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 the preedit style types.
105 enum class PreeditStyle
107 NONE, ///< None style
108 UNDERLINE, ///< Underline substring style
109 REVERSE, ///< Reverse substring style
110 HIGHLIGHT, ///< Highlight substring style
111 CUSTOM_PLATFORM_STYLE_1, ///< Custom style for platform
112 CUSTOM_PLATFORM_STYLE_2, ///< Custom style for platform
113 CUSTOM_PLATFORM_STYLE_3, ///< Custom style for platform
114 CUSTOM_PLATFORM_STYLE_4 ///< Custom style for platform
118 * @brief This structure is for the preedit style types and indices.
120 struct PreeditAttributeData
122 PreeditAttributeData()
123 : preeditType(PreeditStyle::NONE),
129 PreeditStyle preeditType; /// The preedit style type
130 unsigned int startIndex; /// The start index of preedit
131 unsigned int endIndex; /// The end index of preedit
135 * @brief This structure is used to pass on data from the InputMethodContext regarding predictive text.
140 * @brief Default Constructor.
143 : predictiveString(),
153 * @param[in] aEventName The name of the event from the InputMethodContext.
154 * @param[in] aPredictiveString The pre-edit or commit string.
155 * @param[in] aCursorOffset Start position from the current cursor position to start deleting characters.
156 * @param[in] aNumberOfChars The number of characters to delete from the cursorOffset.
158 EventData(EventType aEventName, const std::string& aPredictiveString, int aCursorOffset, int aNumberOfChars)
159 : predictiveString(aPredictiveString),
160 eventName(aEventName),
161 cursorOffset(aCursorOffset),
162 numberOfChars(aNumberOfChars),
171 * @param[in] aEventName The name of the event from the InputMethodContext.
172 * @param[in] aStartIndex The start index of selection.
173 * @param[in] aEndIndex The end index of selection.
175 EventData(EventType aEventName, int aStartIndex, int aEndIndex)
176 : predictiveString(),
177 eventName(aEventName),
180 startIndex(aStartIndex),
186 std::string predictiveString; ///< The pre-edit or commit string.
187 EventType eventName; ///< The name of the event from the InputMethodContext.
188 int cursorOffset; ///< Start position from the current cursor position to start deleting characters.
189 int numberOfChars; ///< number of characters to delete from the cursorOffset.
190 int startIndex; ///< The start index of selection.
191 int endIndex; ///< The end index of selection.
195 * @brief Data required by InputMethodContext from the callback
206 preeditResetRequired(false)
212 * @param[in] aUpdate True if cursor position needs to be updated
213 * @param[in] aCursorPosition new position of cursor
214 * @param[in] aCurrentText current text string
215 * @param[in] aPreeditResetRequired flag if preedit reset is required.
217 CallbackData(bool aUpdate, int aCursorPosition, const std::string& aCurrentText, bool aPreeditResetRequired)
218 : currentText(aCurrentText),
219 cursorPosition(aCursorPosition),
221 preeditResetRequired(aPreeditResetRequired)
225 std::string currentText; ///< current text string
226 int cursorPosition; ///< new position of cursor
227 bool update : 1; ///< if cursor position needs to be updated
228 bool preeditResetRequired : 1; ///< flag if preedit reset is required.
231 typedef Signal<void(InputMethodContext&)> ActivatedSignalType; ///< Keyboard actived signal
232 typedef Signal<CallbackData(InputMethodContext&, const EventData&)> KeyboardEventSignalType; ///< keyboard events
233 typedef Signal<void()> VoidSignalType;
234 typedef Signal<void(bool)> StatusSignalType;
235 typedef Signal<void(KeyboardType)> KeyboardTypeSignalType; ///< keyboard type
236 typedef Signal<void(int)> KeyboardResizedSignalType; ///< Keyboard resized signal
237 typedef Signal<void(int)> LanguageChangedSignalType; ///< Language changed signal
238 typedef Signal<void(const std::string&, const std::string&, const std::string&)> ContentReceivedSignalType; ///< Content received signal
240 using PreEditAttributeDataContainer = Vector<Dali::InputMethodContext::PreeditAttributeData>;
244 * @brief Constructor.
246 InputMethodContext();
251 * This is non-virtual since derived Handle types must not contain data or virtual methods.
253 ~InputMethodContext();
256 * @brief Create a new instance of an InputMethodContext.
258 static InputMethodContext New();
261 * @brief Create a new instance of an InputMethodContext.
263 * @param[in] actor The actor that uses the new InputMethodContext instance.
265 static InputMethodContext New(Actor actor);
268 * @brief Copy constructor.
270 * @param[in] inputMethodContext InputMethodContext to copy. The copied inputMethodContext will point at the same implementation.
272 InputMethodContext(const InputMethodContext& inputMethodContext);
275 * @brief Assignment operator.
277 * @param[in] inputMethodContext The InputMethodContext to assign from.
278 * @return The updated InputMethodContext.
280 InputMethodContext& operator=(const InputMethodContext& inputMethodContext);
283 * @brief Downcast a handle to InputMethodContext handle.
285 * If handle points to an InputMethodContext the downcast produces valid
286 * handle. If not the returned handle is left uninitialized.
288 * @param[in] handle Handle to an object.
289 * @return Handle to an InputMethodContext or an uninitialized handle.
291 static InputMethodContext DownCast(BaseHandle handle);
295 * @brief Finalize the InputMethodContext.
297 * It means that the context will be deleted.
302 * @brief Activate the InputMethodContext.
304 * It means that the text editing is started at somewhere.
305 * If the H/W keyboard isn't connected then it will show the virtual keyboard.
310 * @brief Deactivate the InputMethodContext.
312 * It means that the text editing is finished at somewhere.
317 * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
319 * If true then keyboard will be restored (activated) after focus is regained.
320 * @return restoration status.
322 bool RestoreAfterFocusLost() const;
325 * @brief Set status whether the InputMethodContext has to restore the keyboard after losing focus.
327 * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
329 void SetRestoreAfterFocusLost(bool toggle);
332 * @brief Send message reset the pred-edit state / InputMethodContext module.
334 * Used to interupt pre-edit state maybe due to a touch input.
339 * @brief Notifies InputMethodContext that the cursor position has changed, required for features like auto-capitalisation.
341 void NotifyCursorPosition();
344 * @brief Sets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
346 * @param[in] cursorPosition position of cursor
348 void SetCursorPosition(unsigned int cursorPosition);
351 * @brief Gets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
353 * @return current position of cursor
355 unsigned int GetCursorPosition() const;
358 * @brief Method to store the string required by the InputMethodContext, this is used to provide predictive word suggestions.
360 * @param[in] text The text string surrounding the current cursor point.
362 void SetSurroundingText(const std::string& text);
365 * @brief Gets current text string set within the InputMethodContext manager, this is used to offer predictive suggestions.
367 * @return current position of cursor
369 const std::string& GetSurroundingText() const;
372 * @brief Notifies InputMethodContext that text input is set to multi line or not
374 * @param[in] multiLine True if multiline text input is used
376 void NotifyTextInputMultiLine(bool multiLine);
379 * @brief Returns text direction of the keyboard's current input language.
380 * @return The direction of the text.
382 TextDirection GetTextDirection();
385 * @brief Provides size and position of keyboard.
387 * Position is relative to whether keyboard is visible or not.
388 * If keyboard is not visible then position will be off the screen.
389 * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
390 * the values then taken down. So ideally GetInputMethodArea() should be called after Show().
391 * @return rect which is keyboard panel x, y, width, height
393 Dali::Rect<int> GetInputMethodArea();
396 * @brief Set one or more of the Input Method options
397 * @param[in] options The options to be applied
399 void ApplyOptions(const InputMethodOptions& options);
402 * @brief Sets up the input-panel specific data.
403 * @param[in] data The specific data to be set to the input panel
405 void SetInputPanelData(const std::string& data);
408 * @brief Gets the specific data of the current active input panel.
410 * Input Panel Data is not always the data which is set by SetInputPanelData().
411 * Data can be changed internally in the input panel.
412 * It is just used to get a specific data from the input panel to an application.
413 * @param[in] data The specific data to be got from the input panel
415 void GetInputPanelData(std::string& data);
418 * @brief Gets the state of the current active input panel.
419 * @return The state of the input panel.
421 State GetInputPanelState();
424 * @brief Sets the return key on the input panel to be visible or invisible.
426 * The default is true.
427 * @param[in] visible True if the return key is visible(enabled), false otherwise.
429 void SetReturnKeyState(bool visible);
432 * @brief Enable to show the input panel automatically when focused.
433 * @param[in] enabled If true, the input panel will be shown when focused
435 void AutoEnableInputPanel(bool enabled);
438 * @brief Shows the input panel.
440 void ShowInputPanel();
443 * @brief Hides the input panel.
445 void HideInputPanel();
448 * @brief Gets the keyboard type.
450 * The default keyboard type is SOFTWARE_KEYBOARD.
451 * @return The keyboard type
453 KeyboardType GetKeyboardType();
456 * @brief Gets the current language locale of the input panel.
458 * ex) en_US, en_GB, en_PH, fr_FR, ...
459 * @return The current language locale of the input panel
461 std::string GetInputPanelLocale();
464 * @brief Sets the allowed MIME Types to deliver to the input panel.
466 * ex) std::string mimeTypes = "text/plain,image/png,image/gif,application/pdf";
468 * You can receive a media content URI and its MIME type from ContentReceivedSignal(). @see ContentReceivedSignal
469 * @param[in] mimeTypes The allowed MIME types
471 void SetContentMIMETypes(const std::string& mimeTypes);
474 * @brief Process event key down or up, whether filter a key to isf.
476 * @param[in] keyEvent The event key to be handled.
477 * @return Whether the event key is handled.
479 bool FilterEventKey(const Dali::KeyEvent& keyEvent);
482 * @brief Sets whether the IM context should allow to use the text prediction.
484 * @param[in] prediction Whether to allow text prediction or not.
486 void AllowTextPrediction(bool prediction);
489 * @brief Gets whether the IM context allow to use the text prediction.
491 * @return Whether the IM allow text prediction or not.
493 bool IsTextPredictionAllowed() const;
496 * @brief Sets the language of the input panel.
498 * This method can be used when you want to show the English keyboard.
499 * @param[in] language The language to be set to the input panel
501 void SetInputPanelLanguage(InputPanelLanguage language);
504 * @brief Gets the language of the input panel.
506 * @return The language of the input panel
508 InputPanelLanguage GetInputPanelLanguage() const;
511 * @brief Sets the x,y coordinates of the input panel.
513 * @param[in] x The top-left x coordinate of the input panel
514 * @param[in] y The top-left y coordinate of the input panel
516 void SetInputPanelPosition(unsigned int x, unsigned int y);
519 * @brief Gets the preedit attributes data.
521 * @param[out] attrs The preedit attributes data.
523 void GetPreeditStyle(PreEditAttributeDataContainer& attrs) const;
529 * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
531 * @return The InputMethodContext Activated signal.
533 ActivatedSignalType& ActivatedSignal();
536 * @brief This is emitted when the InputMethodContext manager receives an event from the InputMethodContext.
538 * @return The Event signal containing the event data.
540 KeyboardEventSignalType& EventReceivedSignal();
543 * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
545 * A callback of the following type may be connected:
547 * void YourCallbackName(bool keyboardShown);
549 * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
550 * has just been hidden.
551 * @return The signal to connect to.
553 StatusSignalType& StatusChangedSignal();
556 * @brief Connect to this signal to be notified when the virtual keyboard is resized.
558 * A callback of the following type may be connected:
560 * void YourCallbackName( int resolvedResize );
562 * The parameter sends the resolved resize defined by the InputMethodContext.
564 * User can get changed size by using GetInputMethodArea() in the callback
565 * @return The signal to connect to.
567 KeyboardResizedSignalType& ResizedSignal();
570 * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
572 * A callback of the following type may be connected:
574 * void YourCallbackName( int resolvedLanguage );
576 * The parameter sends the resolved language defined by the InputMethodContext.
578 * User can get the text direction of the language by calling GetTextDirection() in the callback.
579 * @return The signal to connect to.
581 LanguageChangedSignalType& LanguageChangedSignal();
584 * @brief Connect to this signal to be notified when the keyboard type is changed.
586 * A callback of the following type may be connected:
588 * void YourCallbackName( KeyboardType keyboard );
591 * @return The signal to connect to.
593 KeyboardTypeSignalType& KeyboardTypeChangedSignal();
596 * @brief Connect to this signal to be notified when the content, such as images, of input method is received.
598 * A callback of the following type may be connected:
600 * void YourCallbackName( const std::string& contentUri, const std::string& description, const std::string& contentMIMEType );
603 * @return The signal to connect to.
605 ContentReceivedSignalType& ContentReceivedSignal();
609 * @brief This constructor is used by InputMethodContext::New().
611 * @param[in] inputMethodContext A pointer to the InputMethodContext.
613 explicit DALI_INTERNAL InputMethodContext(Internal::Adaptor::InputMethodContext* inputMethodContext);
618 #endif // DALI_INPUT_METHOD_CONTEXT_H