1 #ifndef DALI_INPUT_METHOD_CONTEXT_H
2 #define DALI_INPUT_METHOD_CONTEXT_H
5 * Copyright (c) 2020 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/common/dali-vector.h>
23 #include <dali/public-api/events/key-event.h>
26 #include <dali/devel-api/adaptor-framework/input-method-options.h>
27 #include <dali/public-api/object/base-handle.h>
28 #include <dali/public-api/signals/dali-signal.h>
32 namespace Internal DALI_INTERNAL
36 class InputMethodContext;
38 } // namespace DALI_INTERNAL
43 * @brief The InputMethodContext class
45 * Specifically manages the ecore input method framework which enables the virtual or hardware keyboards.
47 class DALI_ADAPTOR_API InputMethodContext : public BaseHandle
51 * @brief The direction of text.
60 * @brief Events that are generated by the InputMethodContext.
65 PRE_EDIT, ///< Pre-Edit changed
66 COMMIT, ///< Commit recieved
67 DELETE_SURROUNDING, ///< Event to delete a range of characters from the string
68 GET_SURROUNDING, ///< Event to query string and cursor position
69 PRIVATE_COMMAND ///< Private command sent from the input panel
73 * @brief Enumeration for state of the input panel.
77 DEFAULT = 0, ///< Unknown state
78 SHOW, ///< Input panel is shown
79 HIDE, ///< Input panel is hidden
80 WILL_SHOW ///< Input panel in process of being shown
84 * @brief Enumeration for the type of Keyboard.
88 SOFTWARE_KEYBOARD, ///< Software keyboard (Virtual keyboard) is default
89 HARDWARE_KEYBOARD ///< Hardware keyboard
93 * @brief Enumeration for the language mode of the input panel.
95 enum class InputPanelLanguage
97 AUTOMATIC, ///< IME Language automatically set depending on the system display
98 ALPHABET ///< Latin alphabet at all times
102 * @brief Enumeration for the preedit style types.
104 enum class PreeditStyle
106 NONE, ///< None style
107 UNDERLINE, ///< Underline substring style
108 REVERSE, ///< Reverse substring style
109 HIGHLIGHT, ///< Highlight substring style
110 CUSTOM_PLATFORM_STYLE_1, ///< Custom style for platform
111 CUSTOM_PLATFORM_STYLE_2, ///< Custom style for platform
112 CUSTOM_PLATFORM_STYLE_3, ///< Custom style for platform
113 CUSTOM_PLATFORM_STYLE_4 ///< Custom style for platform
117 * @brief This structure is for the preedit style types and indices.
119 struct PreeditAttributeData
121 PreeditAttributeData()
122 : preeditType(PreeditStyle::NONE),
128 PreeditStyle preeditType; /// The preedit style type
129 unsigned int startIndex; /// The start index of preedit
130 unsigned int endIndex; /// The end index of preedit
134 * @brief This structure is used to pass on data from the InputMethodContext regarding predictive text.
139 * @brief Default Constructor.
142 : predictiveString(),
150 * @param[in] aEventName The name of the event from the InputMethodContext.
151 * @param[in] aPredictiveString The pre-edit or commit string.
152 * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
153 * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
155 EventData(EventType aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars)
156 : predictiveString(aPredictiveString),
157 eventName(aEventName),
158 cursorOffset(aCursorOffset),
159 numberOfChars(aNumberOfChars)
164 std::string predictiveString; ///< The pre-edit or commit string.
165 EventType eventName; ///< The name of the event from the InputMethodContext.
166 int cursorOffset; ///< Start position from the current cursor position to start deleting characters.
167 int numberOfChars; ///< number of characters to delete from the cursorOffset.
171 * @brief Data required by InputMethodContext from the callback
182 preeditResetRequired(false)
188 * @param[in] aUpdate True if cursor position needs to be updated
189 * @param[in] aCursorPosition new position of cursor
190 * @param[in] aCurrentText current text string
191 * @param[in] aPreeditResetRequired flag if preedit reset is required.
193 CallbackData(bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired)
194 : currentText(aCurrentText),
195 cursorPosition(aCursorPosition),
197 preeditResetRequired(aPreeditResetRequired)
201 std::string currentText; ///< current text string
202 int cursorPosition; ///< new position of cursor
203 bool update : 1; ///< if cursor position needs to be updated
204 bool preeditResetRequired : 1; ///< flag if preedit reset is required.
207 typedef Signal<void(InputMethodContext&)> ActivatedSignalType; ///< Keyboard actived signal
208 typedef Signal<CallbackData(InputMethodContext&, const EventData&)> KeyboardEventSignalType; ///< keyboard events
209 typedef Signal<void()> VoidSignalType;
210 typedef Signal<void(bool)> StatusSignalType;
211 typedef Signal<void(KeyboardType)> KeyboardTypeSignalType; ///< keyboard type
212 typedef Signal<void(int)> KeyboardResizedSignalType; ///< Keyboard resized signal
213 typedef Signal<void(int)> LanguageChangedSignalType; ///< Language changed signal
214 typedef Signal<void(const std::string&, const std::string&, const std::string&)> ContentReceivedSignalType; ///< Content received signal
216 using PreEditAttributeDataContainer = Vector<Dali::InputMethodContext::PreeditAttributeData>;
220 * @brief Retrieve a handle to the instance of InputMethodContext.
221 * @return A handle to the InputMethodContext.
222 * @brief Constructor.
224 InputMethodContext();
229 * This is non-virtual since derived Handle types must not contain data or virtual methods.
231 ~InputMethodContext();
234 * @brief Create a new instance of an InputMethodContext.
236 static InputMethodContext New();
239 * @brief Create a new instance of an InputMethodContext.
241 * @param[in] actor The actor that uses the new InputMethodContext instance.
243 static InputMethodContext New(Actor actor);
246 * @brief Copy constructor.
248 * @param[in] inputMethodContext InputMethodContext to copy. The copied inputMethodContext will point at the same implementation.
250 InputMethodContext(const InputMethodContext& inputMethodContext);
253 * @brief Assignment operator.
255 * @param[in] inputMethodContext The InputMethodContext to assign from.
256 * @return The updated InputMethodContext.
258 InputMethodContext& operator=(const InputMethodContext& inputMethodContext);
261 * @brief Downcast a handle to InputMethodContext handle.
263 * If handle points to an InputMethodContext the downcast produces valid
264 * handle. If not the returned handle is left uninitialized.
266 * @param[in] handle Handle to an object.
267 * @return Handle to an InputMethodContext or an uninitialized handle.
269 static InputMethodContext DownCast(BaseHandle handle);
273 * @brief Finalize the InputMethodContext.
275 * It means that the context will be deleted.
280 * @brief Activate the InputMethodContext.
282 * It means that the text editing is started at somewhere.
283 * If the H/W keyboard isn't connected then it will show the virtual keyboard.
288 * @brief Deactivate the InputMethodContext.
290 * It means that the text editing is finished at somewhere.
295 * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
297 * If true then keyboard will be restored (activated) after focus is regained.
298 * @return restoration status.
300 bool RestoreAfterFocusLost() const;
303 * @brief Set status whether the InputMethodContext has to restore the keyboard after losing focus.
305 * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
307 void SetRestoreAfterFocusLost(bool toggle);
310 * @brief Send message reset the pred-edit state / InputMethodContext module.
312 * Used to interupt pre-edit state maybe due to a touch input.
317 * @brief Notifies InputMethodContext that the cursor position has changed, required for features like auto-capitalisation.
319 void NotifyCursorPosition();
322 * @brief Sets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
324 * @param[in] cursorPosition position of cursor
326 void SetCursorPosition(unsigned int cursorPosition);
329 * @brief Gets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
331 * @return current position of cursor
333 unsigned int GetCursorPosition() const;
336 * @brief Method to store the string required by the InputMethodContext, this is used to provide predictive word suggestions.
338 * @param[in] text The text string surrounding the current cursor point.
340 void SetSurroundingText(const std::string& text);
343 * @brief Gets current text string set within the InputMethodContext manager, this is used to offer predictive suggestions.
345 * @return current position of cursor
347 const std::string& GetSurroundingText() const;
350 * @brief Notifies InputMethodContext that text input is set to multi line or not
352 * @param[in] multiLine True if multiline text input is used
354 void NotifyTextInputMultiLine(bool multiLine);
357 * @brief Returns text direction of the keyboard's current input language.
358 * @return The direction of the text.
360 TextDirection GetTextDirection();
363 * @brief Provides size and position of keyboard.
365 * Position is relative to whether keyboard is visible or not.
366 * If keyboard is not visible then position will be off the screen.
367 * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
368 * the values then taken down. So ideally GetInputMethodArea() should be called after Show().
369 * @return rect which is keyboard panel x, y, width, height
371 Dali::Rect<int> GetInputMethodArea();
374 * @brief Set one or more of the Input Method options
375 * @param[in] options The options to be applied
377 void ApplyOptions(const InputMethodOptions& options);
380 * @brief Sets up the input-panel specific data.
381 * @param[in] data The specific data to be set to the input panel
383 void SetInputPanelData(const std::string& data);
386 * @brief Gets the specific data of the current active input panel.
388 * Input Panel Data is not always the data which is set by SetInputPanelData().
389 * Data can be changed internally in the input panel.
390 * It is just used to get a specific data from the input panel to an application.
391 * @param[in] data The specific data to be got from the input panel
393 void GetInputPanelData(std::string& data);
396 * @brief Gets the state of the current active input panel.
397 * @return The state of the input panel.
399 State GetInputPanelState();
402 * @brief Sets the return key on the input panel to be visible or invisible.
404 * The default is true.
405 * @param[in] visible True if the return key is visible(enabled), false otherwise.
407 void SetReturnKeyState(bool visible);
410 * @brief Enable to show the input panel automatically when focused.
411 * @param[in] enabled If true, the input panel will be shown when focused
413 void AutoEnableInputPanel(bool enabled);
416 * @brief Shows the input panel.
418 void ShowInputPanel();
421 * @brief Hides the input panel.
423 void HideInputPanel();
426 * @brief Gets the keyboard type.
428 * The default keyboard type is SOFTWARE_KEYBOARD.
429 * @return The keyboard type
431 KeyboardType GetKeyboardType();
434 * @brief Gets the current language locale of the input panel.
436 * ex) en_US, en_GB, en_PH, fr_FR, ...
437 * @return The current language locale of the input panel
439 std::string GetInputPanelLocale();
442 * @brief Sets the allowed MIME Types to deliver to the input panel.
444 * ex) std::string mimeTypes = "text/plain,image/png,image/gif,application/pdf";
446 * You can receive a media content URI and its MIME type from ContentReceivedSignal(). @see ContentReceivedSignal
447 * @param[in] mimeTypes The allowed MIME types
449 void SetContentMIMETypes(const std::string& mimeTypes);
452 * @brief Process event key down or up, whether filter a key to isf.
454 * @param[in] keyEvent The event key to be handled.
455 * @return Whether the event key is handled.
457 bool FilterEventKey(const Dali::KeyEvent& keyEvent);
460 * @brief Sets whether the IM context should allow to use the text prediction.
462 * @param[in] prediction Whether to allow text prediction or not.
464 void AllowTextPrediction(bool prediction);
467 * @brief Gets whether the IM context allow to use the text prediction.
469 * @return Whether the IM allow text prediction or not.
471 bool IsTextPredictionAllowed() const;
474 * @brief Sets the language of the input panel.
476 * This method can be used when you want to show the English keyboard.
477 * @param[in] language The language to be set to the input panel
479 void SetInputPanelLanguage(InputPanelLanguage language);
482 * @brief Gets the language of the input panel.
484 * @return The language of the input panel
486 InputPanelLanguage GetInputPanelLanguage() const;
489 * @brief Sets the x,y coordinates of the input panel.
491 * @param[in] x The top-left x coordinate of the input panel
492 * @param[in] y The top-left y coordinate of the input panel
494 void SetInputPanelPosition(unsigned int x, unsigned int y);
497 * @brief Gets the preedit attributes data.
499 * @param[out] attrs The preedit attributes data.
501 void GetPreeditStyle(PreEditAttributeDataContainer& attrs) const;
507 * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
509 * @return The InputMethodContext Activated signal.
511 ActivatedSignalType& ActivatedSignal();
514 * @brief This is emitted when the InputMethodContext manager receives an event from the InputMethodContext.
516 * @return The Event signal containing the event data.
518 KeyboardEventSignalType& EventReceivedSignal();
521 * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
523 * A callback of the following type may be connected:
525 * void YourCallbackName(bool keyboardShown);
527 * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
528 * has just been hidden.
529 * @return The signal to connect to.
531 StatusSignalType& StatusChangedSignal();
534 * @brief Connect to this signal to be notified when the virtual keyboard is resized.
536 * A callback of the following type may be connected:
538 * void YourCallbackName( int resolvedResize );
540 * The parameter sends the resolved resize defined by the InputMethodContext.
542 * User can get changed size by using GetInputMethodArea() in the callback
543 * @return The signal to connect to.
545 KeyboardResizedSignalType& ResizedSignal();
548 * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
550 * A callback of the following type may be connected:
552 * void YourCallbackName( int resolvedLanguage );
554 * The parameter sends the resolved language defined by the InputMethodContext.
556 * User can get the text direction of the language by calling GetTextDirection() in the callback.
557 * @return The signal to connect to.
559 LanguageChangedSignalType& LanguageChangedSignal();
562 * @brief Connect to this signal to be notified when the keyboard type is changed.
564 * A callback of the following type may be connected:
566 * void YourCallbackName( KeyboardType keyboard );
569 * @return The signal to connect to.
571 KeyboardTypeSignalType& KeyboardTypeChangedSignal();
574 * @brief Connect to this signal to be notified when the content, such as images, of input method is received.
576 * A callback of the following type may be connected:
578 * void YourCallbackName( const std::string& contentUri, const std::string& description, const std::string& contentMIMEType );
581 * @return The signal to connect to.
583 ContentReceivedSignalType& ContentReceivedSignal();
587 * @brief This constructor is used by InputMethodContext::New().
589 * @param[in] inputMethodContext A pointer to the InputMethodContext.
591 explicit DALI_INTERNAL InputMethodContext(Internal::Adaptor::InputMethodContext* inputMethodContext);
596 #endif // DALI_INPUT_METHOD_CONTEXT_H