Input Method
PUBLISHED
The input method editor (IME) is an input panel (keyboard) that lets the user input text and the platform receive the entered data. The user can select an IME as their default keyboard in the device Settings application.
You can create a Tizen native IME application that provides a new IME. You can start the IME application life-cycle, interact with the current IME UI state, and retrieve attributes and events.
The main features of the Input Method API include:
- Managing the IME life-cycle
The system can have multiple keyboards, and the user can choose which one to use as the default keyboard. The IME application starts its life-cycle when it is selected as the default keyboard. The following figure shows the IME application life-cycle.
Figure: IME application life-cycle
The IME application runs as follows:
- Once the IME application is started, the
create()
callback function is called. - When a text input UI control gets the focus, the
show()
callback function is called.The IME application can call Input Method APIs to interact with the UI control. The event callback functions are called when the UI control state changes. When the text input UI control loses the focus, the
hide()
callback function is called. - When the IME application is finished, the
terminate()
callback function is called.
- Once the IME application is started, the
- Managing the main loop and event callback functions
The IME application must implement the
ime_app_main()
function. It is the main entry point, in which you can register event callback functions and call theime_run()
function to start the main loop.During its life-cycle, the IME application can receive a number of events from the Tizen input service framework through the callback functions. You must register the mandatory
create()
,terminate()
,show()
, andhide()
callbacks. Other callbacks can be registered as required by the specific IME application. - Showing and hiding the keyboard
When an associated text input UI control has the focus, the active keyboard is requested to be shown. When the text input UI control loses the focus, the keyboard is requested to be hidden.
The
show()
andhide()
callback functions are used to manage the keyboard visibility, and the IME application must register both of them when starting the IME main loop.The client application can set various configurations for each text input UI control, such as the cursor position, key layout type, return key type, and flags of predictive text. The configurations are delivered to the IME application though the
show()
callback function, to allow the keyboard to show the correct look to the user. - Using the keyboard option menu
Each keyboard can offer its own option menu to allow the user to manage the keyboard settings. Nowadays, most platforms provide the keyboard option menu from the device Settings application or from the keyboard directly.
You can register callback functions that are called when the keyboard option menu opens or closes. These callback functions can be registered before the
ime_run()
function call in theime_app_main()
function.The device Settings application triggers the callback function to open the keyboard option menu. The keyboard itself can also trigger the callback function to open its option menu.
Input Method Manager
The Input Method Manager (in mobile and wearable applications) is a module used to manage the installed IMEs. You can use it to open the installed IME list or selector menu after your IME application is installed, and guide the user to select the installed IME:
- Showing the IME list
You can request the installed IME list menu to be opened. If a new IME has been installed, the user can see its name in the IME list, and can use the toggle button to enable the keyboard they want. All keyboards enabled in the IME list are shown in the IME selector to allow the user to select them as the default keyboard.
Figure: IME list
- Showing the IME selector
You can request the IME selector menu to be opened. When the user opens the IME selector menu, it shows all the keyboards enabled in the IME list. The user can change the default keyboard by selecting a new one. By clicking Select keyboard, the user can return to the IME list menu to enable a new IME.
Figure: IME selector
- Checking the IME status
You can check whether a specific IME is enabled or disabled in the system keyboard setting. You can also check which IME is currently selected as the default keyboard, or how many IMEs are enabled (usable). These features are useful when the user installs a new keyboard.
Prerequisites
To enable your application to use the input method functionality:
-
To use the Input Method Manager API (in mobile and wearable applications), the application has to request permission by adding the following privilege to the
tizen-manifest.xml
file:<privileges> <privilege>http://tizen.org/privilege/imemanager</privilege> </privileges>
- To use the functions and data types of the Input Method API (in mobile and wearable applications), include the
<inputmethod.h>
header file in your application:
#include <inputmethod.h> #include <Elementary.h>
- To use the functions and data types of the Input Method Manager API, include the
<inputmethod_manager.h>
header file in your application:
#include <inputmethod_manager.h>
Starting the IME Life-cycle
To start the IME application life-cycle:
- Implement the
ime_app_main()
function as the main entry point of IME application:void ime_app_main(int argc, char **argv);
The function is called when the user selects the IME as default from the IME selector menu.
- Inside the
ime_app_main()
function, add the required callbacks and call theime_run()
function to start the application:
int ime_run(ime_callback_s *basic_cb, void *user_data);
Adding Event Callbacks
To register and define event callbacks for the IME application:
- Implement the mandatory callbacks:
-
You must register the
create()
,terminate()
,show()
, andhide()
callbacks.Add the callbacks to the
ime_callback_s
structure (in mobile and wearable applications), and pass the structure as a parameter to theime_run()
function:static void create(void *user_data); static void terminate(void *user_data); static void show(int context_id, ime_context_h context, void *user_data); static void hide(int context_id, void *user_data); void ime_app_main(int argc, char **argv) { ime_callback_s basic_callback = { create, /* When the input panel is created */ terminate, /* When the input panel is terminated */ show, /* When the input panel is shown */ hide, /* When the input panel is hidden */ }; ime_run(&basic_callback, NULL); }
- Define the callbacks:
static void create(void *user_data) { int portrait_w, portrait_h, landscape_w, landscape_h; Evas_Object *ime_win = ime_get_main_window(); /* Update IME size information */ ime_set_size(portrait_w, portrait_h, landscape_w, landscape_h); /* Create or initialize resources */ } static void terminate(void *user_data) { /* Release the resources */ } static void show(int context_id, ime_context_h context, void *user_data) { Ecore_IMF_Input_Panel_Layout layout; ime_layout_variation_e layout_variation; int cursor_pos; Ecore_IMF_Autocapital_Type autocapital_type; Ecore_IMF_Input_Panel_Return_Key_Type return_key_type; bool return_key_state, prediction_mode, password_mode; Ecore_IMF_Input_Hints input_hint; Ecore_IMF_BiDi_Direction bidi; Ecore_IMF_Input_Panel_Lang language; Evas_Object *ime_win = ime_get_main_window(); ime_context_get_layout(context, &layout); ime_context_get_layout_variation(context, &layout_variation); /* Draw the proper layout */ ime_context_get_autocapital_type(context, &autocapital_type); ime_context_get_cursor_position(context, &cursor_pos); /* Draw the capital or small characters accordingly */ ime_context_get_return_key_type(context, &return_key_type); ime_context_get_return_key_state(context, &return_key_state); /* Draw the proper Return key */ /* Show the IME window */ evas_object_show(ime_win); } static void hide(int context_id, void *user_data) { Evas_Object *ime_win = ime_get_main_window(); /* Hide the IME window */ evas_object_hide(ime_win); }
In the
show()
callback, the IME application can get the contextual information from an associated text input UI control to configure the keyboard state and look accordingly. The contextual information for each input UI control is provided through theime_context_get_XXX()
functions defined in theinputmethod.h
header file.
-
- Implementing the optional callbacks, as needed:
-
You can register optional callbacks with the
ime_event_set_XXX_cb()
functions provided in theinputmethod.h
header file:static int focus_in(int context_id, void *user_data); static int focus_out(int context_id, void *user_data); static int cursor_position_updated(int cursor_pos, void *user_data); void ime_app_main(int argc, char **argv) { ime_callback_s basic_callback = { /* Add the mandatory callbacks */ }; ime_event_set_focus_in_cb(focus_in, NULL); ime_event_set_focus_out_cb(focus_out, NULL); ime_event_set_cursor_position_updated_cb(cursor_position_updated, NULL); ime_run(&basic_callback, NULL); }
- Define the registered callbacks:
- The
focus_in()
callback is triggered when an associated text input UI control in any application gets the focus. Usually, thefocus_in()
event is followed by theshow()
event.static int focus_in(int context_id, void *user_data) { /* Take action */ }
- The
focus_out()
callback is triggered when an associated text input UI control in any application loses the focus. Usually, thefocus_out()
event is followed by thehide()
event.
static int focus_out(int context_id, void *user_data) { /* Take action */ }
- The
cursor_position_updated()
callback is triggered when the position of the cursor in an associated text input UI control changes. You can use this callback to provide, for example, auto-capitalization or predictive text features.
static int cursor_position_updated(int cursor_pos, void *user_data) { /* Take action */ }
- The
-
Making a Keyboard Option Menu
To make the option menu for the keyboard:
- Add the necessary callbacks for reacting to the keyboard option menu opening and closing, before calling the
ime_run()
function:static void option_window_created(Evas_Object *window, ime_option_window_type_e type, void *user_data); static void option_window_destroyed(Evas_Object *window, void *user_data); void ime_app_main(int argc, char **argv) { ime_callback_s basic_callback = { /* Add the mandatory callbacks */ }; ime_event_set_option_window_created_cb(option_window_created, NULL); ime_event_set_option_window_destroyed_cb(option_window_destroyed, NULL); ime_run(&basic_callback, NULL); }
- The option menu can be opened in 2 different ways:
- The device Settings application can open the keyboard option menu from Settings > Language and input > Keyboard > Keyboard settings.
If the user selects the keyboard settings, the
option_window_created()
callback is executed:static void option_window_created(Evas_Object *window, ime_option_window_type_e type, void *user_data) { /* Create the option window */ /* Draw the content to the given window object */ evas_object_show(window); }
- The keyboard can have a specific key button for its option menu, allowing the user to open the option menu directly from the keyboard.
If the user clicks the key button, you can use the
ime_create_option_window()
function in the button click callback to open the option menu:static void _clicked(void *data, Evas_Object *obj, void *event_info) { /* Open the IME option menu window */ ime_create_option_window(); }
The
ime_create_option_window()
function call triggers theoption_window_created()
callback, in which you can draw the option menu content on the given window.
- The device Settings application can open the keyboard option menu from Settings > Language and input > Keyboard > Keyboard settings.
- To close the option menu, call the
ime_destroy_option_window()
function. The function call triggers theoption_window_destroyed()
callback:
static void option_window_destroyed(Evas_Object *window, void *user_data) { /* Destroy the option window */ /* Release the resources */ }
Showing the IME List
To launch the IME list menu to show the installed IMEs, use the ime_manager_show_ime_list()
function:
void show_ime_list() { int ret = ime_manager_show_ime_list(); if (IME_MANAGER_ERROR_NONE != ret) /* Error handling */ }
If the menu opens successfully, the function returns 0.
Showing the IME Selector
To launch the IME selector menu to allow the user to select the default keyboard, use the ime_manager_show_ime_selector()
function:
void show_ime_selector() { int ret = ime_manager_show_ime_selector(); if (IME_MANAGER_ERROR_NONE != ret) /* Error handling */ }
If the menu opens successfully, the function returns 0.
Checking the IME State
To check the current default keyboard or whether a specific IME is enabled, or to get the number of enabled (usable) IMEs:
- To check whether a specific IME is enabled, call the
ime_manager_is_ime_enabled()
function. The first parameter is the application ID of the IME whose status you want to check.boolean is_ime_enabled(const char *app_id) { boolean enabled = false; int ret = ime_manager_is_ime_enabled(app_id, &enabled); if (IME_MANAGER_ERROR_NONE != ret) /* Error handling */ return enabled; }
If the function is successful, it returns 0.
- To check which IME is currently selected as the default keyboard, call the
ime_manager_get_active_ime()
function:
void get_active_ime() { char *app_id = NULL; int ret = ime_manager_get_active_ime(&app_id); if (IME_MANAGER_ERROR_NONE != ret) /* Error handling */ /* Take action */ free(app_id); }
If the function is successful, it returns 0.
- To get the number of enabled (usable) IMEs, call the
ime_manager_get_enabled_ime_count()
function:
int get_enabled_ime_count() { int count = ime_manager_get_enabled_ime_count(); if (count == 0) { if (get_last_result() != IME_MANAGER_ERROR_NONE) { /* Error handling */ } } /* Take action */ return count; }
If the function is successful, it returns the number of enabled IMEs. Otherwise, 0.