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