1 #ifndef __DALI_IMF_MANAGER_H__
2 #define __DALI_IMF_MANAGER_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/object/base-handle.h>
23 #include <dali/public-api/signals/dali-signal.h>
24 #include "input-method-options.h"
29 namespace Internal DALI_INTERNAL
38 * @brief The ImfManager class
40 * Specifically manages the ecore input method framework which enables the virtual or hardware keyboards.
42 class DALI_IMPORT_API ImfManager : public BaseHandle
47 * @brief The direction of text.
56 * @brief Events that are generated by the IMF.
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 PRIVATECOMMAND ///< Private command sent from the input panel
69 * @brief Enumeration for state of the input panel.
73 DEFAULT = 0, ///< Unknown state
74 SHOW, ///< Input panel is shown
75 HIDE, ///< Input panel is hidden
76 WILL_SHOW ///< Input panel in process of being shown
80 * @brief This structure is used to pass on data from the IMF regarding predictive text.
85 * @brief Default Constructor.
98 * @param[in] aEventName The name of the event from the IMF.
99 * @param[in] aPredictiveString The pre-edit or commit string.
100 * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
101 * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
103 ImfEventData( ImfEvent aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars )
104 : predictiveString( aPredictiveString ),
105 eventName( aEventName ),
106 cursorOffset( aCursorOffset ),
107 numberOfChars( aNumberOfChars )
112 std::string predictiveString; ///< The pre-edit or commit string.
113 ImfEvent eventName; ///< The name of the event from the IMF.
114 int cursorOffset; ///< Start position from the current cursor position to start deleting characters.
115 int numberOfChars; ///< number of characters to delete from the cursorOffset.
119 * @brief Data required by IMF from the callback
121 struct ImfCallbackData
130 preeditResetRequired( false )
136 * @param[in] aUpdate True if cursor position needs to be updated
137 * @param[in] aCursorPosition new position of cursor
138 * @param[in] aCurrentText current text string
139 * @param[in] aPreeditResetRequired flag if preedit reset is required.
141 ImfCallbackData( bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired )
142 : currentText( aCurrentText ),
143 cursorPosition( aCursorPosition ),
145 preeditResetRequired( aPreeditResetRequired )
149 std::string currentText; ///< current text string
150 int cursorPosition; ///< new position of cursor
151 bool update :1; ///< if cursor position needs to be updated
152 bool preeditResetRequired :1; ///< flag if preedit reset is required.
155 typedef Signal< void (ImfManager&) > ImfManagerSignalType; ///< Keyboard actived signal
156 typedef Signal< ImfCallbackData ( ImfManager&, const ImfEventData& ) > ImfEventSignalType; ///< keyboard events
157 typedef Signal< void () > VoidSignalType;
158 typedef Signal< void (bool) > StatusSignalType;
163 * @brief Retrieve a handle to the instance of ImfManager.
164 * @return A handle to the ImfManager.
166 static ImfManager Get();
169 * @brief Activate the IMF.
171 * It means that the text editing is started at somewhere.
172 * If the H/W keyboard isn't connected then it will show the virtual keyboard.
177 * @brief Deactivate the IMF.
179 * It means that the text editing is finished at somewhere.
184 * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
186 * If true then keyboard will be restored (activated) after focus is regained.
187 * @return restoration status.
189 bool RestoreAfterFocusLost() const;
192 * @brief Set status whether the IMF has to restore the keyboard after losing focus.
194 * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
196 void SetRestoreAfterFocusLost( bool toggle );
199 * @brief Send message reset the pred-edit state / imf module.
201 * Used to interupt pre-edit state maybe due to a touch input.
206 * @brief Notifies IMF context that the cursor position has changed, required for features like auto-capitalisation.
208 void NotifyCursorPosition();
211 * @brief Sets cursor position stored in VirtualKeyboard, this is required by the IMF context.
213 * @param[in] cursorPosition position of cursor
215 void SetCursorPosition( unsigned int cursorPosition );
218 * @brief Gets cursor position stored in VirtualKeyboard, this is required by the IMF context.
220 * @return current position of cursor
222 unsigned int GetCursorPosition() const;
225 * @brief Method to store the string required by the IMF, this is used to provide predictive word suggestions.
227 * @param[in] text The text string surrounding the current cursor point.
229 void SetSurroundingText( const std::string& text );
232 * @brief Gets current text string set within the IMF manager, this is used to offer predictive suggestions.
234 * @return current position of cursor
236 const std::string& GetSurroundingText() const;
239 * @brief Notifies IMF context that text input is set to multi line or not
241 * @param[in] multiLine True if multiline text input is used
243 void NotifyTextInputMultiLine( bool multiLine );
246 * @brief Returns text direction of the keyboard's current input language.
247 * @return The direction of the text.
249 TextDirection GetTextDirection();
252 * @brief Provides size and position of keyboard.
254 * Position is relative to whether keyboard is visible or not.
255 * If keyboard is not visible then position will be off the screen.
256 * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
257 * the values then taken down. So ideally GetInputMethodArea() should be called after Show().
258 * @return rect which is keyboard panel x, y, width, height
260 Dali::Rect<int> GetInputMethodArea();
263 * @brief Set one or more of the Input Method options
264 * @param[in] options The options to be applied
266 void ApplyOptions( const InputMethodOptions& options );
269 * @brief Sets up the input-panel specific data.
270 * @param[in] data The specific data to be set to the input panel
272 void SetInputPanelUserData( const std::string& data );
275 * @brief Gets the specific data of the current active input panel.
276 * @param[in] data The specific data to be got from the input panel
278 void GetInputPanelUserData( std::string& data );
281 * @brief Gets the state of the current active input panel.
282 * @return The state of the input panel.
284 State GetInputPanelState();
287 * @brief Sets the return key on the input panel to be visible or invisible.
289 * The default is true.
290 * @param[in] visible True if the return key is visible(enabled), false otherwise.
292 void SetReturnKeyState( bool visible );
295 * @brief Enable to show the input panel automatically when focused.
296 * @param[in] enabled If true, the input panel will be shown when focused
298 void AutoEnableInputPanel( bool enabled );
301 * @brief Shows the input panel.
303 void ShowInputPanel();
306 * @brief Hides the input panel.
308 void HideInputPanel();
315 * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
317 * @return The IMF Activated signal.
319 ImfManagerSignalType& ActivatedSignal();
322 * @brief This is emitted when the IMF manager receives an event from the IMF.
324 * @return The Event signal containing the event data.
326 ImfEventSignalType& EventReceivedSignal();
329 * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
331 * A callback of the following type may be connected:
333 * void YourCallbackName(bool keyboardShown);
335 * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
336 * has just been hidden.
337 * @return The signal to connect to.
339 StatusSignalType& StatusChangedSignal();
342 * @brief Connect to this signal to be notified when the virtual keyboard is resized.
344 * A callback of the following type may be connected:
346 * void YourCallbackName();
348 * User can get changed size by using GetInputMethodArea() in the callback
349 * @return The signal to connect to.
351 VoidSignalType& ResizedSignal();
354 * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
356 * A callback of the following type may be connected:
358 * void YourCallbackName();
360 * User can get the text direction of the language by calling GetTextDirection() in the callback.
361 * @return The signal to connect to.
363 VoidSignalType& LanguageChangedSignal();
365 // Construction & Destruction
368 * @brief Constructor.
375 * This is non-virtual since derived Handle types must not contain data or virtual methods.
380 * @brief This constructor is used by ImfManager::Get().
382 * @param[in] imfManager A pointer to the imf Manager.
384 explicit DALI_INTERNAL ImfManager( Internal::Adaptor::ImfManager* imfManager );
389 #endif // __DALI_IMF_MANAGER_H__