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 Enumeration for the type of Keyboard.
  81    */
  82   enum KeyboardType
  83   {
  84     SOFTWARE_KEYBOARD,  ///< Software keyboard (Virtual keyboard) is default
  85     HARDWARE_KEYBOARD   ///< Hardware keyboard
  86   };
  87
  88   /**
  89    * @brief This structure is used to pass on data from the IMF regarding predictive text.
  90    */
  91   struct ImfEventData
  92   {
  93     /**
  94      * @brief Default Constructor.
  95      */
  96     ImfEventData()
  97     : predictiveString(),
  98       eventName( VOID ),
  99       cursorOffset( 0 ),
 100       numberOfChars ( 0 )
 101     {
 102     };
 103
 104     /**
 105      * @brief Constructor
 106      *
 107      * @param[in] aEventName The name of the event from the IMF.
 108      * @param[in] aPredictiveString The pre-edit or commit string.
 109      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
 110      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
 111      */
 112     ImfEventData( ImfEvent aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
 113     : predictiveString( aPredictiveString ),
 114       eventName( aEventName ),
 115       cursorOffset( aCursorOffset ),
 116       numberOfChars( aNumberOfChars )
 117     {
 118     }
 119
 120     // Data
 121     std::string predictiveString; ///< The pre-edit or commit string.
 122     ImfEvent eventName;           ///< The name of the event from the IMF.
 123     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
 124     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
 125   };
 126
 127   /**
 128    * @brief Data required by IMF from the callback
 129    */
 130   struct ImfCallbackData
 131   {
 132     /**
 133      * @brief Constructor
 134      */
 135     ImfCallbackData()
 136     : currentText(),
 137       cursorPosition( 0 ),
 138       update( false ),
 139       preeditResetRequired( false )
 140     {
 141     }
 142
 143     /**
 144      * @brief Constructor
 145      * @param[in] aUpdate True if cursor position needs to be updated
 146      * @param[in] aCursorPosition new position of cursor
 147      * @param[in] aCurrentText current text string
 148      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 149      */
 150     ImfCallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 151     : currentText( aCurrentText ),
 152       cursorPosition( aCursorPosition ),
 153       update( aUpdate ),
 154       preeditResetRequired( aPreeditResetRequired )
 155     {
 156     }
 157
 158     std::string currentText;      ///< current text string
 159     int cursorPosition;           ///< new position of cursor
 160     bool update               :1; ///< if cursor position needs to be updated
 161     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 162   };
 163
 164   typedef Signal< void (ImfManager&) > ImfManagerSignalType; ///< Keyboard actived signal
 165   typedef Signal< ImfCallbackData ( ImfManager&, const ImfEventData& ) > ImfEventSignalType; ///< keyboard events
 166   typedef Signal< void () > VoidSignalType;
 167   typedef Signal< void (bool) > StatusSignalType;
 168   typedef Signal< void (KeyboardType) > KeyboardTypeSignalType; ///< keyboard type
 169
 170 public:
 171
 172   /**
 173    * @brief Finalize the IMF.
 174    *
 175    * It means that the context will be deleted.
 176    */
 177   void Finalize();
 178
 179   /**
 180    * @brief Retrieve a handle to the instance of ImfManager.
 181    * @return A handle to the ImfManager.
 182    */
 183   static ImfManager Get();
 184
 185   /**
 186    * @brief Activate the IMF.
 187    *
 188    * It means that the text editing is started at somewhere.
 189    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 190    */
 191   void Activate();
 192
 193   /**
 194    * @brief Deactivate the IMF.
 195    *
 196    * It means that the text editing is finished at somewhere.
 197    */
 198   void Deactivate();
 199
 200   /**
 201    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 202    *
 203    * If true then keyboard will be restored (activated) after focus is regained.
 204    * @return restoration status.
 205    */
 206   bool RestoreAfterFocusLost() const;
 207
 208   /**
 209    * @brief Set status whether the IMF has to restore the keyboard after losing focus.
 210    *
 211    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 212    */
 213   void SetRestoreAfterFocusLost( bool toggle );
 214
 215   /**
 216    * @brief Send message reset the pred-edit state / imf module.
 217    *
 218    * Used to interupt pre-edit state maybe due to a touch input.
 219    */
 220   void Reset();
 221
 222   /**
 223    * @brief Notifies IMF context that the cursor position has changed, required for features like auto-capitalisation.
 224    */
 225   void NotifyCursorPosition();
 226
 227   /**
 228    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 229    *
 230    * @param[in] cursorPosition position of cursor
 231    */
 232   void SetCursorPosition( unsigned int cursorPosition );
 233
 234   /**
 235    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 236    *
 237    * @return current position of cursor
 238    */
 239   unsigned int GetCursorPosition() const;
 240
 241   /**
 242    * @brief Method to store the string required by the IMF, this is used to provide predictive word suggestions.
 243    *
 244    * @param[in] text The text string surrounding the current cursor point.
 245    */
 246   void SetSurroundingText( const std::string& text );
 247
 248   /**
 249    * @brief Gets current text string set within the IMF manager, this is used to offer predictive suggestions.
 250    *
 251    * @return current position of cursor
 252    */
 253   const std::string& GetSurroundingText() const;
 254
 255   /**
 256  * @brief Notifies IMF context that text input is set to multi line or not
 257  *
 258  * @param[in] multiLine True if multiline text input is used
 259  */
 260   void NotifyTextInputMultiLine( bool multiLine );
 261
 262   /**
 263    * @brief Returns text direction of the keyboard's current input language.
 264    * @return The direction of the text.
 265    */
 266   TextDirection GetTextDirection();
 267
 268   /**
 269    * @brief Provides size and position of keyboard.
 270    *
 271    * Position is relative to whether keyboard is visible or not.
 272    * If keyboard is not visible then position will be off the screen.
 273    * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
 274    * the values then taken down.  So ideally GetInputMethodArea() should be called after Show().
 275    * @return rect which is keyboard panel x, y, width, height
 276    */
 277   Dali::Rect<int> GetInputMethodArea();
 278
 279   /**
 280    * @brief Set one or more of the Input Method options
 281    * @param[in] options The options to be applied
 282    */
 283   void ApplyOptions( const InputMethodOptions& options );
 284
 285   /**
 286    * @brief Sets up the input-panel specific data.
 287    * @param[in] data The specific data to be set to the input panel
 288    */
 289   void SetInputPanelData( const std::string& data );
 290
 291   /**
 292    * @brief Gets the specific data of the current active input panel.
 293    *
 294    * Input Panel Data is not always the data which is set by SetInputPanelData().
 295    * Data can be changed internally in the input panel.
 296    * It is just used to get a specific data from the input panel to an application.
 297    * @param[in] data The specific data to be got from the input panel
 298    */
 299   void GetInputPanelData( std::string& data );
 300
 301   /**
 302    * @brief Gets the state of the current active input panel.
 303    * @return The state of the input panel.
 304    */
 305   State GetInputPanelState();
 306
 307   /**
 308    * @brief Sets the return key on the input panel to be visible or invisible.
 309    *
 310    * The default is true.
 311    * @param[in] visible True if the return key is visible(enabled), false otherwise.
 312    */
 313   void SetReturnKeyState( bool visible );
 314
 315   /**
 316    * @brief Enable to show the input panel automatically when focused.
 317    * @param[in] enabled If true, the input panel will be shown when focused
 318    */
 319   void AutoEnableInputPanel( bool enabled );
 320
 321   /**
 322    * @brief Shows the input panel.
 323    */
 324   void ShowInputPanel();
 325
 326   /**
 327    * @brief Hides the input panel.
 328    */
 329   void HideInputPanel();
 330
 331   /**
 332    * @brief Gets the keyboard type.
 333    *
 334    * The default keyboard type is SOFTWARE_KEYBOARD.
 335    * @return The keyboard type
 336    */
 337   KeyboardType GetKeyboardType();
 338
 339   /**
 340    * @brief Gets the current language locale of the input panel.
 341    *
 342    * ex) en_US, en_GB, en_PH, fr_FR, ...
 343    * @return The current language locale of the input panel
 344    */
 345   std::string GetInputPanelLocale();
 346
 347 public:
 348
 349   // Signals
 350
 351   /**
 352    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 353    *
 354    * @return The IMF Activated signal.
 355    */
 356   ImfManagerSignalType& ActivatedSignal();
 357
 358   /**
 359    * @brief This is emitted when the IMF manager receives an event from the IMF.
 360    *
 361    * @return The Event signal containing the event data.
 362    */
 363   ImfEventSignalType& EventReceivedSignal();
 364
 365   /**
 366    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 367    *
 368    * A callback of the following type may be connected:
 369    * @code
 370    *   void YourCallbackName(bool keyboardShown);
 371    * @endcode
 372    * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
 373    * has just been hidden.
 374    * @return The signal to connect to.
 375    */
 376   StatusSignalType& StatusChangedSignal();
 377
 378   /**
 379    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 380    *
 381    * A callback of the following type may be connected:
 382    * @code
 383    *   void YourCallbackName();
 384    * @endcode
 385    * User can get changed size by using GetInputMethodArea() in the callback
 386    * @return The signal to connect to.
 387    */
 388   VoidSignalType& ResizedSignal();
 389
 390   /**
 391    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 392    *
 393    * A callback of the following type may be connected:
 394    * @code
 395    *   void YourCallbackName();
 396    * @endcode
 397    * User can get the text direction of the language by calling GetTextDirection() in the callback.
 398    * @return The signal to connect to.
 399    */
 400   VoidSignalType& LanguageChangedSignal();
 401
 402   /**
 403    * @brief Connect to this signal to be notified when the keyboard type is changed.
 404    *
 405    * A callback of the following type may be connected:
 406    * @code
 407    *   void YourCallbackName( KeyboardType keyboard );
 408    * @endcode
 409    *
 410    * @return The signal to connect to.
 411    */
 412   KeyboardTypeSignalType& KeyboardTypeChangedSignal();
 413
 414   // Construction & Destruction
 415
 416   /**
 417    * @brief Constructor.
 418    */
 419   ImfManager();
 420
 421   /**
 422    * @brief Destructor
 423    *
 424    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 425    */
 426   ~ImfManager();
 427
 428   /**
 429    * @brief This constructor is used by ImfManager::Get().
 430    *
 431    * @param[in] imfManager A pointer to the imf Manager.
 432    */
 433   explicit DALI_INTERNAL ImfManager( Internal::Adaptor::ImfManager* imfManager );
 434 };
 435
 436 } // namespace Dali
 437
 438 #endif // __DALI_IMF_MANAGER_H__