adaptors/devel-api/adaptor-framework/imf-manager.h

   1 #ifndef __DALI_IMF_MANAGER_H__
   2 #define __DALI_IMF_MANAGER_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/signals/dali-signal.h>
  24 #include "input-method-options.h"
  25
  26 namespace Dali
  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 DALI_IMPORT_API ImfManager : public BaseHandle
  43 {
  44 public:
  45
  46   /**
  47   * @brief The direction of text.
  48   */
  49   enum TextDirection
  50   {
  51     LeftToRight,
  52     RightToLeft,
  53   };
  54
  55   /**
  56    * @brief Events that are generated by the IMF.
  57    */
  58   enum ImfEvent
  59   {
  60     VOID,                ///< No event
  61     PREEDIT,             ///< Pre-Edit changed
  62     COMMIT,              ///< Commit recieved
  63     DELETESURROUNDING,   ///< Event to delete a range of characters from the string
  64     GETSURROUNDING,      ///< Event to query string and cursor position
  65     PRIVATECOMMAND       ///< Private command sent from the input panel
  66   };
  67
  68   /**
  69    * @brief Enumeration for state of the input panel.
  70    */
  71   enum State
  72   {
  73     DEFAULT = 0,   ///< Unknown state
  74     SHOW,          ///< Input panel is shown
  75     HIDE,          ///< Input panel is hidden
  76     WILL_SHOW      ///< Input panel in process of being shown
  77   };
  78
  79   /**
  80    * @brief This structure is used to pass on data from the IMF regarding predictive text.
  81    */
  82   struct ImfEventData
  83   {
  84     /**
  85      * @brief Default Constructor.
  86      */
  87     ImfEventData()
  88     : predictiveString(),
  89       eventName( VOID ),
  90       cursorOffset( 0 ),
  91       numberOfChars ( 0 )
  92     {
  93     };
  94
  95     /**
  96      * @brief Constructor
  97      *
  98      * @param[in] aEventName The name of the event from the IMF.
  99      * @param[in] aPredictiveString The pre-edit or commit string.
 100      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
 101      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
 102      */
 103     ImfEventData( ImfEvent aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
 104     : predictiveString( aPredictiveString ),
 105       eventName( aEventName ),
 106       cursorOffset( aCursorOffset ),
 107       numberOfChars( aNumberOfChars )
 108     {
 109     }
 110
 111     // Data
 112     std::string predictiveString; ///< The pre-edit or commit string.
 113     ImfEvent eventName;           ///< The name of the event from the IMF.
 114     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
 115     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
 116   };
 117
 118   /**
 119    * @brief Data required by IMF from the callback
 120    */
 121   struct ImfCallbackData
 122   {
 123     /**
 124      * @brief Constructor
 125      */
 126     ImfCallbackData()
 127     : currentText(),
 128       cursorPosition( 0 ),
 129       update( false ),
 130       preeditResetRequired( false )
 131     {
 132     }
 133
 134     /**
 135      * @brief Constructor
 136      * @param[in] aUpdate True if cursor position needs to be updated
 137      * @param[in] aCursorPosition new position of cursor
 138      * @param[in] aCurrentText current text string
 139      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 140      */
 141     ImfCallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 142     : currentText( aCurrentText ),
 143       cursorPosition( aCursorPosition ),
 144       update( aUpdate ),
 145       preeditResetRequired( aPreeditResetRequired )
 146     {
 147     }
 148
 149     std::string currentText;      ///< current text string
 150     int cursorPosition;           ///< new position of cursor
 151     bool update               :1; ///< if cursor position needs to be updated
 152     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 153   };
 154
 155   typedef Signal< void (ImfManager&) > ImfManagerSignalType; ///< Keyboard actived signal
 156   typedef Signal< ImfCallbackData ( ImfManager&, const ImfEventData& ) > ImfEventSignalType; ///< keyboard events
 157   typedef Signal< void () > VoidSignalType;
 158   typedef Signal< void (bool) > StatusSignalType;
 159
 160 public:
 161
 162   /**
 163    * @brief Retrieve a handle to the instance of ImfManager.
 164    * @return A handle to the ImfManager.
 165    */
 166   static ImfManager Get();
 167
 168   /**
 169    * @brief Activate the IMF.
 170    *
 171    * It means that the text editing is started at somewhere.
 172    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 173    */
 174   void Activate();
 175
 176   /**
 177    * @brief Deactivate the IMF.
 178    *
 179    * It means that the text editing is finished at somewhere.
 180    */
 181   void Deactivate();
 182
 183   /**
 184    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 185    *
 186    * If true then keyboard will be restored (activated) after focus is regained.
 187    * @return restoration status.
 188    */
 189   bool RestoreAfterFocusLost() const;
 190
 191   /**
 192    * @brief Set status whether the IMF has to restore the keyboard after losing focus.
 193    *
 194    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 195    */
 196   void SetRestoreAfterFocusLost( bool toggle );
 197
 198   /**
 199    * @brief Send message reset the pred-edit state / imf module.
 200    *
 201    * Used to interupt pre-edit state maybe due to a touch input.
 202    */
 203   void Reset();
 204
 205   /**
 206    * @brief Notifies IMF context that the cursor position has changed, required for features like auto-capitalisation.
 207    */
 208   void NotifyCursorPosition();
 209
 210   /**
 211    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 212    *
 213    * @param[in] cursorPosition position of cursor
 214    */
 215   void SetCursorPosition( unsigned int cursorPosition );
 216
 217   /**
 218    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 219    *
 220    * @return current position of cursor
 221    */
 222   unsigned int GetCursorPosition() const;
 223
 224   /**
 225    * @brief Method to store the string required by the IMF, this is used to provide predictive word suggestions.
 226    *
 227    * @param[in] text The text string surrounding the current cursor point.
 228    */
 229   void SetSurroundingText( const std::string& text );
 230
 231   /**
 232    * @brief Gets current text string set within the IMF manager, this is used to offer predictive suggestions.
 233    *
 234    * @return current position of cursor
 235    */
 236   const std::string& GetSurroundingText() const;
 237
 238   /**
 239  * @brief Notifies IMF context that text input is set to multi line or not
 240  *
 241  * @param[in] multiLine True if multiline text input is used
 242  */
 243   void NotifyTextInputMultiLine( bool multiLine );
 244
 245   /**
 246    * @brief Returns text direction of the keyboard's current input language.
 247    * @return The direction of the text.
 248    */
 249   TextDirection GetTextDirection();
 250
 251   /**
 252    * @brief Provides size and position of keyboard.
 253    *
 254    * Position is relative to whether keyboard is visible or not.
 255    * If keyboard is not visible then position will be off the screen.
 256    * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
 257    * the values then taken down.  So ideally GetInputMethodArea() should be called after Show().
 258    * @return rect which is keyboard panel x, y, width, height
 259    */
 260   Dali::Rect<int> GetInputMethodArea();
 261
 262   /**
 263    * @brief Set one or more of the Input Method options
 264    * @param[in] options The options to be applied
 265    */
 266   void ApplyOptions( const InputMethodOptions& options );
 267
 268   /**
 269    * @brief Sets up the input-panel specific data.
 270    * @param[in] data The specific data to be set to the input panel
 271    */
 272   void SetInputPanelUserData( const std::string& data );
 273
 274   /**
 275    * @brief Gets the specific data of the current active input panel.
 276    * @param[in] data The specific data to be got from the input panel
 277    */
 278   void GetInputPanelUserData( std::string& data );
 279
 280   /**
 281    * @brief Gets the state of the current active input panel.
 282    * @return The state of the input panel.
 283    */
 284   State GetInputPanelState();
 285
 286   /**
 287    * @brief Sets the return key on the input panel to be visible or invisible.
 288    *
 289    * The default is true.
 290    * @param[in] visible True if the return key is visible(enabled), false otherwise.
 291    */
 292   void SetReturnKeyState( bool visible );
 293
 294   /**
 295    * @brief Enable to show the input panel automatically when focused.
 296    * @param[in] enabled If true, the input panel will be shown when focused
 297    */
 298   void AutoEnableInputPanel( bool enabled );
 299
 300   /**
 301    * @brief Shows the input panel.
 302    */
 303   void ShowInputPanel();
 304
 305   /**
 306    * @brief Hides the input panel.
 307    */
 308   void HideInputPanel();
 309
 310 public:
 311
 312   // Signals
 313
 314   /**
 315    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 316    *
 317    * @return The IMF Activated signal.
 318    */
 319   ImfManagerSignalType& ActivatedSignal();
 320
 321   /**
 322    * @brief This is emitted when the IMF manager receives an event from the IMF.
 323    *
 324    * @return The Event signal containing the event data.
 325    */
 326   ImfEventSignalType& EventReceivedSignal();
 327
 328   /**
 329    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 330    *
 331    * A callback of the following type may be connected:
 332    * @code
 333    *   void YourCallbackName(bool keyboardShown);
 334    * @endcode
 335    * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
 336    * has just been hidden.
 337    * @return The signal to connect to.
 338    */
 339   StatusSignalType& StatusChangedSignal();
 340
 341   /**
 342    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 343    *
 344    * A callback of the following type may be connected:
 345    * @code
 346    *   void YourCallbackName();
 347    * @endcode
 348    * User can get changed size by using GetInputMethodArea() in the callback
 349    * @return The signal to connect to.
 350    */
 351   VoidSignalType& ResizedSignal();
 352
 353   /**
 354    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 355    *
 356    * A callback of the following type may be connected:
 357    * @code
 358    *   void YourCallbackName();
 359    * @endcode
 360    * User can get the text direction of the language by calling GetTextDirection() in the callback.
 361    * @return The signal to connect to.
 362    */
 363   VoidSignalType& LanguageChangedSignal();
 364
 365   // Construction & Destruction
 366
 367   /**
 368    * @brief Constructor.
 369    */
 370   ImfManager();
 371
 372   /**
 373    * @brief Destructor
 374    *
 375    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 376    */
 377   ~ImfManager();
 378
 379   /**
 380    * @brief This constructor is used by ImfManager::Get().
 381    *
 382    * @param[in] imfManager A pointer to the imf Manager.
 383    */
 384   explicit DALI_INTERNAL ImfManager( Internal::Adaptor::ImfManager* imfManager );
 385 };
 386
 387 } // namespace Dali
 388
 389 #endif // __DALI_IMF_MANAGER_H__