adaptors/devel-api/adaptor-framework/imf-manager.h

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