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