dali/devel-api/adaptor-framework/input-method-context.h

   1 #ifndef __DALI_INPUT_METHOD_CONTEXT_H__
   2 #define __DALI_INPUT_METHOD_CONTEXT_H__
   3
   4 /*
   5  * Copyright (c) 2018 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/events/key-event.h>
  23
  24 // EXTERNAL INCLUDES
  25 #include <dali/public-api/object/base-handle.h>
  26 #include <dali/public-api/signals/dali-signal.h>
  27 #include <dali/devel-api/adaptor-framework/input-method-options.h>
  28
  29 namespace Dali
  30 {
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 namespace Adaptor
  35 {
  36 class InputMethodContext;
  37 }
  38 }
  39
  40 /**
  41  * @brief The InputMethodContext class
  42  *
  43  * Specifically manages the ecore input method framework which enables the virtual or hardware keyboards.
  44  */
  45
  46 class DALI_ADAPTOR_API InputMethodContext : public BaseHandle
  47 {
  48 public:
  49
  50   /**
  51   * @brief The direction of text.
  52   */
  53   enum TextDirection
  54   {
  55     LeftToRight,
  56     RightToLeft,
  57   };
  58
  59   /**
  60    * @brief Events that are generated by the InputMethodContext.
  61    */
  62   enum EventType
  63   {
  64     VOID,                ///< No event
  65     PRE_EDIT,             ///< Pre-Edit changed
  66     COMMIT,              ///< Commit recieved
  67     DELETE_SURROUNDING,   ///< Event to delete a range of characters from the string
  68     GET_SURROUNDING,      ///< Event to query string and cursor position
  69     PRIVATE_COMMAND       ///< Private command sent from the input panel
  70   };
  71
  72   /**
  73    * @brief Enumeration for state of the input panel.
  74    */
  75   enum State
  76   {
  77     DEFAULT = 0,   ///< Unknown state
  78     SHOW,          ///< Input panel is shown
  79     HIDE,          ///< Input panel is hidden
  80     WILL_SHOW      ///< Input panel in process of being shown
  81   };
  82
  83   /**
  84    * @brief Enumeration for the type of Keyboard.
  85    */
  86   enum KeyboardType
  87   {
  88     SOFTWARE_KEYBOARD,  ///< Software keyboard (Virtual keyboard) is default
  89     HARDWARE_KEYBOARD   ///< Hardware keyboard
  90   };
  91
  92   /**
  93    * @brief This structure is used to pass on data from the InputMethodContext regarding predictive text.
  94    */
  95   struct EventData
  96   {
  97     /**
  98      * @brief Default Constructor.
  99      */
 100     EventData()
 101     : predictiveString(),
 102       eventName( VOID ),
 103       cursorOffset( 0 ),
 104       numberOfChars ( 0 )
 105     {
 106     };
 107
 108     /**
 109      * @brief Constructor
 110      *
 111      * @param[in] aEventName The name of the event from the InputMethodContext.
 112      * @param[in] aPredictiveString The pre-edit or commit string.
 113      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
 114      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
 115      */
 116     EventData( EventType aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
 117     : predictiveString( aPredictiveString ),
 118       eventName( aEventName ),
 119       cursorOffset( aCursorOffset ),
 120       numberOfChars( aNumberOfChars )
 121     {
 122     }
 123
 124     // Data
 125     std::string predictiveString; ///< The pre-edit or commit string.
 126     EventType eventName;           ///< The name of the event from the InputMethodContext.
 127     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
 128     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
 129   };
 130
 131   /**
 132    * @brief Data required by InputMethodContext from the callback
 133    */
 134   struct CallbackData
 135   {
 136     /**
 137      * @brief Constructor
 138      */
 139     CallbackData()
 140     : currentText(),
 141       cursorPosition( 0 ),
 142       update( false ),
 143       preeditResetRequired( false )
 144     {
 145     }
 146
 147     /**
 148      * @brief Constructor
 149      * @param[in] aUpdate True if cursor position needs to be updated
 150      * @param[in] aCursorPosition new position of cursor
 151      * @param[in] aCurrentText current text string
 152      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 153      */
 154     CallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 155     : currentText( aCurrentText ),
 156       cursorPosition( aCursorPosition ),
 157       update( aUpdate ),
 158       preeditResetRequired( aPreeditResetRequired )
 159     {
 160     }
 161
 162     std::string currentText;      ///< current text string
 163     int cursorPosition;           ///< new position of cursor
 164     bool update               :1; ///< if cursor position needs to be updated
 165     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 166   };
 167
 168   typedef Signal< void (InputMethodContext&) > ActivatedSignalType; ///< Keyboard actived signal
 169   typedef Signal< CallbackData ( InputMethodContext&, const EventData& ) > KeyboardEventSignalType; ///< keyboard events
 170   typedef Signal< void () > VoidSignalType;
 171   typedef Signal< void ( bool ) > StatusSignalType;
 172   typedef Signal< void ( KeyboardType ) > KeyboardTypeSignalType; ///< keyboard type
 173   typedef Signal< void ( int ) > KeyboardResizedSignalType;  ///< Keyboard resized signal
 174   typedef Signal< void ( int ) > LanguageChangedSignalType;  ///< Language changed signal
 175
 176 public:
 177
 178   /**
 179    * @brief Retrieve a handle to the instance of InputMethodContext.
 180    * @return A handle to the InputMethodContext.
 181    * @brief Constructor.
 182    */
 183   InputMethodContext();
 184
 185   /**
 186    * @brief Destructor
 187    *
 188    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 189    */
 190   ~InputMethodContext();
 191
 192   /**
 193    * @brief Create a new instance of an InputMethodContext.
 194    */
 195   static InputMethodContext New();
 196
 197   /**
 198    * @brief Copy constructor.
 199    *
 200    * @param[in] inputMethodContext InputMethodContext to copy. The copied inputMethodContext will point at the same implementation.
 201    */
 202  InputMethodContext( const InputMethodContext& inputMethodContext );
 203
 204   /**
 205    * @brief Assignment operator.
 206    *
 207    * @param[in] inputMethodContext The InputMethodContext to assign from.
 208    * @return The updated InputMethodContext.
 209    */
 210  InputMethodContext& operator=( const InputMethodContext& inputMethodContext );
 211
 212   /**
 213    * @brief Downcast a handle to InputMethodContext handle.
 214    *
 215    * If handle points to an InputMethodContext the downcast produces valid
 216    * handle. If not the returned handle is left uninitialized.
 217    *
 218    * @param[in] handle Handle to an object.
 219    * @return Handle to an InputMethodContext or an uninitialized handle.
 220    */
 221   static InputMethodContext DownCast( BaseHandle handle );
 222
 223 public:
 224
 225   /**
 226    * @brief Finalize the InputMethodContext.
 227    *
 228    * It means that the context will be deleted.
 229    */
 230   void Finalize();
 231
 232   /**
 233    * @brief Activate the InputMethodContext.
 234    *
 235    * It means that the text editing is started at somewhere.
 236    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 237    */
 238   void Activate();
 239
 240   /**
 241    * @brief Deactivate the InputMethodContext.
 242    *
 243    * It means that the text editing is finished at somewhere.
 244    */
 245   void Deactivate();
 246
 247   /**
 248    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 249    *
 250    * If true then keyboard will be restored (activated) after focus is regained.
 251    * @return restoration status.
 252    */
 253   bool RestoreAfterFocusLost() const;
 254
 255   /**
 256    * @brief Set status whether the InputMethodContext has to restore the keyboard after losing focus.
 257    *
 258    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 259    */
 260   void SetRestoreAfterFocusLost( bool toggle );
 261
 262   /**
 263    * @brief Send message reset the pred-edit state / InputMethodContext module.
 264    *
 265    * Used to interupt pre-edit state maybe due to a touch input.
 266    */
 267   void Reset();
 268
 269   /**
 270    * @brief Notifies InputMethodContext that the cursor position has changed, required for features like auto-capitalisation.
 271    */
 272   void NotifyCursorPosition();
 273
 274   /**
 275    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
 276    *
 277    * @param[in] cursorPosition position of cursor
 278    */
 279   void SetCursorPosition( unsigned int cursorPosition );
 280
 281   /**
 282    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
 283    *
 284    * @return current position of cursor
 285    */
 286   unsigned int GetCursorPosition() const;
 287
 288   /**
 289    * @brief Method to store the string required by the InputMethodContext, this is used to provide predictive word suggestions.
 290    *
 291    * @param[in] text The text string surrounding the current cursor point.
 292    */
 293   void SetSurroundingText( const std::string& text );
 294
 295   /**
 296    * @brief Gets current text string set within the InputMethodContext manager, this is used to offer predictive suggestions.
 297    *
 298    * @return current position of cursor
 299    */
 300   const std::string& GetSurroundingText() const;
 301
 302   /**
 303  * @brief Notifies InputMethodContext that text input is set to multi line or not
 304  *
 305  * @param[in] multiLine True if multiline text input is used
 306  */
 307   void NotifyTextInputMultiLine( bool multiLine );
 308
 309   /**
 310    * @brief Returns text direction of the keyboard's current input language.
 311    * @return The direction of the text.
 312    */
 313   TextDirection GetTextDirection();
 314
 315   /**
 316    * @brief Provides size and position of keyboard.
 317    *
 318    * Position is relative to whether keyboard is visible or not.
 319    * If keyboard is not visible then position will be off the screen.
 320    * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
 321    * the values then taken down.  So ideally GetInputMethodArea() should be called after Show().
 322    * @return rect which is keyboard panel x, y, width, height
 323    */
 324   Dali::Rect<int> GetInputMethodArea();
 325
 326   /**
 327    * @brief Set one or more of the Input Method options
 328    * @param[in] options The options to be applied
 329    */
 330   void ApplyOptions( const InputMethodOptions& options );
 331
 332   /**
 333    * @brief Sets up the input-panel specific data.
 334    * @param[in] data The specific data to be set to the input panel
 335    */
 336   void SetInputPanelData( const std::string& data );
 337
 338   /**
 339    * @brief Gets the specific data of the current active input panel.
 340    *
 341    * Input Panel Data is not always the data which is set by SetInputPanelData().
 342    * Data can be changed internally in the input panel.
 343    * It is just used to get a specific data from the input panel to an application.
 344    * @param[in] data The specific data to be got from the input panel
 345    */
 346   void GetInputPanelData( std::string& data );
 347
 348   /**
 349    * @brief Gets the state of the current active input panel.
 350    * @return The state of the input panel.
 351    */
 352   State GetInputPanelState();
 353
 354   /**
 355    * @brief Sets the return key on the input panel to be visible or invisible.
 356    *
 357    * The default is true.
 358    * @param[in] visible True if the return key is visible(enabled), false otherwise.
 359    */
 360   void SetReturnKeyState( bool visible );
 361
 362   /**
 363    * @brief Enable to show the input panel automatically when focused.
 364    * @param[in] enabled If true, the input panel will be shown when focused
 365    */
 366   void AutoEnableInputPanel( bool enabled );
 367
 368   /**
 369    * @brief Shows the input panel.
 370    */
 371   void ShowInputPanel();
 372
 373   /**
 374    * @brief Hides the input panel.
 375    */
 376   void HideInputPanel();
 377
 378   /**
 379    * @brief Gets the keyboard type.
 380    *
 381    * The default keyboard type is SOFTWARE_KEYBOARD.
 382    * @return The keyboard type
 383    */
 384   KeyboardType GetKeyboardType();
 385
 386   /**
 387    * @brief Gets the current language locale of the input panel.
 388    *
 389    * ex) en_US, en_GB, en_PH, fr_FR, ...
 390    * @return The current language locale of the input panel
 391    */
 392   std::string GetInputPanelLocale();
 393
 394   /**
 395    * @brief Process event key down or up, whether filter a key to isf.
 396    *
 397    * @param[in] keyEvent The event key to be handled.
 398    * @return Whether the event key is handled.
 399    */
 400   bool FilterEventKey( const Dali::KeyEvent& keyEvent );
 401
 402   /**
 403    * @brief Sets whether the IM context should allow to use the text prediction.
 404    *
 405    * @param[in] prediction Whether to allow text prediction or not.
 406    */
 407   void AllowTextPrediction( bool prediction );
 408
 409   /**
 410    * @brief Gets whether the IM context allow to use the text prediction.
 411    *
 412    * @return Whether the IM allow text prediction or not.
 413    */
 414   bool IsTextPredictionAllowed() const;
 415 public:
 416
 417   // Signals
 418
 419   /**
 420    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 421    *
 422    * @return The InputMethodContext Activated signal.
 423    */
 424   ActivatedSignalType& ActivatedSignal();
 425
 426   /**
 427    * @brief This is emitted when the InputMethodContext manager receives an event from the InputMethodContext.
 428    *
 429    * @return The Event signal containing the event data.
 430    */
 431   KeyboardEventSignalType& EventReceivedSignal();
 432
 433   /**
 434    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 435    *
 436    * A callback of the following type may be connected:
 437    * @code
 438    *   void YourCallbackName(bool keyboardShown);
 439    * @endcode
 440    * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
 441    * has just been hidden.
 442    * @return The signal to connect to.
 443    */
 444   StatusSignalType& StatusChangedSignal();
 445
 446   /**
 447    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 448    *
 449    * A callback of the following type may be connected:
 450    * @code
 451    *   void YourCallbackName( int resolvedResize );
 452    * @endcode
 453    * The parameter sends the resolved resize defined by the InputMethodContext.
 454    *
 455    * User can get changed size by using GetInputMethodArea() in the callback
 456    * @return The signal to connect to.
 457    */
 458   KeyboardResizedSignalType& ResizedSignal();
 459
 460   /**
 461    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 462    *
 463    * A callback of the following type may be connected:
 464    * @code
 465    *   void YourCallbackName( int resolvedLanguage );
 466    * @endcode
 467    * The parameter sends the resolved language defined by the InputMethodContext.
 468    *
 469    * User can get the text direction of the language by calling GetTextDirection() in the callback.
 470    * @return The signal to connect to.
 471    */
 472   LanguageChangedSignalType& LanguageChangedSignal();
 473
 474   /**
 475    * @brief Connect to this signal to be notified when the keyboard type is changed.
 476    *
 477    * A callback of the following type may be connected:
 478    * @code
 479    *   void YourCallbackName( KeyboardType keyboard );
 480    * @endcode
 481    *
 482    * @return The signal to connect to.
 483    */
 484   KeyboardTypeSignalType& KeyboardTypeChangedSignal();
 485
 486 public:
 487
 488   /**
 489    * @brief This constructor is used by InputMethodContext::New().
 490    *
 491    * @param[in] inputMethodContext A pointer to the InputMethodContext.
 492    */
 493   explicit DALI_INTERNAL InputMethodContext( Internal::Adaptor::InputMethodContext* inputMethodContext );
 494
 495 };
 496
 497
 498
 499 } // namespace Dali
 500
 501 #endif // __DALI_INPUT_METHOD_CONTEXT_H__