automated-tests/src/dali-toolkit/dali-toolkit-test-utils/toolkit-imf-manager.h

   1 #ifndef __DALI_TOOLKIT_TOOLKIT_IMF_MANAGER_H__
   2 #define __DALI_TOOLKIT_TOOLKIT_IMF_MANAGER_H__
   3
   4 /*
   5  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #define __DALI_IMF_MANAGER_H__
  23 #include <dali/public-api/object/base-handle.h>
  24 #include <dali/public-api/signals/dali-signal.h>
  25
  26 namespace Dali DALI_IMPORT_API
  27 {
  28
  29 namespace Internal DALI_INTERNAL
  30 {
  31 namespace Adaptor
  32 {
  33 class ImfManager;
  34 }
  35 }
  36
  37 /**
  38  * @brief The ImfManager class
  39  *
  40  * Specifically manages the ecore input method framework which enables the virtual or hardware keyboards.
  41  */
  42 class ImfManager : public BaseHandle
  43 {
  44 public:
  45
  46   /**
  47    * @brief Events that are generated by the IMF.
  48    */
  49   enum ImfEvent
  50   {
  51     VOID,                ///< No event
  52     PREEDIT,             ///< Pre-Edit changed
  53     COMMIT,              ///< Commit recieved
  54     DELETESURROUNDING,   ///< Event to delete a range of characters from the string
  55     GETSURROUNDING       ///< Event to query string and cursor position
  56   };
  57
  58   /**
  59    * @brief This structure is used to pass on data from the IMF regarding predictive text.
  60    */
  61   struct ImfEventData
  62   {
  63     /**
  64      * @brief Default Constructor.
  65      */
  66     ImfEventData()
  67     : predictiveString(),
  68       eventName( VOID ),
  69       cursorOffset( 0 ),
  70       numberOfChars ( 0 )
  71     {
  72     };
  73
  74     /**
  75      * @brief Constructor
  76      *
  77      * @param[in] aEventName The name of the event from the IMF.
  78      * @param[in] aPredictiveString The pre-edit or commit string.
  79      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
  80      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
  81      */
  82     ImfEventData( ImfEvent aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
  83     : predictiveString( aPredictiveString ),
  84       eventName( aEventName ),
  85       cursorOffset( aCursorOffset ),
  86       numberOfChars( aNumberOfChars )
  87     {
  88     }
  89
  90     // Data
  91     std::string predictiveString; ///< The pre-edit or commit string.
  92     ImfEvent eventName;           ///< The name of the event from the IMF.
  93     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
  94     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
  95   };
  96
  97   /**
  98    * @brief Data required by IMF from the callback
  99    */
 100   struct ImfCallbackData
 101   {
 102     /**
 103      * @brief Constructor
 104      */
 105     ImfCallbackData()
 106     : currentText(),
 107       cursorPosition( 0 ),
 108       update( false ),
 109       preeditResetRequired( false )
 110     {
 111     }
 112
 113     /**
 114      * @brief Constructor
 115      * @param[in] aUpdate True if cursor position needs to be updated
 116      * @param[in] aCursorPosition new position of cursor
 117      * @param[in] aCurrentText current text string
 118      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 119      */
 120     ImfCallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 121     : currentText( aCurrentText ),
 122       cursorPosition( aCursorPosition ),
 123       update( aUpdate ),
 124       preeditResetRequired( aPreeditResetRequired )
 125     {
 126     }
 127
 128     std::string currentText;      ///< current text string
 129     int cursorPosition;           ///< new position of cursor
 130     bool update               :1; ///< if cursor position needs to be updated
 131     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 132   };
 133
 134   typedef Signal< void (ImfManager&) > ImfManagerSignalType; ///< Keyboard actived signal
 135   typedef Signal< ImfCallbackData ( ImfManager&, const ImfEventData& ) > ImfEventSignalType; ///< keyboard events
 136
 137 public:
 138
 139   /**
 140    * @brief Retrieve a handle to the instance of ImfManager.
 141    * @return A handle to the ImfManager.
 142    */
 143   static ImfManager Get();
 144
 145   /**
 146    * @brief Activate the IMF.
 147    *
 148    * It means that the text editing is started at somewhere.
 149    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 150    */
 151   void Activate();
 152
 153   /**
 154    * @brief Deactivate the IMF.
 155    *
 156    * It means that the text editing is finished at somewhere.
 157    */
 158   void Deactivate();
 159
 160   /**
 161    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 162    *
 163    * If true then keyboard will be restored (activated) after focus is regained.
 164    * @return restoration status.
 165    */
 166   bool RestoreAfterFocusLost() const;
 167
 168   /**
 169    * @brief Set status whether the IMF has to restore the keyboard after losing focus.
 170    *
 171    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 172    */
 173   void SetRestoreAfterFocusLost( bool toggle );
 174
 175   /**
 176    * @brief Send message reset the pred-edit state / imf module.
 177    *
 178    * Used to interupt pre-edit state maybe due to a touch input.
 179    */
 180   void Reset();
 181
 182   /**
 183    * @brief Notifies IMF context that the cursor position has changed, required for features like auto-capitalisation.
 184    */
 185   void NotifyCursorPosition();
 186
 187   /**
 188    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 189    *
 190    * @param[in] cursorPosition position of cursor
 191    */
 192   void SetCursorPosition( unsigned int cursorPosition );
 193
 194   /**
 195    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 196    *
 197    * @return current position of cursor
 198    */
 199   unsigned int GetCursorPosition() const;
 200
 201   /**
 202    * @brief Method to store the string required by the IMF, this is used to provide predictive word suggestions.
 203    *
 204    * @param[in] text The text string surrounding the current cursor point.
 205    */
 206   void SetSurroundingText( const std::string& text );
 207
 208   /**
 209    * @brief Gets current text string set within the IMF manager, this is used to offer predictive suggestions.
 210    *
 211    * @return current position of cursor
 212    */
 213   const std::string& GetSurroundingText() const;
 214
 215   /**
 216   * @brief Notifies IMF context that text input is set to multi line or not
 217   */
 218   void NotifyTextInputMultiLine( bool multiLine );
 219
 220 public:
 221
 222   // Signals
 223
 224   /**
 225    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 226    *
 227    * @return The IMF Activated signal.
 228    */
 229   ImfManagerSignalType& ActivatedSignal();
 230
 231   /**
 232    * @brief This is emitted when the IMF manager receives an event from the IMF.
 233    *
 234    * @return The Event signal containing the event data.
 235    */
 236   ImfEventSignalType& EventReceivedSignal();
 237
 238   // Construction & Destruction
 239
 240   /**
 241    * @brief Constructor.
 242    */
 243   ImfManager();
 244
 245   /**
 246    * @brief Destructor
 247    *
 248    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 249    */
 250   ~ImfManager();
 251
 252   /**
 253    * @brief This constructor is used by ImfManager::Get().
 254    *
 255    * @param[in] imfManager A pointer to the imf Manager.
 256    */
 257   explicit ImfManager( Internal::Adaptor::ImfManager* imfManager );
 258 };
 259
 260 } // namespace Dali
 261
 262 #endif // __DALI_TOOLKIT_TOOLKIT_IMF_MANAGER_H__