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