Navigation

Views

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).

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:

hildon-input-method/hildon-im-plugin.h

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

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

/* Called when the plugin is disabled */staticvoid
disable(HildonIMPlugin *plugin){/* not implemented */}

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

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

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

/* Called when the plugin is requested to 'clear'/refresh its UI */staticvoid
clear(HildonIMPlugin *plugin){/* not implemented */}

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

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

/* Called when the plugin is requested to save its data */staticvoid
save_data(HildonIMPlugin *plugin){/* not implemented */}

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

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:

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

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:

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

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

HildonIMCommand hildon_im_ui_get_autocase_mode(HildonIMUI *main_ui);

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

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:

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:

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.