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