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 #include <dali/devel-api/adaptor-framework/input-method-options.h>
  26
  27 namespace Dali DALI_IMPORT_API
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 namespace Adaptor
  33 {
  34 class ImfManager;
  35 }
  36 }
  37
  38 /**
  39  * @brief The ImfManager class
  40  *
  41  * Specifically manages the ecore input method framework which enables the virtual or hardware keyboards.
  42  */
  43 class ImfManager : public BaseHandle
  44 {
  45 public:
  46
  47   /**
  48    * @brief Events that are generated by the IMF.
  49    */
  50   enum ImfEvent
  51   {
  52     VOID,                ///< No event
  53     PREEDIT,             ///< Pre-Edit changed
  54     COMMIT,              ///< Commit recieved
  55     DELETESURROUNDING,   ///< Event to delete a range of characters from the string
  56     GETSURROUNDING       ///< Event to query string and cursor position
  57   };
  58
  59   /**
  60    * @brief This structure is used to pass on data from the IMF regarding predictive text.
  61    */
  62   struct ImfEventData
  63   {
  64     /**
  65      * @brief Default Constructor.
  66      */
  67     ImfEventData()
  68     : predictiveString(),
  69       eventName( VOID ),
  70       cursorOffset( 0 ),
  71       numberOfChars ( 0 )
  72     {
  73     };
  74
  75     /**
  76      * @brief Constructor
  77      *
  78      * @param[in] aEventName The name of the event from the IMF.
  79      * @param[in] aPredictiveString The pre-edit or commit string.
  80      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
  81      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
  82      */
  83     ImfEventData( ImfEvent aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
  84     : predictiveString( aPredictiveString ),
  85       eventName( aEventName ),
  86       cursorOffset( aCursorOffset ),
  87       numberOfChars( aNumberOfChars )
  88     {
  89     }
  90
  91     // Data
  92     std::string predictiveString; ///< The pre-edit or commit string.
  93     ImfEvent eventName;           ///< The name of the event from the IMF.
  94     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
  95     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
  96   };
  97
  98   /**
  99    * @brief Data required by IMF from the callback
 100    */
 101   struct ImfCallbackData
 102   {
 103     /**
 104      * @brief Constructor
 105      */
 106     ImfCallbackData()
 107     : currentText(),
 108       cursorPosition( 0 ),
 109       update( false ),
 110       preeditResetRequired( false )
 111     {
 112     }
 113
 114     /**
 115      * @brief Constructor
 116      * @param[in] aUpdate True if cursor position needs to be updated
 117      * @param[in] aCursorPosition new position of cursor
 118      * @param[in] aCurrentText current text string
 119      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 120      */
 121     ImfCallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 122     : currentText( aCurrentText ),
 123       cursorPosition( aCursorPosition ),
 124       update( aUpdate ),
 125       preeditResetRequired( aPreeditResetRequired )
 126     {
 127     }
 128
 129     std::string currentText;      ///< current text string
 130     int cursorPosition;           ///< new position of cursor
 131     bool update               :1; ///< if cursor position needs to be updated
 132     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 133   };
 134
 135   typedef Signal< void (ImfManager&) > ImfManagerSignalType; ///< Keyboard actived signal
 136   typedef Signal< ImfCallbackData ( ImfManager&, const ImfEventData& ) > ImfEventSignalType; ///< keyboard events
 137   typedef Signal< void () > VoidSignalType;
 138   typedef Signal< void (bool) > StatusSignalType;
 139
 140 public:
 141
 142   /**
 143    * @brief Retrieve a handle to the instance of ImfManager.
 144    * @return A handle to the ImfManager.
 145    */
 146   static ImfManager Get();
 147
 148   /**
 149    * @brief Activate the IMF.
 150    *
 151    * It means that the text editing is started at somewhere.
 152    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 153    */
 154   void Activate();
 155
 156   /**
 157    * @brief Deactivate the IMF.
 158    *
 159    * It means that the text editing is finished at somewhere.
 160    */
 161   void Deactivate();
 162
 163   /**
 164    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 165    *
 166    * If true then keyboard will be restored (activated) after focus is regained.
 167    * @return restoration status.
 168    */
 169   bool RestoreAfterFocusLost() const;
 170
 171   /**
 172    * @brief Set status whether the IMF has to restore the keyboard after losing focus.
 173    *
 174    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 175    */
 176   void SetRestoreAfterFocusLost( bool toggle );
 177
 178   /**
 179    * @brief Send message reset the pred-edit state / imf module.
 180    *
 181    * Used to interupt pre-edit state maybe due to a touch input.
 182    */
 183   void Reset();
 184
 185   /**
 186    * @brief Notifies IMF context that the cursor position has changed, required for features like auto-capitalisation.
 187    */
 188   void NotifyCursorPosition();
 189
 190   /**
 191    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 192    *
 193    * @param[in] cursorPosition position of cursor
 194    */
 195   void SetCursorPosition( unsigned int cursorPosition );
 196
 197   /**
 198    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 199    *
 200    * @return current position of cursor
 201    */
 202   unsigned int GetCursorPosition() const;
 203
 204   /**
 205    * @brief Method to store the string required by the IMF, this is used to provide predictive word suggestions.
 206    *
 207    * @param[in] text The text string surrounding the current cursor point.
 208    */
 209   void SetSurroundingText( const std::string& text );
 210
 211   /**
 212    * @brief Gets current text string set within the IMF manager, this is used to offer predictive suggestions.
 213    *
 214    * @return current position of cursor
 215    */
 216   const std::string& GetSurroundingText() const;
 217
 218   /**
 219   * @brief Notifies IMF context that text input is set to multi line or not
 220   */
 221   void NotifyTextInputMultiLine( bool multiLine );
 222
 223   /**
 224    * @brief Set one or more of the Input Method options
 225    * @param[in] options The options to be applied
 226    */
 227   void ApplyOptions( const InputMethodOptions& options );
 228
 229 public:
 230
 231   // Signals
 232
 233   /**
 234    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 235    *
 236    * @return The IMF Activated signal.
 237    */
 238   ImfManagerSignalType& ActivatedSignal();
 239
 240   /**
 241    * @brief This is emitted when the IMF manager receives an event from the IMF.
 242    *
 243    * @return The Event signal containing the event data.
 244    */
 245   ImfEventSignalType& EventReceivedSignal();
 246
 247   /**
 248    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 249    *
 250    * @return The signal connect to status changed event.
 251    */
 252   StatusSignalType& StatusChangedSignal();
 253
 254   /**
 255    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 256    *
 257    * @return The signal to connect to resized event.
 258    */
 259   VoidSignalType& ResizedSignal();
 260
 261   /**
 262    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 263    *
 264    * @return The signal to connect to language changed event.
 265    */
 266   VoidSignalType& LanguageChangedSignal();
 267
 268   // Construction & Destruction
 269
 270   /**
 271    * @brief Constructor.
 272    */
 273   ImfManager();
 274
 275   /**
 276    * @brief Destructor
 277    *
 278    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 279    */
 280   ~ImfManager();
 281
 282   /**
 283    * @brief This constructor is used by ImfManager::Get().
 284    *
 285    * @param[in] imfManager A pointer to the imf Manager.
 286    */
 287   explicit ImfManager( Internal::Adaptor::ImfManager* imfManager );
 288 };
 289
 290 } // namespace Dali
 291
 292 #endif // __DALI_TOOLKIT_TOOLKIT_IMF_MANAGER_H__