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