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