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

   1 #ifndef __DALI_IMF_MANAGER_H__
   2 #define __DALI_IMF_MANAGER_H__
   3
   4 /*
   5  * Copyright (c) 2014 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
  25 namespace Dali
  26 {
  27
  28 namespace Internal DALI_INTERNAL
  29 {
  30 namespace Adaptor
  31 {
  32 class ImfManager;
  33 }
  34 }
  35
  36 // TODO: Temporary patch to hidden ecore dependency. Must fix it.
  37 typedef void* ImfContext;
  38
  39 /**
  40  * @brief The ImfManager class
  41  *
  42  * Specifically manages the ecore input method framework which enables the virtual or hardware keyboards.
  43  */
  44 class DALI_IMPORT_API ImfManager : public BaseHandle
  45 {
  46 public:
  47
  48   /**
  49    * @brief Events that are generated by the IMF.
  50    */
  51   enum ImfEvent
  52   {
  53     VOID,                ///< No event
  54     PREEDIT,             ///< Pre-Edit changed
  55     COMMIT,              ///< Commit recieved
  56     DELETESURROUNDING,   ///< Event to delete a range of characters from the string
  57     GETSURROUNDING       ///< Event to query string and cursor position
  58   };
  59
  60   /**
  61    * @brief This structure is used to pass on data from the IMF regarding predictive text.
  62    */
  63   struct ImfEventData
  64   {
  65     /**
  66      * @brief Default Constructor.
  67      */
  68     ImfEventData()
  69     : eventName( VOID ),
  70       predictiveString(""),
  71       cursorOffset( 0 ),
  72       numberOfChars ( 0 )
  73     {
  74     };
  75
  76     /**
  77      * @brief Constructor
  78      *
  79      * @param[in] aEventName The name of the event from the IMF.
  80      * @param[in] aPredictiveString The pre-edit or commit string.
  81      * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
  82      * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
  83      */
  84     ImfEventData(ImfEvent aEventName, const std::string& aPredictiveString, int aCursorOffset,int aNumberOfChars  )
  85     : eventName(aEventName), predictiveString(aPredictiveString), cursorOffset( aCursorOffset ), numberOfChars( aNumberOfChars )
  86     {
  87     }
  88
  89     // Data
  90     ImfEvent eventName; ///< The name of the event from the IMF.
  91     std::string predictiveString; ///< The pre-edit or commit string.
  92     int cursorOffset; ///< Start position from the current cursor position to start deleting characters.
  93     int numberOfChars; ///< number of characters to delete from the cursorOffset.
  94   };
  95
  96   /**
  97    * @brief Data required by IMF from the callback
  98    */
  99   struct ImfCallbackData
 100   {
 101     /**
 102      * @brief Constructor
 103      */
 104     ImfCallbackData( )
 105     : update( false ), cursorPosition( 0 ), preeditResetRequired ( false )
 106     {
 107     }
 108
 109     /**
 110      * @brief Constructor
 111      * @param[in] aUpdate True if cursor position needs to be updated
 112      * @param[in] aCursorPosition new position of cursor
 113      * @param[in] aCurrentText current text string
 114      * @param[in] aPreeditResetRequired flag if preedit reset is required.
 115      */
 116     ImfCallbackData(bool aUpdate, int aCursorPosition, std::string aCurrentText, bool aPreeditResetRequired )
 117     : update(aUpdate), cursorPosition(aCursorPosition), currentText( aCurrentText ), preeditResetRequired( aPreeditResetRequired )
 118     {
 119     }
 120
 121     bool update; ///< if cursor position needs to be updated
 122     int cursorPosition; ///< new position of cursor
 123     std::string currentText; ///< current text string
 124     bool preeditResetRequired; ///< flag if preedit reset is required.
 125   };
 126
 127   typedef Signal< void (ImfManager&) > ImfManagerSignalType; ///< Keyboard actived signal
 128
 129   typedef Signal< ImfCallbackData ( ImfManager&, const ImfEventData& ) > ImfEventSignalType; ///< keyboard events
 130
 131 public:
 132
 133   /**
 134    * @brief Retrieve a handle to the instance of ImfManager.
 135    * @return A handle to the ImfManager.
 136    */
 137   static ImfManager Get();
 138
 139   /**
 140    * @brief Get the current imf context.
 141    * @return current imf context.
 142    */
 143   ImfContext GetContext();
 144
 145   /**
 146    * @brief Activate the IMF.
 147    *
 148    * It means that the text editing is started at somewhere.
 149    * If the H/W keyboard isn't connected then it will show the virtual keyboard.
 150    */
 151   void Activate();
 152
 153   /**
 154    * @brief Deactivate the IMF.
 155    *
 156    * It means that the text editing is finished at somewhere.
 157    */
 158   void Deactivate();
 159
 160   /**
 161    * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
 162    *
 163    * If true then keyboard will be restored (activated) after focus is regained.
 164    * @return restoration status.
 165    */
 166   bool RestoreAfterFocusLost() const;
 167
 168   /**
 169    * @brief Set status whether the IMF has to restore the keyboard after losing focus.
 170    *
 171    * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
 172    */
 173   void SetRestoreAfterFocusLost( bool toggle );
 174
 175   /**
 176    * @brief Send message reset the pred-edit state / imf module.
 177    *
 178    * Used to interupt pre-edit state maybe due to a touch input.
 179    */
 180   void Reset();
 181
 182   /**
 183    * @brief Notifies IMF context that the cursor position has changed, required for features like auto-capitalisation.
 184    */
 185   void NotifyCursorPosition();
 186
 187   /**
 188    * @brief Sets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 189    *
 190    * @param[in] cursorPosition position of cursor
 191    */
 192   void SetCursorPosition( unsigned int cursorPosition );
 193
 194   /**
 195    * @brief Gets cursor position stored in VirtualKeyboard, this is required by the IMF context.
 196    *
 197    * @return current position of cursor
 198    */
 199   int GetCursorPosition();
 200
 201   /**
 202    * @brief Method to store the string required by the IMF, this is used to provide predictive word suggestions.
 203    *
 204    * @param[in] text The text string surrounding the current cursor point.
 205    */
 206   void SetSurroundingText( std::string text );
 207
 208   /**
 209    * @brief Gets current text string set within the IMF manager, this is used to offer predictive suggestions.
 210    *
 211    * @return current position of cursor
 212    */
 213   std::string GetSurroundingText();
 214
 215 public:
 216
 217   // Signals
 218
 219   /**
 220    * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
 221    *
 222    * @return The IMF Activated signal.
 223    */
 224   ImfManagerSignalType& ActivatedSignal();
 225
 226   /**
 227    * @brief This is emitted when the IMF manager receives an event from the IMF.
 228    *
 229    * @return The Event signal containing the event data.
 230    */
 231   ImfEventSignalType& EventReceivedSignal();
 232
 233   // Construction & Destruction
 234
 235   /**
 236    * @brief Constructor.
 237    */
 238   ImfManager();
 239
 240   /**
 241    * @brief Destructor
 242    *
 243    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 244    */
 245   ~ImfManager();
 246
 247   /**
 248    * @brief This constructor is used by ImfManager::Get().
 249    *
 250    * @param[in] imfManager A pointer to the imf Manager.
 251    */
 252   explicit DALI_INTERNAL ImfManager( Internal::Adaptor::ImfManager* imfManager );
 253 };
 254
 255 } // namespace Dali
 256
 257 #endif // __DALI_IMF_MANAGER_H__