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