[maemo-developers] [maemo-developers] Non-gtk application integration

[From: Tim Teulings]

Hello!

>> > * How can I trigger the keyboard when doing text entry ?

I while ago i did some investigations regarding the communication
protocol between maemo GTK applications and the keyboard by monitoring
relevant X11 Client Messages to add support for keyboard handling funder
maemo to my GUI library. I managed to get the keyboard openend and
closed and get typed characters inserted into my application.

I send these information a while ago to Antonio Gomes, the porter of the
minimo browser. Antonio in turn managed to get keboard input working for
minimo.

This was (part of) my mail:

-----%<-----------------------------

OK, this source contains the necessary code fragment.

http://svn.sourceforge.net/viewcvs.cgi/illumination/trunk/Illumination/src/Lum/OS/X11/Window.cpp?view=markup&rev=670

For the referenced files and classes you should also browse:

http://svn.sourceforge.net/viewcvs.cgi/illumination/trunk/Illumination/src/Lum/OS/X11/
http://svn.sourceforge.net/viewcvs.cgi/illumination/trunk/Illumination/include/Lum/OS/X11/

And (top level):
http://svn.sourceforge.net/viewcvs.cgi/illumination/trunk/Illumination/

The relevant code for opening the keyboard is in
void Window::AcquireKeyboardInput()

It reads a property from the desktop root window to find out the id of
the input method window and then send some client messages to it. The
outcomented messages were used by the example-toolbar program when
opening the keyboard but I found out that one could miss some (their
will have their purpose though. I assume further customizing).

For closing the keyboard look at
void Window::ReleaseKeyboardInput()

If you have called AcquireKeyboardInput you will get in turn a number of
of ClientMessages you have to evaluate or even answer. The relevant code
starts with "Atom
hildonWindow=XInternAtom(display->display,"_HILDON_IM_WINDOW",true);"
which is called within
bool Window::HandleEvent(::Lum::OS::EventPtr event)

At that point you are right in the X11 event loop (for the window you
have given the id of in the Acquire method).

All code is not really cleaned up. I will put some common code into
helper methods for cleanup.

Here is a little text with information about the messages:

Messages:
_HILDON_IM_COM:
l[1]:
 0: Return pressed
 1: Tab pressed
 2: Backspace pressed
 4: ???
 7: Session start?
12: Menu opened, reset?

_HILDON_IM_ACTIVATE:
l[0]: Client window to send input to
l[1]: Window with current focus
l[2]:
 1: ???
 2: Close keyboard
 3: ???
 4: Some kind of acknowlegde or "status change after typing"?
 5: Close keyboard
 6: <not used>
 7: ??? (but uses l[3] as 'mode', can see no difference, but '0' is not
allowed)
 6: ??? (Results in getting COM-4 from keyboard!)
 8: Session initiator? (uses l[3] as mode? '0' not allowed!)
 9: Open keyboard (Perhaps "8" = "session begin" and "9" = "open"?
10: ???
11: ???
12: <not used>

l[3] Mode flag (Bitset?):
 1: only characters
 2: Tab, return, backspace only
 3: Letters and numbers (but no symbols)
 4: only symbol characters
 5: Everything but numbers
 6: Only symbols and tab, return and backspace
 7: everything
 8: hexadecimal (A-F, a-f, 0-9)
 9: Letters and numbers (but no symbols) (where is the difference to 3?)
10: A-F
11: letters and numbers (but no symbols) (where is the difference to 3
and 9?)
12: Hexadecimal and symbols
13: Everything
14: Hexadecimal and symbols
15: Everything
16: mathematical stuff (numbers, brackets, operators and letter 'w' and 'p'?
17: Letters, mathematical but no symbols
18: mathematical stuff but no numbers
19: Letters, mathematical, numbers  but no symbols
..
31:

The are many open points. For example there are messages to then the
text context to the input method (for proper out completion).

If you have questions or have extraced more information, please just
mail me!

-----%<-----------------------------

Not ethat Illumination, the library that this source code is part of,
also contains a lot of code showing how to use Gtk/maemo theming code
for native (non-GTK) applications. While the code is neither perfect nor
complete is shows how foreign applications can mimic maemo look & feel.

Btw., It is not nice that maemo theming divergates from standard GTK
theming. I hope that in future the differences between maemo and GTK
theming will be removed or at least reduced (by either removing maemo
GTK patches or getting them incorporated into GTK upstream).

If there are any questions, ask. If anybody wants to add this
information to some web page, feel free to do so.

-- 
Gruß...
       Tim.