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
- http://www.dasher.org.uk/ (I'm working on it! - Phil)
References
- This document describes the input method from a more user-centred viewpoint: HowToInputMethod770 (It would be sensible to merge these two documents at some point)
- Discussion on alternatives to the hildon framework, which may be useful for specific applications. http://maemo.org/pipermail/maemo-developers/2006-February/003081.html
- Discussion on how to set up alternative input methods: http://www.gossamer-threads.com/lists/maemo/developers/4003?#4003
- Might be useful to have a link to the GTK IM module docs here (although I can't actually find any right now!)
- Examples on how the hildon input method can be used in plain X11 applications can be found on the code snippet library in the Maemo Garage: https://garage.maemo.org/snippet/browse.php?by=lang&lang=2