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(default). It can be changed according to OSD(On Screen Display) language.
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 Constructor.
222 InputMethodContext();
227 * This is non-virtual since derived Handle types must not contain data or virtual methods.
229 ~InputMethodContext();
232 * @brief Create a new instance of an InputMethodContext.
234 static InputMethodContext New();
237 * @brief Create a new instance of an InputMethodContext.
239 * @param[in] actor The actor that uses the new InputMethodContext instance.
241 static InputMethodContext New(Actor actor);
244 * @brief Copy constructor.
246 * @param[in] inputMethodContext InputMethodContext to copy. The copied inputMethodContext will point at the same implementation.
248 InputMethodContext(const InputMethodContext& inputMethodContext);
251 * @brief Assignment operator.
253 * @param[in] inputMethodContext The InputMethodContext to assign from.
254 * @return The updated InputMethodContext.
256 InputMethodContext& operator=(const InputMethodContext& inputMethodContext);
259 * @brief Downcast a handle to InputMethodContext handle.
261 * If handle points to an InputMethodContext the downcast produces valid
262 * handle. If not the returned handle is left uninitialized.
264 * @param[in] handle Handle to an object.
265 * @return Handle to an InputMethodContext or an uninitialized handle.
267 static InputMethodContext DownCast(BaseHandle handle);
271 * @brief Finalize the InputMethodContext.
273 * It means that the context will be deleted.
278 * @brief Activate the InputMethodContext.
280 * It means that the text editing is started at somewhere.
281 * If the H/W keyboard isn't connected then it will show the virtual keyboard.
286 * @brief Deactivate the InputMethodContext.
288 * It means that the text editing is finished at somewhere.
293 * @brief Get the restoration status, which controls if the keyboard is restored after the focus lost then regained.
295 * If true then keyboard will be restored (activated) after focus is regained.
296 * @return restoration status.
298 bool RestoreAfterFocusLost() const;
301 * @brief Set status whether the InputMethodContext has to restore the keyboard after losing focus.
303 * @param[in] toggle True means that keyboard should be restored after focus lost and regained.
305 void SetRestoreAfterFocusLost(bool toggle);
308 * @brief Send message reset the pred-edit state / InputMethodContext module.
310 * Used to interupt pre-edit state maybe due to a touch input.
315 * @brief Notifies InputMethodContext that the cursor position has changed, required for features like auto-capitalisation.
317 void NotifyCursorPosition();
320 * @brief Sets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
322 * @param[in] cursorPosition position of cursor
324 void SetCursorPosition(unsigned int cursorPosition);
327 * @brief Gets cursor position stored in VirtualKeyboard, this is required by the InputMethodContext.
329 * @return current position of cursor
331 unsigned int GetCursorPosition() const;
334 * @brief Method to store the string required by the InputMethodContext, this is used to provide predictive word suggestions.
336 * @param[in] text The text string surrounding the current cursor point.
338 void SetSurroundingText(const std::string& text);
341 * @brief Gets current text string set within the InputMethodContext manager, this is used to offer predictive suggestions.
343 * @return current position of cursor
345 const std::string& GetSurroundingText() const;
348 * @brief Notifies InputMethodContext that text input is set to multi line or not
350 * @param[in] multiLine True if multiline text input is used
352 void NotifyTextInputMultiLine(bool multiLine);
355 * @brief Returns text direction of the keyboard's current input language.
356 * @return The direction of the text.
358 TextDirection GetTextDirection();
361 * @brief Provides size and position of keyboard.
363 * Position is relative to whether keyboard is visible or not.
364 * If keyboard is not visible then position will be off the screen.
365 * If keyboard is not being shown when this method is called the keyboard is partially setup (IMFContext) to get
366 * the values then taken down. So ideally GetInputMethodArea() should be called after Show().
367 * @return rect which is keyboard panel x, y, width, height
369 Dali::Rect<int> GetInputMethodArea();
372 * @brief Set one or more of the Input Method options
373 * @param[in] options The options to be applied
375 void ApplyOptions(const InputMethodOptions& options);
378 * @brief Sets up the input-panel specific data.
379 * @param[in] data The specific data to be set to the input panel
381 void SetInputPanelData(const std::string& data);
384 * @brief Gets the specific data of the current active input panel.
386 * Input Panel Data is not always the data which is set by SetInputPanelData().
387 * Data can be changed internally in the input panel.
388 * It is just used to get a specific data from the input panel to an application.
389 * @param[in] data The specific data to be got from the input panel
391 void GetInputPanelData(std::string& data);
394 * @brief Gets the state of the current active input panel.
395 * @return The state of the input panel.
397 State GetInputPanelState();
400 * @brief Sets the return key on the input panel to be visible or invisible.
402 * The default is true.
403 * @param[in] visible True if the return key is visible(enabled), false otherwise.
405 void SetReturnKeyState(bool visible);
408 * @brief Enable to show the input panel automatically when focused.
409 * @param[in] enabled If true, the input panel will be shown when focused
411 void AutoEnableInputPanel(bool enabled);
414 * @brief Shows the input panel.
416 void ShowInputPanel();
419 * @brief Hides the input panel.
421 void HideInputPanel();
424 * @brief Gets the keyboard type.
426 * The default keyboard type is SOFTWARE_KEYBOARD.
427 * @return The keyboard type
429 KeyboardType GetKeyboardType();
432 * @brief Gets the current language locale of the input panel.
434 * ex) en_US, en_GB, en_PH, fr_FR, ...
435 * @return The current language locale of the input panel
437 std::string GetInputPanelLocale();
440 * @brief Sets the allowed MIME Types to deliver to the input panel.
442 * ex) std::string mimeTypes = "text/plain,image/png,image/gif,application/pdf";
444 * You can receive a media content URI and its MIME type from ContentReceivedSignal(). @see ContentReceivedSignal
445 * @param[in] mimeTypes The allowed MIME types
447 void SetContentMIMETypes(const std::string& mimeTypes);
450 * @brief Process event key down or up, whether filter a key to isf.
452 * @param[in] keyEvent The event key to be handled.
453 * @return Whether the event key is handled.
455 bool FilterEventKey(const Dali::KeyEvent& keyEvent);
458 * @brief Sets whether the IM context should allow to use the text prediction.
460 * @param[in] prediction Whether to allow text prediction or not.
462 void AllowTextPrediction(bool prediction);
465 * @brief Gets whether the IM context allow to use the text prediction.
467 * @return Whether the IM allow text prediction or not.
469 bool IsTextPredictionAllowed() const;
472 * @brief Sets the language of the input panel.
474 * This method can be used when you want to show the English keyboard.
475 * @param[in] language The language to be set to the input panel
477 void SetInputPanelLanguage(InputPanelLanguage language);
480 * @brief Gets the language of the input panel.
482 * @return The language of the input panel
484 InputPanelLanguage GetInputPanelLanguage() const;
487 * @brief Sets the x,y coordinates of the input panel.
489 * @param[in] x The top-left x coordinate of the input panel
490 * @param[in] y The top-left y coordinate of the input panel
492 void SetInputPanelPosition(unsigned int x, unsigned int y);
495 * @brief Gets the preedit attributes data.
497 * @param[out] attrs The preedit attributes data.
499 void GetPreeditStyle(PreEditAttributeDataContainer& attrs) const;
505 * @brief This is emitted when the virtual keyboard is connected to or the hardware keyboard is activated.
507 * @return The InputMethodContext Activated signal.
509 ActivatedSignalType& ActivatedSignal();
512 * @brief This is emitted when the InputMethodContext manager receives an event from the InputMethodContext.
514 * @return The Event signal containing the event data.
516 KeyboardEventSignalType& EventReceivedSignal();
519 * @brief Connect to this signal to be notified when the virtual keyboard is shown or hidden.
521 * A callback of the following type may be connected:
523 * void YourCallbackName(bool keyboardShown);
525 * If the parameter keyboardShown is true, then the keyboard has just shown, if it is false, then it
526 * has just been hidden.
527 * @return The signal to connect to.
529 StatusSignalType& StatusChangedSignal();
532 * @brief Connect to this signal to be notified when the virtual keyboard is resized.
534 * A callback of the following type may be connected:
536 * void YourCallbackName( int resolvedResize );
538 * The parameter sends the resolved resize defined by the InputMethodContext.
540 * User can get changed size by using GetInputMethodArea() in the callback
541 * @return The signal to connect to.
543 KeyboardResizedSignalType& ResizedSignal();
546 * @brief Connect to this signal to be notified when the virtual keyboard's language is changed.
548 * A callback of the following type may be connected:
550 * void YourCallbackName( int resolvedLanguage );
552 * The parameter sends the resolved language defined by the InputMethodContext.
554 * User can get the text direction of the language by calling GetTextDirection() in the callback.
555 * @return The signal to connect to.
557 LanguageChangedSignalType& LanguageChangedSignal();
560 * @brief Connect to this signal to be notified when the keyboard type is changed.
562 * A callback of the following type may be connected:
564 * void YourCallbackName( KeyboardType keyboard );
567 * @return The signal to connect to.
569 KeyboardTypeSignalType& KeyboardTypeChangedSignal();
572 * @brief Connect to this signal to be notified when the content, such as images, of input method is received.
574 * A callback of the following type may be connected:
576 * void YourCallbackName( const std::string& contentUri, const std::string& description, const std::string& contentMIMEType );
579 * @return The signal to connect to.
581 ContentReceivedSignalType& ContentReceivedSignal();
585 * @brief This constructor is used by InputMethodContext::New().
587 * @param[in] inputMethodContext A pointer to the InputMethodContext.
589 explicit DALI_INTERNAL InputMethodContext(Internal::Adaptor::InputMethodContext* inputMethodContext);
594 #endif // DALI_INPUT_METHOD_CONTEXT_H