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