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