InputMethod

Notes on The Hildon (Nokia 770) Input Method Architecture

I've just got hold of an N770 and was keen to have a go at implementing an alternative input method, so I spend a while figuring out how the system works. Here's what I found - this may or may not be accurate and is definitely not complete :-)

(Can someone link to some code that implements some of this, for those of us unfamiliar with xlib programming? Thanks.)

Window Manager Interaction

You basically need to set a couple of X11 Window properties to get matchbox to do the right thing:

1 . Set _NET_WM_WINDOW_TYPE to be _NET_WM_WINDOW_TYPE_INPUT for your application window. This will make the window manager position it in the right place at the bottom of the screen. 2 . Set your window to be transient for the window into which text is being entered (see below for how to find out which window this is). This will have the effect of making the target window resize so it's not covered by the input method window.

Note that you probably don't want to derive from HildonApp etc for an input method - just create a standard GTK window.

Input Method Interaction

As far as I can tell the input method is partially implemented as a combination of custom patches to GTK and a plugin using the GTK IM framework. You probably don't want to worry too much about this side of things. I didn't get far without the source code when I tried :-). The other half is a standalone binary, hildon-input-method. My strategy was to replace the latter. Communication between the two halves is via X11 client message events.

The GTK side of things figures out which window to communicate with via the _HILDON_IM_WINDOW property of the root window. Set this to be the X11 window ID of your app window. This will also prevent events from being sent to the existing input method, so it should stay out of your way.

Having done this you'll receive XClientMessageEvents (see the X11 man pages). The ones you receive initially have message_type set to _HILDON_IM_ACTIVATE. These tell you when to show and hide your window. Note that the format member seems to be always set to 8, even though most of the data seems to be 32 bit values. As far as I can tell, the values of lare:

Member Description
l0/td> Global IM window ID
l1 currently active window ID
l2 No idea (always seems to be 1)
l3 Message type
l4 No idea (always seems to be 0)

The global IM window ID is needed to send messages when you want to enter text. The currently active window is the one you should make you window transient for.

The message type seems to be 0x05, 0x0d or 0x12 for 'show window' and 0x0b for 'hide window'. I haven't figured out the difference between the show window types yet.

Update: I've just noticed that some apps (eg the Notes utility) send 0x0c instead of 0x0d and 0x11 instead of 0x12. Not sure what the difference is, it could be something to do with having a toolbar?

Upon receiving the 0x11/0x12 variant I send a _HILDON_IM_COM message with l0= Global IM window ID, l1 = 0x7 and l2, l3 and l4 set to 0 to the global window, as this is what the hildon-input-method process does. I guess this is something along the lines of 'yes I'm here and I'll be sending stuff soon', but I haven't looked in too much detail.

Finally, when you want to send text, send _HILDON_IM_INSERT_UTF8 to the global IM window. Set l1 to be the character to send (in UTF-8 I guess) and everything else to zero. You'll get a _HILDON_IM_ACTIVATE in response and your character should appear.

There are a few other XAtoms which I haven't investigated yet:

_HILDON_IM_CLIPBOARD_COPY

_HILDON_IM_CLIPBOARD_CUT
_HILDON_IM_CLIPBOARD_PASTE
_HILDON_IM_CLIPBOARD_SELECTION_QUERY _HILDON_IM_CLIPBOARD_SELECTION_REPLY

I guess the names are pretty clear - if you fancy investigating them xmond is pretty useful.

Input methods nice to have on the N770

References