Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Extending Hildon Input Methods

= Extending Hildon Input Methods =

Overview
Maemo platform is intended to be used on embedded devices. It is a quite straightforward request that one might want to have different input methods from the ones available by default, or just simply want a different layout for the virtual keyboard. For this reason, maemo 4.1 introduces a way to enable writing custom plug-ins for Hildon Input Method.

This section describes writing a simple plug-in for Hildon Input Method. This example plug-in is going to implement a very basic virtual keyboard.

The illustration below shows what area of the Hildon Input Method can be redefined with the custom plug-in.



Technically, the plug-in is an almost standard GTK widget (with additional steps to support dynamic loading). The widget of the plug-in will be placed in the Plug-in area.

The illustration below shows the data flow of a user's input:



User inputs directly to the plug-in, then the plug-in sends the inputted data to HIM main user interface. The HIM main UI will interact with the IM context, and then commit the inputted text to the client widget.

In case of a custom plug-in, the plug-in itself - i.e. its writer - is responsible for handling all the inputs (even the buttons that are part of HIM main UI, e.g. tab or enter) and propagate them to the right modules (e.g. IM context).

The function and outlook of the buttons in HIM main UI can be customized, but one cannot remove them completely from the UI - only dim them (see handwriting plug-in), and they cannot be rearranged (for further information, see section Common buttons).

Plug-in features
Hildon Input Method plug-in must be a GTK widget. In addition to the GTK widget interface, the plug-in must implement certain functions.

Interface
As already mentioned, the plug-in must handle all the inputs - both real user input and management signals from the system - that are coming to the HIM main UI. The first step is to take a look at which functions need to be implemented and provided by the plug-in to the Hildon Input Method Plug-in Interface. Later on, it will be shown how these functions are actually registered for the HIM Plug-in Interface.

The essential functions that must be implemented by a basic plug-in:

 void (* enable )  ( HildonIMPlugin  * plugin , gboolean init );  enable is called whenever the plug-in becomes available to the user. init holds TRUE whenever this is the initialization time. hildon-input-method-plugins-example/src/him-vkb-example.c   /* Called when the plugin is available to the user */   static  void  enable  ( HildonIMPlugin  * plugin <font color="#990000">, gboolean init <font color="#990000">) <font color="#FF0000">{ HimExampleVKBPrivate <font color="#990000"> * priv <font color="#990000"> ; HimExampleVKB <font color="#990000"> * vkb <font color="#990000"> ; vkb <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB   <font color="#990000">( plugin <font color="#990000">); priv <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB_GET_PRIVATE   <font color="#990000">( vkb <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">( init <font color="#990000"> == TRUE <font color="#990000">) <font color="#FF0000">{  <font color="#000000">hildon_im_ui_button_set_toggle  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,        HILDON_IM_BUTTON_MODE_A <font color="#990000">, TRUE <font color="#990000">);  <font color="#000000">hildon_im_ui_button_set_toggle  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,        HILDON_IM_BUTTON_MODE_B <font color="#990000">, TRUE <font color="#990000">);  <font color="#000000">hildon_im_ui_button_set_label  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,        HILDON_IM_BUTTON_MODE_A <font color="#990000">,  <font color="#FF0000">"ABC"  <font color="#990000">);  <font color="#000000">hildon_im_ui_button_set_label  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,        HILDON_IM_BUTTON_MODE_B <font color="#990000">,  <font color="#FF0000">"Shift"  <font color="#990000">); <font color="#FF0000">}  <font color="#000000">hildon_im_ui_send_communication_message  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">, HILDON_IM_CONTEXT_DIRECT_MODE <font color="#990000">); <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* disable <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> disable is called whenever the plug-in becomes unavailable to the user (e.g. when the main UI is closed). hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when the plugin is disabled */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">disable  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* not implemented */  <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* settings_changed <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">,                             <font color="#0000FF">const  gchar <font color="#990000"> * key <font color="#990000">,                             <font color="#0000FF">const  GConfValue <font color="#990000"> * value <font color="#990000">); </tt> settings_changed is called whenever the HIM main UI receives a notification from GConf about Hildon Input Method settings being changed. The affected settings are all settings residing in /apps/osso/inputmethod path. key and value hold the GConf key and its value respectively. hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when the standard input method settings   <font color="#9A1900"> has been changed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">settings_changed  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">,       <font color="#0000FF">const  gchar <font color="#990000"> * key <font color="#990000">,   <font color="#0000FF">const  GConfValue <font color="#990000"> * value <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* not implemented */  <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* input_mode_changed <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> input_mode_changed is called whenever the input mode is changed. Input mode is changed to what has been specified by the client widget. The input mode puts constraints to the plug-in to limit whether input shall be accepted or ignored. hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when input mode changed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">input_mode_changed  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* not implemented */  <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* clear <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> clear is called whenever the HIM main UI requests the plug-in to clear or refresh its user interface. hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when the plugin is requested to 'clear'/refresh its UI */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">clear  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* not implemented */  <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* client_widget_changed <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> client_widget_changed is called whenever the client widget is changed from one to another. For instance, the case could be that the user taps on another text entry. hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when the client widget changed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">client_widget_changed  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* not implemented */  <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* save_data <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> save_data is called whenever the HIM main UI is requested to save its (and the plug-in's) data. Usually it is called when the main UI is requested to quit. hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when the plugin is requested to save its data */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">save_data  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* not implemented */  <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* mode_a <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> mode_a is called whenever the Mode A (Caps Lock in virtual keyboard plug-in) is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when the MODE_A button is pressed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">mode_a  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{ HimExampleVKBPrivate <font color="#990000"> * priv <font color="#990000"> ; HimExampleVKB <font color="#990000"> * vkb <font color="#990000"> ; vkb <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB   <font color="#990000">( plugin <font color="#990000">); priv <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB_GET_PRIVATE   <font color="#990000">( vkb <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">(   <font color="#000000">hildon_im_ui_button_get_active   <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">, HILDON_IM_BUTTON_MODE_B <font color="#990000">)) <font color="#FF0000">{  <font color="#000000">hildon_im_ui_button_set_active  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,          HILDON_IM_BUTTON_MODE_B <font color="#990000">, FALSE <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">(   <font color="#000000">hildon_im_ui_button_get_active   <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">, HILDON_IM_BUTTON_MODE_A <font color="#990000">)) <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_UPPER <font color="#990000"> ; <font color="#FF0000">}  <font color="#0000FF">else   <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_LOWER <font color="#990000"> ; <font color="#FF0000">} <font color="#FF0000">}  <font color="#0000FF">else   <font color="#FF0000">{  <font color="#0000FF">if  <font color="#990000">(   <font color="#000000">hildon_im_ui_button_get_active   <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">, HILDON_IM_BUTTON_MODE_A <font color="#990000">)) <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_UPPER <font color="#990000"> ; <font color="#FF0000">}  <font color="#0000FF">else   <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_LOWER <font color="#990000"> ; <font color="#FF0000">} <font color="#FF0000">}  <font color="#000000">update_layout  <font color="#990000">( vkb <font color="#990000">); <font color="#FF0000">} </tt>  <font color="#009900">void <font color="#990000">(* mode_b <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> mode_b is called whenever the Mode B (Shift in virtual keyboard plug-in) is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c   <font color="#9A1900">/* Called when the MODE_B button is pressed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">mode_b  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{ HimExampleVKBPrivate <font color="#990000"> * priv <font color="#990000"> ; HimExampleVKB <font color="#990000"> * vkb <font color="#990000"> ; vkb <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB   <font color="#990000">( plugin <font color="#990000">); priv <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB_GET_PRIVATE   <font color="#990000">( vkb <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">(   <font color="#000000">hildon_im_ui_button_get_active   <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">, HILDON_IM_BUTTON_MODE_B <font color="#990000">)) <font color="#FF0000">{  <font color="#0000FF">if  <font color="#990000">(   <font color="#000000">hildon_im_ui_button_get_active   <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">, HILDON_IM_BUTTON_MODE_A <font color="#990000">)) <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_LOWER <font color="#990000"> ; <font color="#FF0000">}  <font color="#0000FF">else   <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_UPPER <font color="#990000"> ; <font color="#FF0000">} <font color="#FF0000">}  <font color="#0000FF">else   <font color="#FF0000">{  <font color="#0000FF">if  <font color="#990000">(   <font color="#000000">hildon_im_ui_button_get_active   <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">, HILDON_IM_BUTTON_MODE_A <font color="#990000">)) <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_UPPER <font color="#990000"> ; <font color="#FF0000">}  <font color="#0000FF">else   <font color="#FF0000">{ priv <font color="#990000">-&gt; case_mode <font color="#990000"> = CASE_LOWER <font color="#990000"> ; <font color="#FF0000">} <font color="#FF0000">}  <font color="#000000">update_layout  <font color="#990000">( vkb <font color="#990000">); <font color="#FF0000">} </tt> <tt> <font color="#009900">void <font color="#990000">(* backspace <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> backspace is called whenever the virtual backspace key is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c <tt>  <font color="#9A1900">/* Called when the backspace button is pressed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">backspace  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{ HimExampleVKBPrivate <font color="#990000"> * priv <font color="#990000"> ; priv <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB_GET_PRIVATE   <font color="#990000">(   <font color="#000000">HIMEXAMPLE_VKB   <font color="#990000">( plugin <font color="#990000">));  <font color="#000000">hildon_im_ui_send_communication_message  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,        HILDON_IM_CONTEXT_HANDLE_BACKSPACE <font color="#990000">); <font color="#FF0000">} </tt> <tt> <font color="#009900">void <font color="#990000">(* enter <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> enter is called whenever the virtual enter key is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c <tt>  <font color="#9A1900">/* Called when the enter button is pressed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">enter  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{ HimExampleVKBPrivate <font color="#990000"> * priv <font color="#990000"> ; priv <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB_GET_PRIVATE   <font color="#990000">(   <font color="#000000">HIMEXAMPLE_VKB   <font color="#990000">( plugin <font color="#990000">));  <font color="#000000">hildon_im_ui_send_communication_message  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,        HILDON_IM_CONTEXT_HANDLE_ENTER <font color="#990000">); <font color="#FF0000">} </tt> <tt> <font color="#009900">void <font color="#990000">(* tab <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> tab is called whenever the virtual tab key is pressed. hildon-input-method-plugins-example/src/him-vkb-example.c <tt>  <font color="#9A1900">/* Called when the tab button is pressed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">tab  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{ HimExampleVKBPrivate <font color="#990000"> * priv <font color="#990000"> ; priv <font color="#990000"> =  <font color="#000000">HIMEXAMPLE_VKB_GET_PRIVATE   <font color="#990000">(   <font color="#000000">HIMEXAMPLE_VKB   <font color="#990000">( plugin <font color="#990000">));  <font color="#000000">hildon_im_ui_send_communication_message  <font color="#990000">( priv <font color="#990000">-&gt; ui <font color="#990000">,        HILDON_IM_CONTEXT_HANDLE_TAB <font color="#990000">); <font color="#FF0000">} </tt>
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h

Couple of functions related to changing language:

<tt> <font color="#009900">void <font color="#990000">(* language <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">); </tt> language is called whenever a new language is selected from the HIM main UI menu. hildon-input-method-plugins-example/src/him-vkb-example.c <tt>  <font color="#9A1900">/* Called when the language has been changed */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">language  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* not implemented */  <font color="#FF0000">} </tt> <tt> <font color="#009900">void <font color="#990000">(* language_settings_changed <font color="#990000">)  <font color="#990000">( HildonIMPlugin <font color="#990000"> * plugin <font color="#990000">, gint index <font color="#990000">); </tt> language_settings_changed is called whenever the language settings for the specified language index have been changed.
 * hildon-input-method/hildon-im-plugin.h
 * hildon-input-method/hildon-im-plugin.h

Plug-in Loading
A nature of a plug-in is that it can be dynamically loaded. In this case also, the HIM plug-in is loaded whenever the user selects it, so in order to support the dynamic loading, the plug-in has to provide the following three specific functions for Hildon Input Method plug-in system:

</tt> This function initializes the plug-in as a module, meaning the type of GTypeInfo needs to be registered, and the interface and instance information (GInterfaceInfo) need to be added to the module. hildon-input-method-plugins-example/src/him-vkb-example.c <tt> <font color="#009900">void  <font color="#000000">module_init  <font color="#990000">( GTypeModule <font color="#990000"> * module <font color="#990000">) <font color="#FF0000">{  <font color="#0000FF">static   <font color="#0000FF">const  GTypeInfo type_info <font color="#990000"> =  <font color="#FF0000">{  <font color="#0000FF">sizeof  <font color="#990000">( HimExampleVKBClass <font color="#990000">), NULL <font color="#990000">,  <font color="#9A1900">/* base_init */  NULL <font color="#990000">,  <font color="#9A1900">/* base_finalize */  <font color="#990000">( GClassInitFunc <font color="#990000">) himExample_vkb_class_init <font color="#990000">, NULL <font color="#990000">,  <font color="#9A1900">/* class_finalize */  NULL <font color="#990000">,  <font color="#9A1900">/* class_data */   <font color="#0000FF">sizeof  <font color="#990000">( HimExampleVKB <font color="#990000">), <font color="#993399">0 <font color="#990000">,   <font color="#9A1900">/* n_preallocs */  <font color="#990000">( GInstanceInitFunc <font color="#990000">) himExample_vkb_init <font color="#990000">, <font color="#FF0000">} <font color="#990000"> ;  <font color="#0000FF">static   <font color="#0000FF">const  GInterfaceInfo plugin_info <font color="#990000"> =  <font color="#FF0000">{ <font color="#990000">( GInterfaceInitFunc <font color="#990000">) himExample_vkb_iface_init <font color="#990000">, NULL <font color="#990000">,  <font color="#9A1900">/* interface_finalize */  NULL <font color="#990000">,  <font color="#9A1900">/* interface_data */  <font color="#FF0000">} <font color="#990000"> ; himExample_vkb_type <font color="#990000"> =  <font color="#000000">g_type_module_register_type  <font color="#990000">( module <font color="#990000">,                                        GTK_TYPE_WIDGET <font color="#990000">,  <font color="#FF0000">"HimExampleVKB"  <font color="#990000">,                                        <font color="#990000">&amp; type_info <font color="#990000">,                                        <font color="#993399">0  <font color="#990000">);  <font color="#000000">g_type_module_add_interface  <font color="#990000">( module <font color="#990000">,                                HIMEXAMPLE_VKB_TYPE <font color="#990000">,                                HILDON_IM_TYPE_PLUGIN <font color="#990000">,                                <font color="#990000">&amp; plugin_info <font color="#990000">); <font color="#FF0000">} </tt> The himExample_vkb_iface_init function should register the custom interface functions in HildonIMPluginIface : hildon-input-method-plugins-example/src/him-vkb-example.c <tt>  <font color="#9A1900">/* Standard GTK stuff */   <font color="#0000FF">static  <font color="#009900">void  <font color="#000000">himExample_vkb_iface_init  <font color="#990000">( HildonIMPluginIface <font color="#990000"> * iface <font color="#990000">) <font color="#FF0000">{ iface <font color="#990000">-&gt; enable <font color="#990000"> = enable <font color="#990000"> ; iface <font color="#990000">-&gt; disable <font color="#990000"> = disable <font color="#990000"> ; iface <font color="#990000">-&gt; enter <font color="#990000"> = enter <font color="#990000"> ; iface <font color="#990000">-&gt; tab <font color="#990000"> = tab <font color="#990000"> ; iface <font color="#990000">-&gt; backspace <font color="#990000"> = backspace <font color="#990000"> ; iface <font color="#990000">-&gt; clear <font color="#990000"> = clear <font color="#990000"> ; iface <font color="#990000">-&gt; input_mode_changed <font color="#990000"> = input_mode_changed <font color="#990000"> ; iface <font color="#990000">-&gt; client_widget_changed <font color="#990000"> = client_widget_changed <font color="#990000"> ; iface <font color="#990000">-&gt; save_data <font color="#990000"> = save_data <font color="#990000"> ; iface <font color="#990000">-&gt; language <font color="#990000"> = language <font color="#990000"> ; iface <font color="#990000">-&gt; mode_a <font color="#990000"> = mode_a <font color="#990000"> ; iface <font color="#990000">-&gt; mode_b <font color="#990000"> = mode_b <font color="#990000"> ; iface <font color="#990000">-&gt; language_settings_changed <font color="#990000"> = language_settings_changed <font color="#990000"> ; iface <font color="#990000">-&gt; settings_changed <font color="#990000"> = settings_changed <font color="#990000"> ;  <font color="#0000FF">return  <font color="#990000"> ; <font color="#FF0000">} </tt> </tt> This function defines actions when the module is unloaded from the memory. hildon-input-method-plugins-example/src/him-vkb-example.c <tt> <font color="#009900">void  <font color="#000000">module_exit  <font color="#990000">(  <font color="#009900">void  <font color="#990000">) <font color="#FF0000">{  <font color="#9A1900">/* empty */  <font color="#FF0000">} </tt> </tt> This function creates and returns the plug-in widget to the main UI. hildon-input-method-plugins-example/src/him-vkb-example.c <tt>HildonIMPlugin <font color="#990000"> *  <font color="#000000">module_create  <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">) <font color="#FF0000">{  <font color="#0000FF">return   <font color="#000000">HILDON_IM_PLUGIN   <font color="#990000">(   <font color="#000000">himExample_vkb_new   <font color="#990000">( keyboard <font color="#990000">)); <font color="#FF0000">} </tt>
 * <tt> <font color="#009900">void  <font color="#000000">module_init   <font color="#990000">( GTypeModule <font color="#990000"> * module <font color="#990000">);
 * <tt> <font color="#009900">void  <font color="#000000">module_exit   <font color="#990000">(  <font color="#009900">void  <font color="#990000">);
 * <tt>HildonIMPlugin <font color="#990000"> *  <font color="#000000">module_create   <font color="#990000">( HildonIMUI <font color="#990000"> * ui <font color="#990000">);

Plug-in Info
Some basic information of the plug-in needs to be provided to the HIM plug-in system, so it can keep up with the kinds of plug-ins that are available in the system. This is performed with two specific functions:

</tt> The function creates HildonIMPluginInfo struct for providing the required information. hildon-input-method-plugins-example/src/him-vkb-example.c <tt> '' <font color="#9A1900">/* Input Method plugin information.   <font color="#9A1900"> * This structure tells the main UI about this plugin */ ''  <font color="#0000FF">const  HildonIMPluginInfo <font color="#990000"> *  <font color="#000000">hildon_im_plugin_get_info  <font color="#990000">(  <font color="#009900">void  <font color="#990000">) <font color="#FF0000">{  <font color="#0000FF">static   <font color="#0000FF">const  HildonIMPluginInfo info <font color="#990000"> = <font color="#FF0000">{ <font color="#FF0000">"HIM VKB Example" <font color="#990000">,                   <font color="#9A1900">/* description */  <font color="#FF0000">"himExample_vkb" <font color="#990000">,                    <font color="#9A1900">/* name */  <font color="#FF0000">"Keyboard (EXAMPLE)" <font color="#990000">,                <font color="#9A1900">/* menu title */  NULL <font color="#990000">,                               <font color="#9A1900">/* gettext domain */  TRUE <font color="#990000">,                               <font color="#9A1900">/* visible in menu */  FALSE <font color="#990000">,                              <font color="#9A1900">/* cached */  HILDON_IM_TYPE_DEFAULT <font color="#990000">,             <font color="#9A1900">/* UI type */  HILDON_IM_GROUP_LATIN <font color="#990000">,              <font color="#9A1900">/* group */  HILDON_IM_DEFAULT_PLUGIN_PRIORITY <font color="#990000">,  <font color="#9A1900">/* priority */  NULL <font color="#990000">,                               <font color="#9A1900">/* special character plugin */  <font color="#FF0000">"" <font color="#990000">,                                  <font color="#9A1900">/* help page */  FALSE <font color="#990000">,                              <font color="#9A1900">/* disable common UI buttons */  HILDON_IM_DEFAULT_HEIGHT <font color="#990000">,           <font color="#9A1900">/* plugin height */  HILDON_IM_TRIGGER_STYLUS            <font color="#9A1900">/* trigger */  <font color="#FF0000">} <font color="#990000"> ;  <font color="#0000FF">return  <font color="#990000">&amp; info <font color="#990000"> ; <font color="#FF0000">} </tt> </tt> The function returns a NULL terminated array of string, containing language codes supported by the plug-in. Set free to TRUE if HIM main UI should free the returned value when no longer used. hildon-input-method-plugins-example/src/him-vkb-example.c <tt>  <font color="#9A1900">/*   <font color="#9A1900"> * This function returns the list of available languages supported  '' <font color="#9A1900"> * by the plugin.   <font color="#9A1900"> * */ '' gchar <font color="#990000"> **  <font color="#000000">hildon_im_plugin_get_available_languages  <font color="#990000">( gboolean <font color="#990000"> * free <font color="#990000">) <font color="#FF0000">{  <font color="#0000FF">static  gchar <font color="#990000"> * list <font color="#990000">[] <font color="#990000"> =  <font color="#FF0000">{  <font color="#FF0000">"en_GB"  <font color="#990000">, NULL <font color="#FF0000">}  <font color="#990000"> ; <font color="#990000"> * free <font color="#990000"> = FALSE <font color="#990000"> ;  <font color="#0000FF">return  list <font color="#990000"> ; <font color="#FF0000">} </tt>
 * <tt>  <font color="#0000FF">const  HildonIMPluginInfo <font color="#990000"> *  <font color="#000000">hildon_im_plugin_get_info   <font color="#990000">(  <font color="#009900">void  <font color="#990000">);
 * <tt>gchar <font color="#990000"> **  <font color="#000000">hildon_im_plugin_get_available_languages   <font color="#990000">( gboolean <font color="#990000"> * free <font color="#990000">);

Interaction with main user interface
As mentioned above, the plug-in is placed inside the HIM main UI. This section deals with interacting with it. This is mainly done by calling its functions, as defined in hildon-im-ui.h.

Handling Input
hildon-input-method/hildon-im-ui.h

<tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_send_utf8   <font color="#990000">( HildonIMUI <font color="#990000"> * main_ui <font color="#990000">,   <font color="#0000FF">const  gchar <font color="#990000"> * text <font color="#990000">); </tt>

The plug-in can request the main UI to commit a UTF-8 encoded text by calling this function. hildon-input-method/hildon-im-ui.h

<tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_send_communication_message   <font color="#990000">( HildonIMUI <font color="#990000"> * main_ui <font color="#990000">, gint message <font color="#990000">); </tt>

The plug-in can use this function to tell the main UI that Enter, Backspace, or Tab virtual buttons are pressed. Simply call this function and pass one of the constants below as the message argument:



UI Visibility
hildon-input-method/hildon-im-ui.h

<tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_set_visible   <font color="#990000">( HildonIMUI <font color="#990000"> * ui <font color="#990000">, gboolean visible <font color="#990000">); </tt>

The plug-in can request the main UI to set it's visibility by calling this function. hildon-input-method/hildon-im-ui.h

<tt>gboolean  <font color="#000000">hildon_im_ui_get_visibility  <font color="#990000">( HildonIMUI <font color="#990000"> * main_ui <font color="#990000">); </tt>

By calling this function, the plug-in can get the visibility status of the main UI.

Get Input Method State
The following two state reader functions could be very handy in case the plug-in receives a state change notification (e.g. language change), because this way all the state information does not need to be saved. hildon-input-method/hildon-im-ui.h

<tt>HildonIMCommand  <font color="#000000">hildon_im_ui_get_autocase_mode  <font color="#990000">( HildonIMUI <font color="#990000"> * main_ui <font color="#990000">); </tt>

The function returns the auto-capitalization mode of the current client widget. hildon-input-method/hildon-im-ui.h

<tt>  <font color="#0000FF">const  gchar <font color="#990000"> *  <font color="#000000">hildon_im_ui_get_active_language   <font color="#990000">( HildonIMUI <font color="#990000"> * main_ui <font color="#990000">); </tt>

The function returns the current language code.

Common Buttons
As mentioned in the Overview section, the outlook and even the function of the buttons in the main UI can be modified. N.B. It is not recommended to alter buttons, except the Mode A and Mode B buttons! Other buttons may have hardwired behavior within the main UI.

If the plug-in changes the functionality of a button, one might want to reflect this also in the UI by changing the label of the button. The layout of the buttons can be altered by the following two functions:

<tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_button_set_label   <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">,                                     HildonIMButton button <font color="#990000">,                                      <font color="#0000FF">const  gchar <font color="#990000"> * label <font color="#990000">); </tt> With this function, the plug-in can set the label of a button. Possible values of HildonIMButton (see hildon-im-ui.h): <tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_button_set_id   <font color="#990000">( HildonIMUI <font color="#990000"> * self <font color="#990000">,                                  HildonIMButton button <font color="#990000">,                                   <font color="#0000FF">const  gchar <font color="#990000"> * id <font color="#990000">); </tt> This function sets a name to a particular button.
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h

Since every input to the HIM main UI is caught by the plug-in, it is necessary to keep the button state (active or in-active) in sync. The state of a particular button can be changed, queried and toggled with the following functions:

<tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_button_set_active   <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">,                                      HildonIMButton button <font color="#990000">,                                      gboolean active <font color="#990000">); </tt> This function sets the active state of a particular button. <tt>gboolean  <font color="#000000">hildon_im_ui_button_get_active  <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">,                                          HildonIMButton button <font color="#990000">); </tt> This function returns the active state of a particular button. <tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_button_set_toggle   <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">,                                      HildonIMButton button <font color="#990000">,                                      gboolean toggle <font color="#990000">); </tt> The plug-in can set the toggle state of a particular button with this function.
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h

Miscellaneous button manipulation functions:

<tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_button_set_menu   <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">,                                    HildonIMButton button <font color="#990000">,                                    GtkWidget <font color="#990000"> * menu <font color="#990000">); </tt> With this function, the plug-in can attach a menu - which is a GtkWidget - to a particular button. <tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_button_set_sensitive   <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">,                                         HildonIMButton button <font color="#990000">,                                         gboolean sensitive <font color="#990000">); </tt> All the buttons defined on the HIM main UI may not be needed, or the functionality of a button may be wished to be switched off in some states. In this case, the sensitivity of a particular button can be set by calling this function. <tt> <font color="#009900">void  <font color="#000000">hildon_im_ui_button_set_repeat   <font color="#990000">( HildonIMUI <font color="#990000"> * keyboard <font color="#990000">,                                      HildonIMButton button <font color="#990000">,                                      gboolean repeat <font color="#990000">); </tt> This function controls whether a particular button will repeat when pressed for a long time.
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h
 * hildon-input-method/hildon-im-ui.h

Component dependencies
At least the following headers shall be included in the plug-in:

<tt>  <font color="#000080"> #include  <font color="#FF0000">&lt;hildon-im-plugin.h&gt;  <font color="#000080"> #include  <font color="#FF0000">&lt;hildon-im-ui.h&gt; </tt>

hildon-input-method-framework-dev and libhildon-im-ui-dev packages.

Language codes
These are the language codes recognized; they are numbered, the first, af_ZA, being 0.

af_ZA am_ET ar_AE ar_BH ar_DZ ar_EG ar_IN ar_IQ ar_JO ar_KW ar_LB ar_LY ar_MA ar_OM ar_QA ar_SA ar_SD ar_SY ar_TN ar_YE az_AZ be_BY bg_BG bn_IN br_FR bs_BA ca_ES cs_CZ cy_GB da_DK de_AT de_BE de_CH de_DE de_LU el_GR en_AU en_BW en_CA en_DK en_GB en_HK en_IE en_IN en_NZ en_PH en_SG en_US en_ZA en_ZW eo_EO es_AR es_BO es_CL es_CO es_CR es_DO es_EC es_ES es_GT es_HN es_MX es_NI es_PA es_PE es_PR es_PY es_SV es_US es_UY es_VE et_EE eu_ES fa_IR fi_FI fo_FO fr_BE fr_CA fr_CH fr_FR fr_LU ga_IE gd_GB gl_ES gv_GB he_IL hi_IN hr_HR hu_HU hy_AM id_ID is_IS it_CH it_IT iw_IL ja_JP ka_GE kl_GL ko_KR kw_GB lt_LT lv_LV mi_NZ mk_MK mr_IN ms_MY mt_MT nl_BE nl_NL nn_NO no_NO oc_FR pl_PL pt_BR pt_PT ro_RO ru_RU ru_UA se_NO sk_SK sl_SI sq_AL sr_YU sv_FI sv_SE ta_IN te_IN tg_TJ th_TH ti_ER ti_ET tl_PH tr_TR tt_RU uk_UA ur_PK uz_UZ vi_VN wa_BE yi_US zh_CN zh_HK zh_SG zh_TW