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 Events that are generated by the input method context.
  51    */
  52   enum EventType
  53   {
  54     VOID,                ///< No event
  55     PRE_EDIT,             ///< Pre-Edit changed
  56     COMMIT,              ///< Commit recieved
  57     DELETE_SURROUNDING,   ///< Event to delete a range of characters from the string
  58     GET_SURROUNDING,      ///< Event to query string and cursor position
  59     PRIVATE_COMMAND       ///< Private command sent from the input panel
  60   };
  61
  62   /**
  63    * @brief This structure is used to pass on data from the input method cotext regarding predictive text.
  64    */
  65   struct EventData
  66   {
  67     /**
  68      * @brief Default Constructor.
  69      */
  70     EventData()
  71     : predictiveString(),
  72       eventName( VOID ),
  73       cursorOffset( 0 ),
  74       numberOfChars ( 0 )
  75     {
  76     };
  77
  78     /**
  79      * @brief Constructor
  80      *
  81      * @param[in] aEventName The name of the event from the input method context.
  82      * @param[in] aPredictiveString The pre-edit or commit string.
  83      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
  84      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
  85      */
  86     EventData( EventType aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
  87     : predictiveString( aPredictiveString ),
  88       eventName( aEventName ),
  89       cursorOffset( aCursorOffset ),
  90       numberOfChars( aNumberOfChars )
  91     {
  92     }
  93
  94     // Data
  95     std::string predictiveString; ///< The pre-edit or commit string.
  96     EventType eventName;           ///< The name of the event from the input method context.
  97     int cursorOffset;             ///< Start position from the current cursor position to start deleting characters.
  98     int numberOfChars;            ///< number of characters to delete from the cursorOffset.
  99   };
 100
 101   /**
 102    * @brief Data required by input method context from the callback
 103    */
 104   struct CallbackData
 105   {
 106     /**
 107      * @brief Constructor
 108      */
 109     CallbackData()
 110     : currentText(),
 111       cursorPosition( 0 ),
 112       update( false ),
 113       preeditResetRequired( false )
 114     {
 115     }
 116
 117     /**
 118      * @brief Constructor
 119      * @param[in] aUpdate True if cursor position needs to be updated
 120      * @param[in] aCursorPosition new position of cursor
 121      * @param[in] aCurrentText current text string
 122      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 123      */
 124     CallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
 125     : currentText( aCurrentText ),
 126       cursorPosition( aCursorPosition ),
 127       update( aUpdate ),
 128       preeditResetRequired( aPreeditResetRequired )
 129     {
 130     }
 131
 132     std::string currentText;      ///< current text string
 133     int cursorPosition;           ///< new position of cursor
 134     bool update               :1; ///< if cursor position needs to be updated
 135     bool preeditResetRequired :1; ///< flag if preedit reset is required.
 136   };
 137
 138   typedef Signal< void (InputMethodContext&) > ActivatedSignalType; ///< Keyboard actived signal
 139   typedef Signal< CallbackData ( InputMethodContext&, const EventData& ) > KeyboardEventSignalType; ///< keyboard events
 140   typedef Signal< void () > VoidSignalType;
 141   typedef Signal< void (bool) > StatusSignalType;
 142
 143 public:
 144
 145   /**
 146    * @brief Create a handle to the instance of InputMethodContext.
 147    * @return A handle to the InputMethodContext.
 148    */
 149   static InputMethodContext New();
 150
 151   /**
 152    * @brief Create a handle to the instance of InputMethodContext.
 153    *
 154    * @param[in] actor The actor that uses the new InputMethodContext instance.
 155    * @return A handle to the InputMethodContext.
 156    */
 157   static InputMethodContext New( Actor actor );
 158
 159   /**
 160    * @brief Finalize the InputMethodContext.
 161    *
 162    * It means that the context will be deleted.
 163    */
 164   void Finalize();
 165
 166   /**
 167    * @brief Activate the input method context.
 168    *
 169    * It means that the text editing is started at somewhere.
 170    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 171    */
 172   void Activate();
 173
 174   /**
 175    * @brief Deactivate the input method context.
 176    *
 177    * It means that the text editing is finished at somewhere.
 178    */
 179   void Deactivate();
 180
 181   /**
 182    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 183    *
 184    * If true then keyboard will be restored (activated) after focus is regained.
 185    * @return restoration status.
 186    */
 187   bool RestoreAfterFocusLost() const;
 188
 189   /**
 190    * @brief Set status whether the input method context has to restore the keyboard after losing focus.
 191    *
 192    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 193    */
 194   void SetRestoreAfterFocusLost( bool toggle );
 195
 196   /**
 197    * @brief Send message reset the pred-edit state / input method context module.
 198    *
 199    * Used to interupt pre-edit state maybe due to a touch input.
 200    */
 201   void Reset();
 202
 203   /**
 204    * @brief Notifies ImfContext that the cursor position has changed, required for features like auto-capitalisation.
 205    */
 206   void NotifyCursorPosition();
 207
 208   /**
 209    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the ImfContext.
 210    *
 211    * @param[in] cursorPosition position of cursor
 212    */
 213   void SetCursorPosition( unsigned int cursorPosition );
 214
 215   /**
 216    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the ImfContext.
 217    *
 218    * @return current position of cursor
 219    */
 220   unsigned int GetCursorPosition() const;
 221
 222   /**
 223    * @brief Method to store the string required by the input method context, this is used to provide predictive word suggestions.
 224    *
 225    * @param[in] text The text string surrounding the current cursor point.
 226    */
 227   void SetSurroundingText( const std::string& text );
 228
 229   /**
 230    * @brief Gets current text string set within the input method context, this is used to offer predictive suggestions.
 231    *
 232    * @return current position of cursor
 233    */
 234   const std::string& GetSurroundingText() const;
 235
 236   /**
 237   * @brief Notifies ImfContext that text input is set to multi line or not
 238   */
 239   void NotifyTextInputMultiLine( bool multiLine );
 240
 241   /**
 242    * @brief Set one or more of the Input Method options
 243    * @param[in] options The options to be applied
 244    */
 245   void ApplyOptions( const InputMethodOptions& options );
 246
 247   /**
 248    * @brief Process event key down or up, whether filter a key to isf.
 249    *
 250    * @param[in] keyEvent The event key to be handled.
 251    * @return Whether the event key is handled.
 252    */
 253   bool FilterEventKey( const Dali::KeyEvent& keyEvent );
 254
 255 public:
 256
 257   // Signals
 258
 259   /**
 260    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 261    *
 262    * @return The input method context Activated signal.
 263    */
 264   ActivatedSignalType& ActivatedSignal();
 265
 266   /**
 267    * @brief This is emitted when the input method context receives an event.
 268    *
 269    * @return The Event signal containing the event data.
 270    */
 271   KeyboardEventSignalType& EventReceivedSignal();
 272
 273   /**
 274    * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
 275    *
 276    * @return The signal connect to status changed event.
 277    */
 278   StatusSignalType& StatusChangedSignal();
 279
 280   /**
 281    * @brief Connect to this signal to be notified when the virtual keyboard is resized.
 282    *
 283    * @return The signal to connect to resized event.
 284    */
 285   VoidSignalType& ResizedSignal();
 286
 287   /**
 288    * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
 289    *
 290    * @return The signal to connect to language changed event.
 291    */
 292   VoidSignalType& LanguageChangedSignal();
 293
 294   // Construction & Destruction
 295
 296   /**
 297    * @brief Constructor.
 298    */
 299   InputMethodContext();
 300
 301   /**
 302    * @brief Destructor
 303    *
 304    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 305    */
 306   ~InputMethodContext();
 307
 308   /**
 309    * @brief This constructor is used by InputMethodContext::Get().
 310    *
 311    * @param[in] inputMethodContext A pointer to the input method context.
 312    */
 313   explicit InputMethodContext( Internal::Adaptor::InputMethodContext* inputMethodContext );
 314 };
 315
 316 } // namespace Dali
 317
 318 #endif // DALI_TOOLKIT_TOOLKIT_INPUT_METHOD_CONTEXT_H