xkbd-0.8.15_bthid/README

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
   2 <article>
   3 <artheader>
   4 <title>Xkbd - onscreen soft keyboard for X11</title>
   5 <author><firstname>Matthew</firstname>
   6 <surname>Allum</surname></author>
   7 <copyright>
   8       <year>2002</year>
   9       <holder>Matthew Allum <email>mallum@handhelds.org</email></holder>
  10     </copyright>
  11 </artheader>
  12
  13 <section><title>Introduction</title>
  14 <para>
  15 Xkbd is a small highly configurable 'virtual' on-screen keyboard for X11. It
  16 is designed primarily for use on a PDA, but will hopefully be of use
  17 on other devices where a physical keyboard is not present.
  18 </para>
  19 <para>
  20 Xkbd uses no widget set and is based purely on xlib. It also
  21 optionally uses the xft library for anti aliased fonts.
  22 </para>
  23 </section>
  24 <section><title>Building and Installing xkbd</title>
  25 <para>
  26 Xkbd uses autoconf, so building it should be straightforward:
  27 <screen>
  28         <prompt>$</prompt><userinput>./configure</userinput>
  29         <prompt>$</prompt><userinput>make</userinput>
  30         # This next step might require root access
  31         <prompt>$</prompt><userinput>make install</userinput>
  32 </screen>
  33 See the INSTALL file for (standard) gory details regarding autoconf.
  34 </para>
  35 <para>
  36 Configure currently supports the following options;
  37 <ItemizedList>
  38 <ListItem>
  39   <userinput>--enable-debug</userinput>  <para>  configure for a debug build </param>
  40 </ListItem>
  41 <ListItem>
  42   <userinput>--enable-xft</userinput>    <para>configure to use XFT library for anti-aliased fonts.</para>
  43 </ListItem>
  44 </ItemizedList>
  45 </para>
  46 <para>
  47 Make also has an 'ipkg' target for building shiny ipkgs.
  48 </para>
  49 <para>
  50 A prebuilt ipkg is included in the familiar linux distributions
  51 unstable feed.
  52 </para>
  53 </section>
  54 <section><title>Using Xkbd</title>
  55 <para>
  56 On launch xkbd will attempt to open its configuration file from
  57 /etc/xkbdrc .
  58 </para>
  59 xkbd understands the following command switches;
  60 <ItemizedList>
  61   <ListItem><formalpara> -display &lt;display&gt;</formalpara>
  62       Selects the display for xkbd to appear on.
  63   </ListItem>
  64   <ListItem><formalpara> -geometry &lt;geometry&gt;</formalpara>
  65
  66       Provide xkbd with a position and dimension parameters.
  67       For example 320x100+50+50 will make a 320x100 pixel keyboard 50
  68       pixels from the side and top of your display.
  69
  70       NOTE: Its useful to use this option in overide redirect mode
  71       ( see below ) as xkbd by default will alway take up the smallest
  72       space possible for its current configuration, unless told
  73       differently by this option or the window manager.
  74   </ListItem>
  75   <ListItem><formalpara> -fa &lt;font name&gt;[-&lt;point size&gt; ]</formalpara>
  76
  77       Select the xft AA font for xkbd. Overrides whatever was defined
  78       in xkbdrc.
  79      </ListItem>
  80   <ListItem><formalpara> -fn &lt;font name&gt;</formalpara>
  81
  82       Select the X11 font for xkbd. Like -fa also overrides.
  83   </ListItem>
  84   <ListItem><formalpara> -k  &lt;config file&gt;</formalpara>
  85
  86       Select an alternate  keyboard definition file other than the
  87       default /etc/xkbdrc.
  88   </ListItem>
  89   <ListItem><formalpara> -v  </formalpara>
  90
  91       Display the version.
  92   </ListItem>
  93   <ListItem><formalpara> -h  </formalpara>
  94
  95       Display a breif help message.
  96   </ListItem>
  97 </para>
  98 </section>
  99 <section><title>Configuring Xkbd</title>
 100 <para>
 101 The actual 'keyboard' xkbd uses is defined in a configuration
 102 file. The defualt config file is /etc/xkbdrc, an alternate can be
 103 specified with the -k switch on startup.
 104 </para>
 105 <para>
 106 A configuration file for xkbd is split into 'tagged' sections;
 107 A global section mainly for the keyboards overall appearance ,  And
 108 row sections containing key definitions which defined the actual
 109 keys.
 110 See /etc/xkbdrc for an example.
 111 </para>
 112 <para>
 113 The <global> section should appear first in the file and can contain
 114 the following key/value pairs ( seperated by a space ) ;
 115 </para>
 116 <para>
 117 <table frame="all">
 118 <title>xkbd config file options</title>
 119 <tgroup cols=3 align="char" charoff="50" char=".">
 120 <thead>
 121 <row>
 122 <entry>Key</entry>
 123 <entry>Value</entry>
 124 <entry>Description</entry>
 125 </row>
 126 </thead>
 127 <tbody>
 128 <row>
 129 <entry>render</entry>
 130 <entry>xft|normal</entry>
 131 <entry>Set mode to 'xft' if you want to use anti aliased fonts.</entry>
 132 </row>
 133 <row>
 134 <entry>font </entry>
 135 <entry>font definition</entry>
 136 <entry>
 137       Defines the font used for the keyboard. For an xft font, specify
 138       the point size like <font name>-<size>. Default font is fixed / mono.
 139 </entry>
 140 </row>
 141 <row>
 142 <entry>col</entry>
 143 <entry>color def</entry>
 144 <entry>
 145       Defines the color of keyboard background. Defaults to white.
 146       This as with all color definitions can be either an RGB colon
 147       seperated list of an X color name. Defaults to white.
 148 </entry>
 149 </row>
 150 <row>
 151 <entry>down_col</entry>
 152 <entry>color</entry>
 153 <entry>
 154       Defines the color of a held down active key. Defaults to black.
 155 </entry>
 156 </row>
 157 <row>
 158 <entry>
 159     txt_col  </entry>
 160 <entry>color</entry>
 161 <entry>
 162       Defines the color of the keyboard key text. Defaults to black.
 163 </entry>
 164 </row>
 165 <row>
 166 <entry>
 167     border_col </entry>
 168 <entry>color</entry>
 169 <entry>
 170
 171       Defines the color of the keys border. Defaults to black.
 172 </entry>
 173 </row>
 174 <row>
 175 <entry>
 176     width|height</entry>
 177 <entry>pixel count</entry>
 178 <entry>
 179       Defines the keyboards width or height in pixels. Is overridden by
 180       the -geometry switch. Defaults to the smallest possible size for
 181       the defined keyboard.
 182 </entry>
 183 </row>
 184 <row>
 185 <entry>
 186     button_style </entry>
 187 <entry>rounded|plain|square</entry>
 188 <entry>
 189       Sets the basic button visual 'style. Can be rounded ( default ),
 190       square or plain.
 191 </entry>
 192 </para>
 193 <para>
 194
 195 After the &lt;global>&lt;/global&gt; definition, there then follows one of more
 196 &lt;row&gt; sections which contain the definitions for each on that row. The
 197 Rows go from top to and bottom and the keys left to right. Each row
 198 should just contain <key> definitions, there are no key / value definitions
 199 presently for rows.
 200 </para>
 201 <para>
 202 Each key has 3 'states', a default state, a shifted state and a modded
 203 state. Each state contains different key text and keysyms ( what is
 204 actually sent to the focused window when a key is pressed )
 205 </para>
 206 <para>
 207 Each &lt;key&gt; section can contain the following key / value pairs.
 208
 209    default <text>
 210
 211      Defines the text which is displayed on a key when shift or a
 212      modifier ( ie alt ) is not pressed.
 213
 214    default_ks <XKeysym>
 215
 216      Defines the actual keysym value that is sent by xkbd to the
 217      active window when the key is pressed. The keysym is the actual
 218      value thats sent to to active window. Keysyms are listed in
 219      /usr/X11R6/include/X11/keysymdef.h
 220      The is a special keysym '!Mod' which specifies the button is a
 221      'special' modifier button to access a 2nd alternate keysym for
 222      the key - see the mod section below.
 223
 224    shift   <text>
 225
 226      Defines the text which is diplayed on a key when a shift or CAPS
 227      key is held down. If not set the key will show the default text
 228      when shift is pressed.
 229
 230    shift_ks   <XKeysym>
 231
 232      Defines the keysym sent when shift or caps is held down.
 233
 234    mod     <text>
 235
 236      Defines a second alternative text string to be displayed. The mod option
 237      exists to make it easy to define smaller keyboards with more
 238      options per key.
 239
 240    mod_ks     <XKeysym>
 241
 242      The keysym to be sent when the 'mod' button is pressed.
 243
 244    img        <full path to image>
 245
 246      Defines an xpm to be displayed on a key. With this set, no text
 247      will be displayed and the img currently is the same across of
 248      keyboard states.
 249
 250    bg  <color>
 251
 252      Defines the background color of a key, overiding what was set in
 253      <global>.
 254
 255    fg  <color>
 256
 257      Defines the foreground color ( ie text ) of a key, overiding what
 258      was set in <global> .
 259
 260    slide_up_ks <XKeysym>
 261
 262      Defines the keysym to be sent when a key is pressed, but the
 263      pointer is slid up before being released ( a 'slide' ). Other
 264      slide directions can also be defined ( see below ). defaults
 265      to the shifted keysym
 266
 267    slide_down_ks <XKeysym>
 268
 269      defaults to sending a CTRL with the keysym
 270
 271    slide_left_ks <XKeysym>
 272
 273      defaults to None.
 274
 275    slide_right_ks <XKeysym>
 276
 277      defaults to None.
 278
 279    width  <number>
 280
 281      Forces the minimum width of a key to be this set value in pixels.
 282      Useful specifying a more exact layout.
 283
 284    height <number>
 285
 286      Forces the minimum height of a key to be this set value in
 287      pixels.
 288
 289    NOTE: If a key contains no keysym definitions its assumed to be an
 290          empty spacer.
 291 </para>
 292 </section>
 293 <section><title>FAQ</title>
 294 <para>
 295
 296 <section><title>Xkbd runs ok, but dont send key presses !</title>
 297  <para>
 298 There could be one of two things causing this;
 299 </para>
 300
 301 <userinput>xmodmap </userinput>
 302  </para>
 303 </section>
 304 <section><title>How do I get xkbd to launch from the dock </title>
 305  <para>
 306  monolaunch provides this. Run monolaunch like this;
 307 </para>
 308 <userinput>monolaunch /usr/share/xkbd/img/kbd.xpm xkbd</userinput>
 309 <para> Adding the '-k' switch to monolaunch will cause xkbd to completely disappear rather than minimise to a bar.
 310  </para>
 311 </section>
 312 </para>
 313 </section>
 314 <section><title>Embedding Xkbd in to other apps</title>
 315 <para>
 316
 317 </para>
 318 </section>
 319 <section><title>License</title>
 320 <para>
 321 Xkbd is free software released under the terms of the GNU General
 322 Public License, (GPL). You can redistribute it and/or modify
 323 it under the terms of the GNU General Public License as published by
 324 the Free Software Foundation; either version 2, or (at your option)
 325    any later version.
 326 </para>
 327 <para>
 328    Xkbd is distributed in the hope that it will be useful,
 329    but WITHOUT ANY WARRANTY; without even the implied warranty of
 330    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 331    GNU General Public License for more details.
 332 </para>
 333 </section>
 334 <section><title>Credits</title>
 335 <para>Xkbd is written by Matthew Allum. It uses the libvirtkeys lib by.
 336 </para>
 337 <para>
 338 Be sure to check out other exciting software by me including; xkbd - a
 339 xlib virtual on-screen keyboard, pikpak - a python gtk front end to
 340 ipkg, gtksolo - a gtk module which turns held down left clicks into
 341 right clicks on gtk apps and jabberpy - a Python library for the Jabber
 342 instant messaging protocol.
 343 </para>
 344 Xkbd is copyright Matthew Allum 2002.
 345 </para>
 346 </section>
 347 </article>