adaptors/public-api/imf-manager.h

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