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   typedef Signal< void ( const std::string&, const std::string&, const std::string& ) > ContentReceivedSignalType; ///< Content received signal
 181
 182 public:
 183
 184   /**
 185    * @brief Retrieve a handle to the instance of InputMethodContext.
 186    * @return A handle to the InputMethodContext.
 187    * @brief Constructor.
 188    */
 189   InputMethodContext();
 190
 191   /**
 192    * @brief Destructor
 193    *
 194    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 195    */
 196   ~InputMethodContext();
 197
 198   /**
 199    * @brief Create a new instance of an InputMethodContext.
 200    */
 201   static InputMethodContext New();
 202
 203   /**
 204    * @brief Copy constructor.
 205    *
 206    * @param[in] inputMethodContext InputMethodContext to copy. The copied inputMethodContext will point at the same implementation.
 207    */
 208  InputMethodContext( const InputMethodContext& inputMethodContext );
 209
 210   /**
 211    * @brief Assignment operator.
 212    *
 213    * @param[in] inputMethodContext The InputMethodContext to assign from.
 214    * @return The updated InputMethodContext.
 215    */
 216  InputMethodContext& operator=( const InputMethodContext& inputMethodContext );
 217
 218   /**
 219    * @brief Downcast a handle to InputMethodContext handle.
 220    *
 221    * If handle points to an InputMethodContext the downcast produces valid
 222    * handle. If not the returned handle is left uninitialized.
 223    *
 224    * @param[in] handle Handle to an object.
 225    * @return Handle to an InputMethodContext or an uninitialized handle.
 226    */
 227   static InputMethodContext DownCast( BaseHandle handle );
 228
 229 public:
 230
 231   /**
 232    * @brief Finalize the InputMethodContext.
 233    *
 234    * It means that the context will be deleted.
 235    */
 236   void Finalize();
 237
 238   /**
 239    * @brief Activate the InputMethodContext.
 240    *
 241    * It means that the text editing is started at somewhere.
 242    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 243    */
 244   void Activate();
 245
 246   /**
 247    * @brief Deactivate the InputMethodContext.
 248    *
 249    * It means that the text editing is finished at somewhere.
 250    */
 251   void Deactivate();
 252
 253   /**
 254    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 255    *
 256    * If true then keyboard will be restored (activated) after focus is regained.
 257    * @return restoration status.
 258    */
 259   bool RestoreAfterFocusLost() const;
 260
 261   /**
 262    * @brief Set status whether the InputMethodContext has to restore the keyboard after losing focus.
 263    *
 264    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 265    */
 266   void SetRestoreAfterFocusLost( bool toggle );
 267
 268   /**
 269    * @brief Send message reset the pred-edit state / InputMethodContext module.
 270    *
 271    * Used to interupt pre-edit state maybe due to a touch input.
 272    */
 273   void Reset();
 274
 275   /**
 276    * @brief Notifies InputMethodContext that the cursor position has changed, required for features like auto-capitalisation.
 277    */
 278   void NotifyCursorPosition();
 279
 280   /**
 281    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
 282    *
 283    * @param[in] cursorPosition position of cursor
 284    */
 285   void SetCursorPosition( unsigned int cursorPosition );
 286
 287   /**
 288    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
 289    *
 290    * @return current position of cursor
 291    */
 292   unsigned int GetCursorPosition() const;
 293
 294   /**
 295    * @brief Method to store the string required by the InputMethodContext, this is used to provide predictive word suggestions.
 296    *
 297    * @param[in] text The text string surrounding the current cursor point.
 298    */
 299   void SetSurroundingText( const std::string& text );
 300
 301   /**
 302    * @brief Gets current text string set within the InputMethodContext manager, this is used to offer predictive suggestions.
 303    *
 304    * @return current position of cursor
 305    */
 306   const std::string& GetSurroundingText() const;
 307
 308   /**
 309  * @brief Notifies InputMethodContext that text input is set to multi line or not
 310  *
 311  * @param[in] multiLine True if multiline text input is used
 312  */
 313   void NotifyTextInputMultiLine( bool multiLine );
 314
 315   /**
 316    * @brief Returns text direction of the keyboard's current input language.
 317    * @return The direction of the text.
 318    */
 319   TextDirection GetTextDirection();
 320
 321   /**
 322    * @brief Provides size and position of keyboard.
 323    *
 324    * Position is relative to whether keyboard is visible or not.
 325    * If keyboard is not visible then position will be off the screen.
 326    * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
 327    * the values then taken down.  So ideally GetInputMethodArea() should be called after Show().
 328    * @return rect which is keyboard panel x, y, width, height
 329    */
 330   Dali::Rect<int> GetInputMethodArea();
 331
 332   /**
 333    * @brief Set one or more of the Input Method options
 334    * @param[in] options The options to be applied
 335    */
 336   void ApplyOptions( const InputMethodOptions& options );
 337
 338   /**
 339    * @brief Sets up the input-panel specific data.
 340    * @param[in] data The specific data to be set to the input panel
 341    */
 342   void SetInputPanelData( const std::string& data );
 343
 344   /**
 345    * @brief Gets the specific data of the current active input panel.
 346    *
 347    * Input Panel Data is not always the data which is set by SetInputPanelData().
 348    * Data can be changed internally in the input panel.
 349    * It is just used to get a specific data from the input panel to an application.
 350    * @param[in] data The specific data to be got from the input panel
 351    */
 352   void GetInputPanelData( std::string& data );
 353
 354   /**
 355    * @brief Gets the state of the current active input panel.
 356    * @return The state of the input panel.
 357    */
 358   State GetInputPanelState();
 359
 360   /**
 361    * @brief Sets the return key on the input panel to be visible or invisible.
 362    *
 363    * The default is true.
 364    * @param[in] visible True if the return key is visible(enabled), false otherwise.
 365    */
 366   void SetReturnKeyState( bool visible );
 367
 368   /**
 369    * @brief Enable to show the input panel automatically when focused.
 370    * @param[in] enabled If true, the input panel will be shown when focused
 371    */
 372   void AutoEnableInputPanel( bool enabled );
 373
 374   /**
 375    * @brief Shows the input panel.
 376    */
 377   void ShowInputPanel();
 378
 379   /**
 380    * @brief Hides the input panel.
 381    */
 382   void HideInputPanel();
 383
 384   /**
 385    * @brief Gets the keyboard type.
 386    *
 387    * The default keyboard type is SOFTWARE_KEYBOARD.
 388    * @return The keyboard type
 389    */
 390   KeyboardType GetKeyboardType();
 391
 392   /**
 393    * @brief Gets the current language locale of the input panel.
 394    *
 395    * ex) en_US, en_GB, en_PH, fr_FR, ...
 396    * @return The current language locale of the input panel
 397    */
 398   std::string GetInputPanelLocale();
 399
 400   /**
 401    * @brief Sets the allowed MIME Types to deliver to the input panel.
 402    *
 403    * ex) std::string mimeTypes = "text/plain,image/png,image/gif,application/pdf";
 404    *
 405    * You can receive a media content URI and its MIME type from ContentReceivedSignal(). @see ContentReceivedSignal
 406    * @param[in] mimeTypes The allowed MIME types
 407    */
 408   void SetContentMIMETypes( const std::string& mimeTypes );
 409
 410   /**
 411    * @brief Process event key down or up, whether filter a key to isf.
 412    *
 413    * @param[in] keyEvent The event key to be handled.
 414    * @return Whether the event key is handled.
 415    */
 416   bool FilterEventKey( const Dali::KeyEvent& keyEvent );
 417
 418   /**
 419    * @brief Sets whether the IM context should allow to use the text prediction.
 420    *
 421    * @param[in] prediction Whether to allow text prediction or not.
 422    */
 423   void AllowTextPrediction( bool prediction );
 424
 425   /**
 426    * @brief Gets whether the IM context allow to use the text prediction.
 427    *
 428    * @return Whether the IM allow text prediction or not.
 429    */
 430   bool IsTextPredictionAllowed() const;
 431
 432   /**
 433    * @brief Sets the language of the input panel.
 434    *
 435    * This method can be used when you want to show the English keyboard.
 436    * @param[in] language The language to be set to the input panel
 437    */
 438   void SetInputPanelLanguage( InputPanelLanguage language );
 439
 440   /**
 441    * @brief Gets the language of the input panel.
 442    *
 443    * @return The language of the input panel
 444    */
 445   InputPanelLanguage GetInputPanelLanguage() const;
 446
 447 public:
 448
 449   // Signals
 450
 451   /**
 452    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 453    *
 454    * @return The InputMethodContext Activated signal.
 455    */
 456   ActivatedSignalType& ActivatedSignal();
 457
 458   /**
 459    * @brief This is emitted when the InputMethodContext manager receives an event from the InputMethodContext.
 460    *
 461    * @return The Event signal containing the event data.
 462    */
 463   KeyboardEventSignalType& EventReceivedSignal();
 464
 465   /**
 466    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 467    *
 468    * A callback of the following type may be connected:
 469    * @code
 470    *   void YourCallbackName(bool keyboardShown);
 471    * @endcode
 472    * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
 473    * has just been hidden.
 474    * @return The signal to connect to.
 475    */
 476   StatusSignalType& StatusChangedSignal();
 477
 478   /**
 479    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 480    *
 481    * A callback of the following type may be connected:
 482    * @code
 483    *   void YourCallbackName( int resolvedResize );
 484    * @endcode
 485    * The parameter sends the resolved resize defined by the InputMethodContext.
 486    *
 487    * User can get changed size by using GetInputMethodArea() in the callback
 488    * @return The signal to connect to.
 489    */
 490   KeyboardResizedSignalType& ResizedSignal();
 491
 492   /**
 493    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 494    *
 495    * A callback of the following type may be connected:
 496    * @code
 497    *   void YourCallbackName( int resolvedLanguage );
 498    * @endcode
 499    * The parameter sends the resolved language defined by the InputMethodContext.
 500    *
 501    * User can get the text direction of the language by calling GetTextDirection() in the callback.
 502    * @return The signal to connect to.
 503    */
 504   LanguageChangedSignalType& LanguageChangedSignal();
 505
 506   /**
 507    * @brief Connect to this signal to be notified when the keyboard type is changed.
 508    *
 509    * A callback of the following type may be connected:
 510    * @code
 511    *   void YourCallbackName( KeyboardType keyboard );
 512    * @endcode
 513    *
 514    * @return The signal to connect to.
 515    */
 516   KeyboardTypeSignalType& KeyboardTypeChangedSignal();
 517
 518   /**
 519    * @brief Connect to this signal to be notified when the content, such as images, of input method is received.
 520    *
 521    * A callback of the following type may be connected:
 522    * @code
 523    *   void YourCallbackName( const std::string& contentUri, const std::string& description, const std::string& contentMIMEType );
 524    * @endcode
 525    *
 526    * @return The signal to connect to.
 527    */
 528   ContentReceivedSignalType& ContentReceivedSignal();
 529
 530 public:
 531
 532   /**
 533    * @brief This constructor is used by InputMethodContext::New().
 534    *
 535    * @param[in] inputMethodContext A pointer to the InputMethodContext.
 536    */
 537   explicit DALI_INTERNAL InputMethodContext( Internal::Adaptor::InputMethodContext* inputMethodContext );
 538
 539 };
 540
 541
 542
 543 } // namespace Dali
 544
 545 #endif // DALI_INPUT_METHOD_CONTEXT_H