1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
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.
It's made available under the LGPL.
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;
<keyboard>
<options>
</options>
<layout>
<row>
<key ...>
<default .. >
<shifted .. >
<mod1 .. >
....
<key>
.... more keys ...
<space width="1000" />
</row>
<row>
...
</row>
</layout>
</keyboard>
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 <key> 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 <space> tag can also use this. )
The <key> then has sub tags specifies the appearance and action for
the five possible key states; <default>,<shifted>,<mod1>,<mod2>,<mod3>.
There are two possible attributes for each of these state tags;
* display=UTF8 String|image:<filename>
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 <space> 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.
<mallum@openedhand.com>
|
