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   };
  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   /**
  92    * @brief Enumeration for the language mode of the input panel.
  93    */
  94   enum class InputPanelLanguage
  95   {
  96     AUTOMATIC,    ///< IME Language automatically set depending on the system display
  97     ALPHABET      ///< Latin alphabet at all times
  98   };
  99
 100   /**
 101    * @brief Enumeration for the preedit style types.
 102    */
 103   enum class PreeditStyle
 104   {
 105     NONE,         ///< None style
 106     UNDERLINE,    ///< Underline substring style
 107     REVERSE,      ///< Reverse substring style
 108     HIGHLIGHT     ///< Highlight substring style
 109   };
 110
 111   /**
 112    * @brief This structure is used to pass on data from the InputMethodContext regarding predictive text.
 113    */
 114   struct EventData
 115   {
 116     /**
 117      * @brief Default Constructor.
 118      */
 119     EventData()
 120     : predictiveString(),
 121       eventName( VOID ),
 122       cursorOffset( 0 ),
 123       numberOfChars ( 0 )
 124     {
 125     };
 126
 127     /**
 128      * @brief Constructor
 129      *
 130      * @param[in] aEventName The name of the event from the input method context.
 131      * @param[in] aPredictiveString The pre-edit or commit string.
 132      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
 133      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
 134      */
 135     EventData( EventType aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
 136     : predictiveString( aPredictiveString ),
 137       eventName( aEventName ),
 138       cursorOffset( aCursorOffset ),
 139       numberOfChars( aNumberOfChars )
 140     {
 141     }
 142
 143     // Data
 144     std::string predictiveString; ///< The pre-edit or commit string.
 145     EventType eventName;           ///< The name of the event from the input method context.
 146     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
 147     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
 148   };
 149
 150   /**
 151    * @brief Data required by input method context from the callback
 152    */
 153   struct CallbackData
 154   {
 155     /**
 156      * @brief Constructor
 157      */
 158     CallbackData()
 159     : currentText(),
 160       cursorPosition( 0 ),
 161       update( false ),
 162       preeditResetRequired( false )
 163     {
 164     }
 165
 166     /**
 167      * @brief Constructor
 168      * @param[in] aUpdate True if cursor position needs to be updated
 169      * @param[in] aCursorPosition new position of cursor
 170      * @param[in] aCurrentText current text string
 171      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 172      */
 173     CallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 174     : currentText( aCurrentText ),
 175       cursorPosition( aCursorPosition ),
 176       update( aUpdate ),
 177       preeditResetRequired( aPreeditResetRequired )
 178     {
 179     }
 180
 181     std::string currentText;      ///< current text string
 182     int cursorPosition;           ///< new position of cursor
 183     bool update               :1; ///< if cursor position needs to be updated
 184     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 185   };
 186
 187   typedef Signal< void (InputMethodContext&) > ActivatedSignalType; ///< Keyboard actived signal
 188   typedef Signal< CallbackData ( InputMethodContext&, const EventData& ) > KeyboardEventSignalType; ///< keyboard events
 189   typedef Signal< void () > VoidSignalType;
 190   typedef Signal< void (bool) > StatusSignalType;
 191
 192 public:
 193
 194   /**
 195    * @brief Create a handle to the instance of InputMethodContext.
 196    * @return A handle to the InputMethodContext.
 197    */
 198   static InputMethodContext New();
 199
 200   /**
 201    * @brief Create a handle to the instance of InputMethodContext.
 202    *
 203    * @param[in] actor The actor that uses the new InputMethodContext instance.
 204    * @return A handle to the InputMethodContext.
 205    */
 206   static InputMethodContext New( Actor actor );
 207
 208   /**
 209    * @brief Finalize the InputMethodContext.
 210    *
 211    * It means that the context will be deleted.
 212    */
 213   void Finalize();
 214
 215   /**
 216    * @brief Activate the input method context.
 217    *
 218    * It means that the text editing is started at somewhere.
 219    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 220    */
 221   void Activate();
 222
 223   /**
 224    * @brief Deactivate the input method context.
 225    *
 226    * It means that the text editing is finished at somewhere.
 227    */
 228   void Deactivate();
 229
 230   /**
 231    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 232    *
 233    * If true then keyboard will be restored (activated) after focus is regained.
 234    * @return restoration status.
 235    */
 236   bool RestoreAfterFocusLost() const;
 237
 238   /**
 239    * @brief Set status whether the input method context has to restore the keyboard after losing focus.
 240    *
 241    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 242    */
 243   void SetRestoreAfterFocusLost( bool toggle );
 244
 245   /**
 246    * @brief Send message reset the pred-edit state / input method context module.
 247    *
 248    * Used to interupt pre-edit state maybe due to a touch input.
 249    */
 250   void Reset();
 251
 252   /**
 253    * @brief Notifies ImfContext that the cursor position has changed, required for features like auto-capitalisation.
 254    */
 255   void NotifyCursorPosition();
 256
 257   /**
 258    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the ImfContext.
 259    *
 260    * @param[in] cursorPosition position of cursor
 261    */
 262   void SetCursorPosition( unsigned int cursorPosition );
 263
 264   /**
 265    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the ImfContext.
 266    *
 267    * @return current position of cursor
 268    */
 269   unsigned int GetCursorPosition() const;
 270
 271   /**
 272    * @brief Method to store the string required by the input method context, this is used to provide predictive word suggestions.
 273    *
 274    * @param[in] text The text string surrounding the current cursor point.
 275    */
 276   void SetSurroundingText( const std::string& text );
 277
 278   /**
 279    * @brief Gets current text string set within the input method context, this is used to offer predictive suggestions.
 280    *
 281    * @return current position of cursor
 282    */
 283   const std::string& GetSurroundingText() const;
 284
 285   /**
 286   * @brief Notifies ImfContext that text input is set to multi line or not
 287   */
 288   void NotifyTextInputMultiLine( bool multiLine );
 289
 290   /**
 291    * @brief Set one or more of the Input Method options
 292    * @param[in] options The options to be applied
 293    */
 294   void ApplyOptions( const InputMethodOptions& options );
 295
 296   /**
 297    * @brief Process event key down or up, whether filter a key to isf.
 298    *
 299    * @param[in] keyEvent The event key to be handled.
 300    * @return Whether the event key is handled.
 301    */
 302   bool FilterEventKey( const Dali::KeyEvent& keyEvent );
 303
 304   /**
 305    * @brief Sets the preedit type.
 306    *
 307    * @param[in] type The preedit style type
 308    */
 309   void SetPreeditStyle( PreeditStyle type );
 310
 311   /**
 312    * @brief Gets the preedit type.
 313    *
 314    * @return The preedit style type
 315    */
 316   PreeditStyle GetPreeditStyle() const;
 317
 318 public:
 319
 320   // Signals
 321
 322   /**
 323    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 324    *
 325    * @return The input method context Activated signal.
 326    */
 327   ActivatedSignalType& ActivatedSignal();
 328
 329   /**
 330    * @brief This is emitted when the input method context receives an event.
 331    *
 332    * @return The Event signal containing the event data.
 333    */
 334   KeyboardEventSignalType& EventReceivedSignal();
 335
 336   /**
 337    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 338    *
 339    * @return The signal connect to status changed event.
 340    */
 341   StatusSignalType& StatusChangedSignal();
 342
 343   /**
 344    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 345    *
 346    * @return The signal to connect to resized event.
 347    */
 348   VoidSignalType& ResizedSignal();
 349
 350   /**
 351    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 352    *
 353    * @return The signal to connect to language changed event.
 354    */
 355   VoidSignalType& LanguageChangedSignal();
 356
 357   // Construction & Destruction
 358
 359   /**
 360    * @brief Constructor.
 361    */
 362   InputMethodContext();
 363
 364   /**
 365    * @brief Destructor
 366    *
 367    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 368    */
 369   ~InputMethodContext();
 370
 371   /**
 372    * @brief This constructor is used by InputMethodContext::Get().
 373    *
 374    * @param[in] inputMethodContext A pointer to the input method context.
 375    */
 376   explicit InputMethodContext( Internal::Adaptor::InputMethodContext* inputMethodContext );
 377 };
 378
 379 } // namespace Dali
 380
 381 #endif // DALI_TOOLKIT_TOOLKIT_INPUT_METHOD_CONTEXT_H