1 #ifndef DALI_INPUT_METHOD_CONTEXT_H
2 #define DALI_INPUT_METHOD_CONTEXT_H
5 * Copyright (c) 2022 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
70 SELECTION_SET ///< input method needs to set the selection
74 * @brief Enumeration for state of the input panel.
78 DEFAULT = 0, ///< Unknown state
79 SHOW, ///< Input panel is shown
80 HIDE, ///< Input panel is hidden
81 WILL_SHOW ///< Input panel in process of being shown
85 * @brief Enumeration for the type of Keyboard.
89 SOFTWARE_KEYBOARD, ///< Software keyboard (Virtual keyboard) is default
90 HARDWARE_KEYBOARD ///< Hardware keyboard
94 * @brief Enumeration for the language mode of the input panel.
96 enum class InputPanelLanguage
98 AUTOMATIC, ///< IME Language automatically set depending on the system display
99 ALPHABET ///< Latin alphabet(default). It can be changed according to OSD(On Screen Display) language.
103 * @brief Enumeration for defining the types of Ecore_IMF Input Panel align.
105 enum class InputPanelAlign
107 TOP_LEFT, ///< The top-left corner
108 TOP_CENTER, ///< The top-center position
109 TOP_RIGHT, ///< The top-right corner
110 MIDDLE_LEFT, ///< The middle-left position
111 MIDDLE_CENTER, ///< The middle-center position
112 MIDDLE_RIGHT, ///< The middle-right position
113 BOTTOM_LEFT, ///< The bottom-left corner
114 BOTTOM_CENTER, ///< The bottom-center position
115 BOTTOM_RIGHT ///< The bottom-right corner
119 * @brief Enumeration for the preedit style types.
121 enum class PreeditStyle
123 NONE, ///< None style
124 UNDERLINE, ///< Underline substring style
125 REVERSE, ///< Reverse substring style
126 HIGHLIGHT, ///< Highlight substring style
127 CUSTOM_PLATFORM_STYLE_1, ///< Custom style for platform
128 CUSTOM_PLATFORM_STYLE_2, ///< Custom style for platform
129 CUSTOM_PLATFORM_STYLE_3, ///< Custom style for platform
130 CUSTOM_PLATFORM_STYLE_4 ///< Custom style for platform
134 * @brief This structure is for the preedit style types and indices.
136 struct PreeditAttributeData
138 PreeditAttributeData()
139 : preeditType(PreeditStyle::NONE),
145 PreeditStyle preeditType; /// The preedit style type
146 unsigned int startIndex; /// The start index of preedit
147 unsigned int endIndex; /// The end index of preedit
151 * @brief This structure is used to pass on data from the InputMethodContext regarding predictive text.
156 * @brief Default Constructor.
159 : predictiveString(),
169 * @param[in] aEventName The name of the event from the InputMethodContext.
170 * @param[in] aPredictiveString The pre-edit or commit string.
171 * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
172 * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
174 EventData(EventType aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars)
175 : predictiveString(aPredictiveString),
176 eventName(aEventName),
177 cursorOffset(aCursorOffset),
178 numberOfChars(aNumberOfChars),
187 * @param[in] aEventName The name of the event from the InputMethodContext.
188 * @param[in] aStartIndex The start index of selection.
189 * @param[in] aEndIndex The end index of selection.
191 EventData(EventType aEventName, int aStartIndex, int aEndIndex)
192 : predictiveString(),
193 eventName(aEventName),
196 startIndex(aStartIndex),
202 std::string predictiveString; ///< The pre-edit or commit string.
203 EventType eventName; ///< The name of the event from the InputMethodContext.
204 int cursorOffset; ///< Start position from the current cursor position to start deleting characters.
205 int numberOfChars; ///< number of characters to delete from the cursorOffset.
206 int startIndex; ///< The start index of selection.
207 int endIndex; ///< The end index of selection.
211 * @brief Data required by InputMethodContext from the callback
222 preeditResetRequired(false)
228 * @param[in] aUpdate True if cursor position needs to be updated
229 * @param[in] aCursorPosition new position of cursor
230 * @param[in] aCurrentText current text string
231 * @param[in] aPreeditResetRequired flag if preedit reset is required.
233 CallbackData(bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired)
234 : currentText(aCurrentText),
235 cursorPosition(aCursorPosition),
237 preeditResetRequired(aPreeditResetRequired)
241 std::string currentText; ///< current text string
242 int cursorPosition; ///< new position of cursor
243 bool update : 1; ///< if cursor position needs to be updated
244 bool preeditResetRequired : 1; ///< flag if preedit reset is required.
247 typedef Signal<void(InputMethodContext&)> ActivatedSignalType; ///< Keyboard actived signal
248 typedef Signal<CallbackData(InputMethodContext&, const EventData&)> KeyboardEventSignalType; ///< keyboard events
249 typedef Signal<void()> VoidSignalType;
250 typedef Signal<void(bool)> StatusSignalType;
251 typedef Signal<void(KeyboardType)> KeyboardTypeSignalType; ///< keyboard type
252 typedef Signal<void(int)> KeyboardResizedSignalType; ///< Keyboard resized signal
253 typedef Signal<void(int)> LanguageChangedSignalType; ///< Language changed signal
254 typedef Signal<void(const std::string&, const std::string&, const std::string&)> ContentReceivedSignalType; ///< Content received signal
256 using PreEditAttributeDataContainer = Vector<Dali::InputMethodContext::PreeditAttributeData>;
260 * @brief Constructor.
262 InputMethodContext();
267 * This is non-virtual since derived Handle types must not contain data or virtual methods.
269 ~InputMethodContext();
272 * @brief Create a new instance of an InputMethodContext.
274 static InputMethodContext New();
277 * @brief Create a new instance of an InputMethodContext.
279 * @param[in] actor The actor that uses the new InputMethodContext instance.
281 static InputMethodContext New(Actor actor);
284 * @brief Copy constructor.
286 * @param[in] inputMethodContext InputMethodContext to copy. The copied inputMethodContext will point at the same implementation.
288 InputMethodContext(const InputMethodContext& inputMethodContext);
291 * @brief Assignment operator.
293 * @param[in] inputMethodContext The InputMethodContext to assign from.
294 * @return The updated InputMethodContext.
296 InputMethodContext& operator=(const InputMethodContext& inputMethodContext);
299 * @brief Downcast a handle to InputMethodContext handle.
301 * If handle points to an InputMethodContext the downcast produces valid
302 * handle. If not the returned handle is left uninitialized.
304 * @param[in] handle Handle to an object.
305 * @return Handle to an InputMethodContext or an uninitialized handle.
307 static InputMethodContext DownCast(BaseHandle handle);
311 * @brief Finalize the InputMethodContext.
313 * It means that the context will be deleted.
318 * @brief Activate the InputMethodContext.
320 * It means that the text editing is started at somewhere.
321 * If the H/W keyboard isn't connected then it will show the virtual keyboard.
326 * @brief Deactivate the InputMethodContext.
328 * It means that the text editing is finished at somewhere.
333 * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
335 * If true then keyboard will be restored (activated) after focus is regained.
336 * @return restoration status.
338 bool RestoreAfterFocusLost() const;
341 * @brief Set status whether the InputMethodContext has to restore the keyboard after losing focus.
343 * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
345 void SetRestoreAfterFocusLost(bool toggle);
348 * @brief Send message reset the pred-edit state / InputMethodContext module.
350 * Used to interupt pre-edit state maybe due to a touch input.
355 * @brief Notifies InputMethodContext that the cursor position has changed, required for features like auto-capitalisation.
357 void NotifyCursorPosition();
360 * @brief Sets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
362 * @param[in] cursorPosition position of cursor
364 void SetCursorPosition(unsigned int cursorPosition);
367 * @brief Gets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
369 * @return current position of cursor
371 unsigned int GetCursorPosition() const;
374 * @brief Method to store the string required by the InputMethodContext, this is used to provide predictive word suggestions.
376 * @param[in] text The text string surrounding the current cursor point.
378 void SetSurroundingText(const std::string& text);
381 * @brief Gets current text string set within the InputMethodContext manager, this is used to offer predictive suggestions.
383 * @return current position of cursor
385 const std::string& GetSurroundingText() const;
388 * @brief Notifies InputMethodContext that text input is set to multi line or not
390 * @param[in] multiLine True if multiline text input is used
392 void NotifyTextInputMultiLine(bool multiLine);
395 * @brief Returns text direction of the keyboard's current input language.
396 * @return The direction of the text.
398 TextDirection GetTextDirection();
401 * @brief Provides size and position of keyboard.
403 * Position is relative to whether keyboard is visible or not.
404 * If keyboard is not visible then position will be off the screen.
405 * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
406 * the values then taken down. So ideally GetInputMethodArea() should be called after Show().
407 * @return rect which is keyboard panel x, y, width, height
409 Dali::Rect<int> GetInputMethodArea();
412 * @brief Set one or more of the Input Method options
413 * @param[in] options The options to be applied
415 void ApplyOptions(const InputMethodOptions& options);
418 * @brief Sets up the input-panel specific data.
419 * @param[in] data The specific data to be set to the input panel
421 void SetInputPanelData(const std::string& data);
424 * @brief Gets the specific data of the current active input panel.
426 * Input Panel Data is not always the data which is set by SetInputPanelData().
427 * Data can be changed internally in the input panel.
428 * It is just used to get a specific data from the input panel to an application.
429 * @param[in] data The specific data to be got from the input panel
431 void GetInputPanelData(std::string& data);
434 * @brief Gets the state of the current active input panel.
435 * @return The state of the input panel.
437 State GetInputPanelState();
440 * @brief Sets the return key on the input panel to be visible or invisible.
442 * The default is true.
443 * @param[in] visible True if the return key is visible(enabled), false otherwise.
445 void SetReturnKeyState(bool visible);
448 * @brief Enable to show the input panel automatically when focused.
449 * @param[in] enabled If true, the input panel will be shown when focused
451 void AutoEnableInputPanel(bool enabled);
454 * @brief Shows the input panel.
456 void ShowInputPanel();
459 * @brief Hides the input panel.
461 void HideInputPanel();
464 * @brief Gets the keyboard type.
466 * The default keyboard type is SOFTWARE_KEYBOARD.
467 * @return The keyboard type
469 KeyboardType GetKeyboardType();
472 * @brief Gets the current language locale of the input panel.
474 * ex) en_US, en_GB, en_PH, fr_FR, ...
475 * @return The current language locale of the input panel
477 std::string GetInputPanelLocale();
480 * @brief Sets the allowed MIME Types to deliver to the input panel.
482 * ex) std::string mimeTypes = "text/plain,image/png,image/gif,application/pdf";
484 * You can receive a media content URI and its MIME type from ContentReceivedSignal(). @see ContentReceivedSignal
485 * @param[in] mimeTypes The allowed MIME types
487 void SetContentMIMETypes(const std::string& mimeTypes);
490 * @brief Process event key down or up, whether filter a key to isf.
492 * @param[in] keyEvent The event key to be handled.
493 * @return Whether the event key is handled.
495 bool FilterEventKey(const Dali::KeyEvent& keyEvent);
498 * @brief Sets whether the IM context should allow to use the text prediction.
500 * @param[in] prediction Whether to allow text prediction or not.
502 void AllowTextPrediction(bool prediction);
505 * @brief Gets whether the IM context allow to use the text prediction.
507 * @return Whether the IM allow text prediction or not.
509 bool IsTextPredictionAllowed() const;
512 * @brief Sets the language of the input panel.
514 * This method can be used when you want to show the English keyboard.
515 * @param[in] language The language to be set to the input panel
517 void SetInputPanelLanguage(InputPanelLanguage language);
520 * @brief Gets the language of the input panel.
522 * @return The language of the input panel
524 InputPanelLanguage GetInputPanelLanguage() const;
527 * @brief Sets the x,y coordinates of the input panel.
529 * @param[in] x The top-left x coordinate of the input panel
530 * @param[in] y The top-left y coordinate of the input panel
532 void SetInputPanelPosition(unsigned int x, unsigned int y);
535 * @brief Sets the alignment and its x, y coordinates of the input panel.
537 * Regardless of the rotation degree, the x, y values of the top-left corner on the screen are based on 0, 0.
538 * When the IME size is changed, its size will change according to the set alignment.
540 * @param[in] x The x coordinate of the InputPanelAlign value.
541 * @param[in] y The y coordinate of the InputPanelAlign value.
542 * @param[in] align one of the InputPanelAlign values specifying the desired alignment.
543 * @return true on success, false otherwise.
544 * @remarks This API can be used to set the alignment of a floating IME.
546 bool SetInputPanelPositionAlign(int x, int y, InputPanelAlign align);
549 * @brief Gets the preedit attributes data.
551 * @param[out] attrs The preedit attributes data.
553 void GetPreeditStyle(PreEditAttributeDataContainer& attrs) const;
559 * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
561 * @return The InputMethodContext Activated signal.
563 ActivatedSignalType& ActivatedSignal();
566 * @brief This is emitted when the InputMethodContext manager receives an event from the InputMethodContext.
568 * @return The Event signal containing the event data.
570 KeyboardEventSignalType& EventReceivedSignal();
573 * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
575 * A callback of the following type may be connected:
577 * void YourCallbackName(bool keyboardShown);
579 * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
580 * has just been hidden.
581 * @return The signal to connect to.
583 StatusSignalType& StatusChangedSignal();
586 * @brief Connect to this signal to be notified when the virtual keyboard is resized.
588 * A callback of the following type may be connected:
590 * void YourCallbackName( int resolvedResize );
592 * The parameter sends the resolved resize defined by the InputMethodContext.
594 * User can get changed size by using GetInputMethodArea() in the callback
595 * @return The signal to connect to.
597 KeyboardResizedSignalType& ResizedSignal();
600 * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
602 * A callback of the following type may be connected:
604 * void YourCallbackName( int resolvedLanguage );
606 * The parameter sends the resolved language defined by the InputMethodContext.
608 * User can get the text direction of the language by calling GetTextDirection() in the callback.
609 * @return The signal to connect to.
611 LanguageChangedSignalType& LanguageChangedSignal();
614 * @brief Connect to this signal to be notified when the keyboard type is changed.
616 * A callback of the following type may be connected:
618 * void YourCallbackName( KeyboardType keyboard );
621 * @return The signal to connect to.
623 KeyboardTypeSignalType& KeyboardTypeChangedSignal();
626 * @brief Connect to this signal to be notified when the content, such as images, of input method is received.
628 * A callback of the following type may be connected:
630 * void YourCallbackName( const std::string& contentUri, const std::string& description, const std::string& contentMIMEType );
633 * @return The signal to connect to.
635 ContentReceivedSignalType& ContentReceivedSignal();
639 * @brief This constructor is used by InputMethodContext::New().
641 * @param[in] inputMethodContext A pointer to the InputMethodContext.
643 explicit DALI_INTERNAL InputMethodContext(Internal::Adaptor::InputMethodContext* inputMethodContext);
648 #endif // DALI_INPUT_METHOD_CONTEXT_H