Matchbox-Keyboard README ======================== Introduction === Matchbox-keyboard is an on screen 'virtual' or 'software' keyboard. It will hopefully work well on various touchscreen devices from mobile phones to tablet PCs running X Windows. It aims to 'just work' supporting localised, easy to write XML layout configuration files. Its made available under the GPL. Rational === I wrote 'xkbd' a few years back which tried to do the same thing. It was the first xlib app I wrote and the first bit of C Id coded in quite a few years. It was a mess but basically worked, though with a few problems. matchbox-keyboard is my much promised rewrite. The code is cleaner and it hopefully addresses much of the previous short comings of xkbd. Building === Do the usual autotool jig of ./configure, make, make install. ( If building from SVN you'll need to run ./autogen.sh before this). matchbox-keyboard needs xlibs, xft, libfakekey and expat to build - The configure script will detect these. Also optionally there is experimental cairo support for rendering the keys and example embeddeding code. Running === Do; matchbox-keyboard [Options..] [optional variant name] and start typing. The config file will be selected based on locale setting and supplied variant name. The onlu current option is -xid, used for embedding ( see below ). The following Environmental Variables are also used, if set; * MB_KBD_CONFIG Set to full path of a alternate layout file to use overriding any other selection mechanisms. * MB_KBD_VARIANT Same as the first argument to binary. If both set argument overrides. * LANG, MB_KBD_LANG The value up to the first '.' ( i.e en_GB ) is used to build up the config file name based on locale. MB_KBD_LANG can be used to override the systems LANG var ( E.g, for the case of a Dutch person wanting a Dutch keyboard but an English locale - or the other way round ). Embedding === You can embed matchbox-keyboard into other applications with toolkits that support the XEMBED protocol ( GTK2 for example ). See examples/matchbox-keyboard-gtk-embed.c for how its done. Making your own keyboard layouts === Keyboard layout files are UTF8 XML files ( Make sure they are saved with this encoding! ). They are loaded from the directory $PREFIX/share/matchbox-keyboard and are named in the format keyboard[-locale][-variant].xml. This can be overridden by setting MB_KBD_CONFIG environment variable to a valid config file path or by creating $HOME/.matchbox/keyboard.xml. The basic layout of the file looks like; .... .... more keys ... ... A number of layouts can be defined ( though currently only 1 is supported ) each with any number of rows of keys, defining the keyboard from top to bottom. The most important tag to know about is the tag and its children. A key tag can optionally have the following attributes; * obey-caps=true|false ( defaults to false if not declared ) Specifies if the key obeys the Caps Lock key - Its shifted state is shown when the Caps key is held. * width=1000th's of a 'base' key width. Override the automatically calculated key width in 1000th's of a base key width ( The average width of a key with a single glyph ). * fill=true|false ( defaults to false ) If set, the keys width is set to fill all available free space. * extended=true|false ( defaults to false ) Keys set with this extended attribute set to true will *only* be shown if the display is landscape, rather than portrait. The rational for this is to better adapt to screen rotations. ( Note: the tag can also use this. ) The then has sub tags specifies the appearance and action for the five possible key states; ,,,,. There are two possible attributes for each of these state tags; * display=UTF8 String|image: Sets what is displayed on the key face for the particular case. If this is not set the key will be blank. Prefixing the string with 'image:' and then a filename to a valid PNG image will cause that image to be used on that key face. The filename can be abosolute or relative to $PREFIX/share/matchbox-keyboard or ~/.matchbox. * action=action string. The specifies the action of the key. For most (all?) single glyph keys the action is deduced automatically. For 'special' function keys, it can be set to any of the following. backspace, tab, linefeed, clear, return, pause, scrolllock, sysreq, escape, delete, home, left, up, right, down, prior, pageup, next, pagedown, end, begin, space, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12 By prefixing the value with 'xkeysym:', a a xkeysym can be defined to be 'pressed' as the action. If the key is a 'modifier' key, the action value is prefixed with 'modifier:' and then one of the following; Shift, Alt, Ctrl, mod1, mod2, mod3, Caps Rows can also contain a tags which denote blank space. They simply take a width attribute specifying the base in 1000th's of a base key width. See the various keyboard.xml files included in the distribution for example setups. Misc Notes === * matchbox-keyboard attempts to detect the window manager and set up its window 'hints' based on that. This is experimental, YMMV. matchbox-keyboard never wants to get keyboard focus itself, if the window manager gives it focus ( matchbox-keyboard requests the w-m doesn't ), it wont work. * It shouldn't't be too hard to make the keyboard use GTK or another toolkit ( possibly even Non X11 ) just by hacking matchbox-keyboard-ui.c . ( If you do either of these, please send patches ). * There is an applet and experiemental GTK-IM module included in the source for launching the keyboard. The IM module allows for the keyboard to automatically mapped / unmapped on 'demand'. For this to work; - The IM must be added to your gtk setup (See /etc/gtk-2.0/gtk.immodules, gtk-query-immodules-2.0 ) - Matchbox-keyboard must be run with the '--daemon' option. You can also use the --orientation switch so it is only mapped when the display is in a certain orientation. Todo === * Fix layout engine on small on displays. * Themeing. Needs thought... Matthew Allum 2007.