Input Method: Managing Keyboards

This tutorial demonstrates how you create an IME application and use the input method manager to help the user enable and select the new IME as the default keyboard.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Input Method API basics by learning about:

Starting the IME Life-cycle
Start the IME application life-cycle.
Adding Event Callbacks
Register and define mandatory and optional event callbacks.
Making a Keyboard Option Menu
Create an option menu for the keyboard to handle the keyboard settings.
Input method manager
- Showing the IME List
  Open the IME list menu to show the installed IMEs to allow the user to enable them.
- Showing the IME Selector
  Open the IME selector menu to show the enabled IMEs to allow the user to select the default keyboard.
- Checking the IME State
  Check whether a specific IME is enabled, and which IME is currently selected as the default keyboard.

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 Keyboard selection menu in the Settings application.
Inside the ime_app_main() function, add the required callbacks and call the ime_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 and implement the create(), terminate(), show(), and hide() callback functions. Register them as the parameter of the ime_run() function:

#include <Elementary.h>
#include <inputmethod.h>

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 callback functions:

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 the 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 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 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 of each input UI control is provided through the ime_context_get_XXX() functions in the inputmethod.h header file.

Implementing the optional callbacks, as needed:

You can register optional callbacks with the ime_event_set_XXX_cb() functions provided in the inputmethod.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 optional callback functions:
- The focus_in() callback is triggered when an associated text input UI control in any application gets the focus. Usually, the focus_in() event is followed by the show() 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, the focus_out() event is followed by the hide() 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
}
```

To make the option menu for the keyboard:

Add the necessary callback functions 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 the option_window_created() callback, in which you can draw the option menu content on the given window.

To close the option menu, call the ime_destroy_option_window() function. The function call triggers the option_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:

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>
```
Add the http://tizen.org/privilege/imemanager privilege to the application manifest file.

Open the IME list menu with 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:

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>
```
Add the http://tizen.org/privilege/imemanager privilege to the application manifest file.

Open the IME selector menu with 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:

Add the http://tizen.org/privilege/imemanager privilege to the application manifest file.

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 current 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);
}