automated-tests/src/dali-toolkit/dali-toolkit-test-utils/toolkit-input-method-context.h

   1 #ifndef DALI_TOOLKIT_TOOLKIT_INPUT_METHOD_CONTEXT_H
   2 #define DALI_TOOLKIT_TOOLKIT_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 #define DALI_INPUT_METHOD_CONTEXT_H
  23 #include <dali/public-api/actors/actor.h>
  24 #include <dali/public-api/object/base-handle.h>
  25 #include <dali/public-api/signals/dali-signal.h>
  26 #include <dali/devel-api/adaptor-framework/input-method-options.h>
  27 #include <dali/public-api/events/key-event.h>
  28
  29 namespace Dali DALI_IMPORT_API
  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 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     SELECTION_SET       ///< input method needs to set the selection
  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 at all times
  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       startIndex ( 0 ),
 147       endIndex ( 0 )
 148     {
 149     };
 150
 151     /**
 152      * @brief Constructor
 153      *
 154      * @param[in] aEventName The name of the event from the input method context.
 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       startIndex ( 0 ),
 165       endIndex ( 0 )
 166     {
 167     }
 168
 169     /**
 170      * @brief Constructor
 171      *
 172      * @param[in] aEventName The name of the event from the InputMethodContext.
 173      * @param[in] aStartIndex The start index of selection.
 174      * @param[in] aEndIndex The end index of selection.
 175      */
 176     EventData(EventType aEventName, int aStartIndex, int aEndIndex)
 177     : predictiveString(),
 178       eventName(aEventName),
 179       cursorOffset(0),
 180       numberOfChars(0),
 181       startIndex(aStartIndex),
 182       endIndex(aEndIndex)
 183     {
 184     }
 185
 186     // Data
 187     std::string predictiveString; ///< The pre-edit or commit string.
 188     EventType eventName;          ///< The name of the event from the input method context.
 189     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
 190     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
 191     int startIndex;               ///< The start index of selection.
 192     int endIndex;                 ///< The end index of selection.
 193   };
 194
 195   /**
 196    * @brief Data required by input method context from the callback
 197    */
 198   struct CallbackData
 199   {
 200     /**
 201      * @brief Constructor
 202      */
 203     CallbackData()
 204     : currentText(),
 205       cursorPosition( 0 ),
 206       update( false ),
 207       preeditResetRequired( false )
 208     {
 209     }
 210
 211     /**
 212      * @brief Constructor
 213      * @param[in] aUpdate True if cursor position needs to be updated
 214      * @param[in] aCursorPosition new position of cursor
 215      * @param[in] aCurrentText current text string
 216      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 217      */
 218     CallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 219     : currentText( aCurrentText ),
 220       cursorPosition( aCursorPosition ),
 221       update( aUpdate ),
 222       preeditResetRequired( aPreeditResetRequired )
 223     {
 224     }
 225
 226     std::string currentText;      ///< current text string
 227     int cursorPosition;           ///< new position of cursor
 228     bool update               :1; ///< if cursor position needs to be updated
 229     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 230   };
 231
 232   typedef Signal< void (InputMethodContext&) > ActivatedSignalType; ///< Keyboard actived signal
 233   typedef Signal< CallbackData ( InputMethodContext&, const EventData& ) > KeyboardEventSignalType; ///< keyboard events
 234   typedef Signal< void () > VoidSignalType;
 235   typedef Signal< void (bool) > StatusSignalType;
 236
 237   using PreEditAttributeDataContainer = Vector< Dali::InputMethodContext::PreeditAttributeData >;
 238
 239 public:
 240
 241   /**
 242    * @brief Create a handle to the instance of InputMethodContext.
 243    * @return A handle to the InputMethodContext.
 244    */
 245   static InputMethodContext New();
 246
 247   /**
 248    * @brief Create a handle to the instance of InputMethodContext.
 249    *
 250    * @param[in] actor The actor that uses the new InputMethodContext instance.
 251    * @return A handle to the InputMethodContext.
 252    */
 253   static InputMethodContext New( Actor actor );
 254
 255   /**
 256    * @brief Finalize the InputMethodContext.
 257    *
 258    * It means that the context will be deleted.
 259    */
 260   void Finalize();
 261
 262   /**
 263    * @brief Activate the input method context.
 264    *
 265    * It means that the text editing is started at somewhere.
 266    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 267    */
 268   void Activate();
 269
 270   /**
 271    * @brief Deactivate the input method context.
 272    *
 273    * It means that the text editing is finished at somewhere.
 274    */
 275   void Deactivate();
 276
 277   /**
 278    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 279    *
 280    * If true then keyboard will be restored (activated) after focus is regained.
 281    * @return restoration status.
 282    */
 283   bool RestoreAfterFocusLost() const;
 284
 285   /**
 286    * @brief Set status whether the input method context has to restore the keyboard after losing focus.
 287    *
 288    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 289    */
 290   void SetRestoreAfterFocusLost( bool toggle );
 291
 292   /**
 293    * @brief Send message reset the pred-edit state / input method context module.
 294    *
 295    * Used to interupt pre-edit state maybe due to a touch input.
 296    */
 297   void Reset();
 298
 299   /**
 300    * @brief Notifies ImfContext that the cursor position has changed, required for features like auto-capitalisation.
 301    */
 302   void NotifyCursorPosition();
 303
 304   /**
 305    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the ImfContext.
 306    *
 307    * @param[in] cursorPosition position of cursor
 308    */
 309   void SetCursorPosition( unsigned int cursorPosition );
 310
 311   /**
 312    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the ImfContext.
 313    *
 314    * @return current position of cursor
 315    */
 316   unsigned int GetCursorPosition() const;
 317
 318   /**
 319    * @brief Method to store the string required by the input method context, this is used to provide predictive word suggestions.
 320    *
 321    * @param[in] text The text string surrounding the current cursor point.
 322    */
 323   void SetSurroundingText( const std::string& text );
 324
 325   /**
 326    * @brief Gets current text string set within the input method context, this is used to offer predictive suggestions.
 327    *
 328    * @return current position of cursor
 329    */
 330   const std::string& GetSurroundingText() const;
 331
 332   /**
 333   * @brief Notifies ImfContext that text input is set to multi line or not
 334   */
 335   void NotifyTextInputMultiLine( bool multiLine );
 336
 337   /**
 338    * @brief Set one or more of the Input Method options
 339    * @param[in] options The options to be applied
 340    */
 341   void ApplyOptions( const InputMethodOptions& options );
 342
 343   /**
 344    * @brief Process event key down or up, whether filter a key to isf.
 345    *
 346    * @param[in] keyEvent The event key to be handled.
 347    * @return Whether the event key is handled.
 348    */
 349   bool FilterEventKey( const Dali::KeyEvent& keyEvent );
 350
 351   /**
 352    * @brief Sets the preedit type.
 353    *
 354    * @param[in] type The preedit style type
 355    */
 356   void SetPreeditStyle( PreeditStyle type );
 357
 358   /**
 359    * @brief Gets the preedit attributes data.
 360    *
 361    * @param[out] attrs The preedit attributes data.
 362    */
 363   void GetPreeditStyle( Dali::InputMethodContext::PreEditAttributeDataContainer& attrs ) const;
 364
 365 public:
 366
 367   // Signals
 368
 369   /**
 370    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 371    *
 372    * @return The input method context Activated signal.
 373    */
 374   ActivatedSignalType& ActivatedSignal();
 375
 376   /**
 377    * @brief This is emitted when the input method context receives an event.
 378    *
 379    * @return The Event signal containing the event data.
 380    */
 381   KeyboardEventSignalType& EventReceivedSignal();
 382
 383   /**
 384    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 385    *
 386    * @return The signal connect to status changed event.
 387    */
 388   StatusSignalType& StatusChangedSignal();
 389
 390   /**
 391    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 392    *
 393    * @return The signal to connect to resized event.
 394    */
 395   VoidSignalType& ResizedSignal();
 396
 397   /**
 398    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 399    *
 400    * @return The signal to connect to language changed event.
 401    */
 402   VoidSignalType& LanguageChangedSignal();
 403
 404   // Construction & Destruction
 405
 406   /**
 407    * @brief Constructor.
 408    */
 409   InputMethodContext();
 410
 411   /**
 412    * @brief Destructor
 413    *
 414    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 415    */
 416   ~InputMethodContext();
 417
 418   /**
 419    * @brief This constructor is used by InputMethodContext::Get().
 420    *
 421    * @param[in] inputMethodContext A pointer to the input method context.
 422    */
 423   explicit InputMethodContext( Internal::Adaptor::InputMethodContext* inputMethodContext );
 424 };
 425
 426 } // namespace Dali
 427
 428 #endif // DALI_TOOLKIT_TOOLKIT_INPUT_METHOD_CONTEXT_H