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