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