%% The GTKeyboard Manual
%% Written by David Allen
%% Regularly Updated to reflect newer versions of GTKeyboard
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[12ppt]{report}
\usepackage{psfig}
\title{GTKeyboard Manual}
\author{M. David Allen s2mdalle@titan.vcu.edu}
 
\begin{document}
\maketitle
\tableofcontents
\setcounter{tocdepth}{1}
\fussy

\chapter{Introduction}

  \section{Startup Notes}
Upon starting GTKeyboard, you'll be presented with a full keyboard
including all punctuation and symbols available to you on the
keyboard.

The window that is displayed has two different text boxes.  The first,
which is not editable by the user, contains GTKeyboard status messages
to the user, for example, whether the CAPS LOCK key is ON or OFF,
whether the SHIFT key is ON or OFF, and other messages pertaining to
options that you can change within the program, such as whether or not
the program will ask you if you want to save on exit, and so on.

The second text box below the first, is the editable input/output
box.  In this box, you can type as you would normally in any other
program, or you can hit any of the keys above on the keyboard to
insert text into this location.  If you write text past the end of the
line, you will notice that the text automatically wraps around with a
small curling arrow sign at the end of the previous line showing that
you have gone past the end of that line.  You may also toggle word
wrap under the {\it Misc} window.

All punctuation necessary for writing should be available on the
keyboard for editing.

When you are ready to save your document, you have a choice of two
things.  You can either save the file under the default filename,
which is usually /tmp/GTKeyboard, or you can specify the filename you
wish to save it under and then save it.  To specify the filename you
wish to save it as, click the {\it File} menu on the top bar, and
select {\it New File}.  A dialog box will pop up, prompting you for
the new filename.

The status logging toggle option in the {\it Misc} menu is what
controls whether or not the status window's text is saved on exit of the
program.  When you use the menu, it will let you know in the status
menu itself what the current setting is.

A few quick notes:  The ``Clear All'' button, which is located
at the very bottom of the button row at the bottom of the application,
is {\bf not} a cut button.  It will clear all of the text
in the buffer, and it will not copy it to the X cut buffer, i.e. you
will not be able to paste that text back into the document again.  For
that reason, I had to put in an ``are you sure'' popup dialog.

  \section{Problems with this Manual?}

This manual was originally a plaintext to HTML conversion of the even
older GTKeyboard manual that came with the program.  It has since been
converted to \LaTeX{} format and should be available in a variety of
other formats.  I've tried to mention just about everything, but I'm
sure there are things that I missed. 

If you would like to report some feature documentation missing that
you'd like to see, suggest another subtopic, correct my spelling or
grammar, please email me at {\it s2mdalle@titan.vcu.edu}
and I'll clear it up as quickly as possible.  If you would like to
write a section, go for it, and I'll incorporate it as long as it's
relevant to GTKeyboard.

  \section{Who am I?}

I am David Allen, I'm a college student attending Virginia
Commonwealth University in Richmond, Virginia (as of this writing).  I
major in Computer Science and Psychology.  I originally wrote the
program to learn the GTK+ toolkit and to scratch an itch of mine at
the time, but as time went on, people found some new uses for the
software I hadn't imagined, and were requesting new features and
bugfixes, which I was more than happy to provide. 

  \section{Where to get GTKeyboard}

I try to make it as easy as possible to get a copy of GTKeyboard.
Here is a list of places that you're likely to find GTKeyboard hanging
out if you want the latest copy.  I distribute RPMs and DEBs
infrequently where I can.  If you are willing to package GTKeyboard,
please get in touch with me.

\begin{itemize}
\item {\it http://opop.nols.com/gtkeyboard.html}
\item {\it http://www.gnu.org/software/gtkeyboard/gtkeyboard.html}
\item {\it ftp://alpha.gnu.org/pub/gnu/gtkeyboard/}
\item {\it ftp://contrib.redhat.com/}  (src and i386 RPMs)  {\bf Note:
binary and source RPM packages are not currently being maintained -
the versions found here are likely to be very out of date.}
\item By email. If you can't find a copy anywhere, or if tornadoes and
nuclear war have eliminated my site and all of GNU, email me at
{\it s2mdalle@titan.vcu.edu} and I can email you a copy in your
preferred available format.  This includes versions that are
statically linked for people who prefer those.  Because of their size,
I don't plan to include many on the GTKeyboard page.
\end{itemize}

\section{Overview of GTKeyboard Features}

GTKeyboard has many features that hopefully help the user out in
getting many and varied tasks done.  Here is a brief overview of some
of the features available.

\begin{itemize}
    \item Editing Shortcuts
    \begin{itemize}
        \item HTML Editing Shortcuts
        \item Language Shortcuts
	\item User defineable shortcuts
	\item Shortcuts to speed document editing
        \item Word completion (ala GNU Readline)
            \begin{itemize}
            \item Word completion against user-specified caches
            \item Conversion of text files to cache-files
            \end{itemize}
    \end{itemize}

    \item External Program Launching
    \begin{itemize}
        \item Lynx
        \item Telnet
	\item FTP
	\item Can be hacked to include support for other external
	programs.
	\item Uses RXVT by default, but can use Xterm as well.
    \end{itemize}

    \item Output Redirection
    \begin{itemize}
        \item System console (/dev/console)
        \item Printer (/dev/printer)
	\item Can be hacked to include support for other output devices.
    \end{itemize}

    \item The Ability to redirect keypresses to other X applications
    \begin{itemize}
        \item Implicit redirection:  Whichever window last had focus
        \item Explicit redirection:  Explicitly choose a window for
            redirection
    \end{itemize}

    \item Screen Control
    \begin{itemize}
        \item Hide/Show just about any major widget
        \item Specify screen layout in the resource file including
    what should and shouldn't be in toolbars.
    \end{itemize}
    \item Regular text editing features common to GTK+ programs
    \item Licensed under the GNU
    General Public License as Free Software
\end{itemize}

There is one other point that I'd like to make about the feature
set of GTKeyboard.  Although it's constantly growing, sometimes I get
an email that asks me why I put in a specific feature.  Currently,
there are people who are working towards using GTKeyboard in an ICU/OR
setting whos user interface requirements are much different from that
of the standard user.  I have attempted to make each feature as small
as possible, to minimize growth of the binary and memory usage.  If
you find that a certain feature is strange, or doesn't sound like
something you'd ever use, that's fine, but most likely they will stay
in GTKeyboard to add flexibility to the application in addition to
letting other people with different agendas use the application for
their purposes.

  \section{Setting up your Resource File}

GTKeyboard reads a configuration file at startup to determine which
options you want functioning in the program, and which you don't want
functioning.  The file is always located in your home directory with
the name {\it .gtkeyboardrc}.  {\it ~/.gtkeyboardrc} contains a
few lines that toggle features on and off at the start of GTKeyboard.
You may specify a default file to edit at startup, whether you want to
use word wrap or not, whether to ask you to save the document on exit,
and so on.  If there are other aspects of GTKeyboard you would like to
be able to customize, mail me, and I'll see if I can work it in.

If a configuration file is not present, GTKeyboard will copy a default
configuration file and choose values that I think are reasonable.  But
not everybody likes things the same way, what I think is reasonable
you might consider absurd, so please edit the file to your liking.
Editing this file is optional though, since GTKeyboard can run with
the default provided resource file.

Entries in the file look like this:\\
{\it set OPTION\_NAME VALUE} \\
Or, alternatively, like this:\\
{\it toolbar ELEMENT [ON|OFF]}\\

First, the option names.  ``Toolbar''
statements are explained in a later section.

    \subsection{Regular Options}

OPTION\_NAMEs include many possibilities listed in a later section.
VALUE is any integer value that you want to set the feature 
to.   If you enter 0, the feature is turned OFF, any other value will
result in the feature being enabled.  That is,  \\
{\it set ASK\_SAVE\_ON\_EXIT 1}
and \\
{\it set ASK\_SAVE\_ON\_EXIT 323}
and even \\
{\it set ASK\_SAVE\_ON\_EXIT ON}\\
Are functionally equivalent.  Both will cause GTKeyboard to prompt you
as to whether or not you want to save the file before you quit.  But
if you enter\\
{\it set ASK\_SAVE\_ON\_EXIT 0}
then you will not be prompted.

Some option names take strings as arguments, examples being
{\bf WORKING\_FILE}  and {\bf KEYBOARD\_FILE} .  In
these cases, syntax is simply:\\
{\it set variable\_name string\_value}\\
An example would be:\\
{\it set KEYBOARD\_FILE /home/user/gtkeyboard-layouts/DE.key}\\

    \subsection{Option Names}

\begin{itemize}
\item {\bf ASK\_SAVE\_ON\_EXIT} :
If on, you will be asked if you want 
to save the file before you exit.  If off, it won't ask you,
{\bf {\it even if the file needs saving} }  {\it ON}  by
default.
\item {\bf BORDERLESS} :  This makes
GTKeyboard pop up as a ``popup'' window, which with many window managers
makes it borderless. You might want to be careful with this one
though, since some window managers make popup windows always stay on
top.  In this event, you may not see a dialog window that GTKeyboard
pops up because it will be behind the main window.  This is good for
decreasing the amount of screen realestate the program takes though.
This option is {\it OFF}  by default.
\item {\bf CACHE\_FILE} : Specify a filename to be used as the default
word cache file.  This will only be used through the word completion
facility of GTKeyboard.  Note that this setting overrides the default
behaviour of GTKeyboard which is to use .gtkeyboard-wordcache in the
user's home directory.
\item {\bf EXTRA\_FILES} :  This is
the directory GTKeyboard will look in for extra configuration files
including the ChangeLog, README files, (which are displayed in windows
through the help menu) as well as the default location to look for
.KEY files.  This variable is not set by default.
\item {\bf EYECANDY} :  This is
actually a bit silly.  If on, two pixmapped buttons will appear to the
left and right of the up cursor key.  The pixmaps are generated at
random, and look like multicolored snow.  This was mostly added
``because I could''.  If you think it's annoying, keep this option off,
and instead you will have two buttons with the labels ``About'' and
``License''.  This is {\bf off}  by default, since some people
find it annoying, but it's a way to conserve more screen space. 
\item {\bf HANDLEBARS} :  If on, it
adds a handlebar to the left hand side (by default) of each of the
major widgets so that users can pull them off into separate windows.
This used to be the default, but was placed into an option because it
confused some users. 
\item {\bf IGNORE\_LAYOUT\_FILE} :  If this is
set on, then GTKeyboard will ignore your ~/.gtkeyboard-layout file.
This file is produced by using the ``Save Layout Settings''
functionality located under the {\it Options} $\Longrightarrow$ {\it
Looks} menu. Normally, whenever a layout file exists, it will be read,
and the layout settings defined in that file will override your layout
statements in your resource file.  Setting this option tells
GTKeyboard to disregard the settings found in that file.  This is set
to {\it OFF}  by default, meaning that your {\it ~/.gtkeyboard-layout} file
will be used.  
\item {\bf INFO\_POPUPS} :  If you set this, GTKeyboard will pop up
small windows letting you know what's going on, rather than just
outputting the text to the status window. The author is not that wild
about this, but some people prefer it, so it was added added in
0.97.2. {\it OFF}  by default.  {\it Note: this option is deprecated
as of GTKeyboard version 1.1.1 and above - it has no effect, and will
be removed soon}  
\item {\bf KEYBOARD\_FILE} :  This
will load the keyboard file you specify and use it as the keyboard on
startup.  The default is to use the QWERTY.key file which comes with
GTKeyboard.  Specify the keyboard file as a string.  The default is
always the ``QWERTY.key'' that comes with the GTKeyboard
distribution. 
\item {\bf KEYBOARD\_FONT} :
Requires a string argument of the font that should be used for
displaying keyboard buttons.  This font should be of the same form as
the {\it TEXT\_FONT}  variable.  This variable is not set by default.
\item {\bf PULLOFFS} :  This value can
be one of several, ``top'', ``bottom'', ``left'', and ``right''.  The default
is ``left'' which looks the best in my opinion, but options are there
for people who want them.  This controls what side the pull off bars
for various screen items are positioned on.  Note that this variable
will have no effect if {\it HANDLEBARS} 
is {\it OFF} .  The default for this variable is {\it LEFT} .
\item {\bf RANDOM\_STRLEN} : If you
use the random string function, (not many people do, it's just for
fun) then you will get the absolute value of the characters you
specify.  That is, if you say 20, it will be 20. If you say -10, it
will be 10.  This variable has a value of {\it 20}  by default.
\item {\bf REDIRECT\_POLICY} :
This sets the redirect policy.  The default is {\it implicit}  which
means that whichever window last had focus will be the redirect
window.  The two possible options are {\it implicit}  and
{\it explicit} .  This is an important subtopic to itself; see the
section on redirection for more information. 
\item {\bf SEND\_DATA\_TO\_BOTH\_WINDOWS} :
If this is specified as on or a nonzero number, then whenever a key is
pressed, the key that you pressed will be sent to the redirect window
{\bf and}  the regular text buffer.  This way you can log
your keystrokes in other windows.  The default is {\it OFF} .
\item {\bf SHOW\_TOOLTIPS} :  If set to {\it ON} , then tooltips will
be available for each key on the keyboard showing its keycode, and the
different symbols the key can produce.  If it is {\it OFF} , then
tooltips (only on the keyboard) will not be shown. The default is {\it
ON}. 
\item {\bf STATUS\_LOGGING} :  If on, the status buffer will be saved
after each session in the current working directory. {\it ON}  by default.
\item {\bf TEXT\_FONT} :  Requires a
string argument of the font that should be used in the main text area
for display.  This should be of the X font form similar to
``-biznet-fotinos-bold-r-normal-*-*-180-*-*-p-*-iso8859-2''
(that particular font may not be on your system).  The default is the
standard GTK+ text font.  Note that if the font you specify can't be
found or can't be loaded, the default GTK+ font will be used despite
your setting, and gtkeyboard will issue and error message.
\item {\bf WORD\_WRAP} :  Turns on word
wrap within the text widget. {\it OFF}  by default.
\item {\bf WORKING\_FILE} :
Whatever string you give it will 
be the file GTKeyboard opens on startup as its default file.  If you
specify a file on the command line in addition to having a
WORKING\_FILE, your working filename is
ignored. {\it \$HOME/.gtkeyboardrc} by default.
\item {\bf XPOS}:  Sets the X position of
the keyboard as it 
should be when the window pops up.  The upper left hand corner of the
application will move to (XPOS, YPOS)
\item {\bf YPOS}:  Sets the Y position of
the keyboard as it 
should be when the window pops up.  Note that both a valid XPOS and
YPOS must be set for this to have any effect.  The upper left hand
corner of the window will appear at (XPOS, YPOS) on your screen at
startup.
\end{itemize}

    \subsection{Layout Statements}

These are simple statements of the form:\\
{\it [show|hide] element} \\
The element list is as follows:\\
\begin{itemize}
    \item {\bf KEYBOARD}:  The actual keyboard display
    \item {\bf BUTTONBAR}:  The bottom row buttons
    \item {\bf MENUBAR}:  The pulldown menus
    \item {\bf TEXT}:  The main text editing area
    \item {\bf STATUS}:  The status buffer
    \item {\bf TOOLBAR}:  The icon toolbar
\end{itemize}

Each statement contains the word ``show'' or ``hide''
followed by an element name.  The corresponding element is either
shown or hidden when the application starts.  Using the Looks menu you
can always display or hide things after the application starts
though.  The default for all elements is show.

    \subsection{Keyboard Statements}

Keyboard statments are very similar to layout statements.  The only
main difference is that a keyboard statement only controls a
subsection of the keyboard.  It allows the user to show/hide arbitrary
parts of the keyboard.

Syntax for keyboard statements is:\\
{\it keyboard element\_name [on|off]}\\
Where {\it element\_name} is one of the following:

\begin{itemize}
    \item {\bf CURSOR\_KEYS}:  The cursor keys, containing the
    up, down, left, and right cursor keys, and also
    Insert/Home/Delete/End/Page Up/Page Down.
    \item {\bf F\_KEYS}:  The function keys, including
    escape.  Keys ESC, F1-F12.
    \item {\bf MAIN\_KEYBOARD}:  The main keyboard area.  This
    includes the number keys, the main alphabet, enter, caps lock,
    shift,
    etc.  {\it Note} :  In versions before 1.0, this option was
    known by
    {\it KEYBOARD} 
    \item {\bf NUMBER\_PAD}:  The number pad located on the
    far right hand side of the keyboard.  This includes the numbers
    0-9, enter, num lock, -, /, *, and +.
\end{itemize}

For example, a layout file that wanted to only show the main
keyboard and nothing else would have statements looking like this
(note that case doesn't matter in resource file statements):

{\it keyboard keyboard on           \# Turns the main keyboard ON \\
     keyboard cursor\_keys off       \# Turns the cursor keys off \\
     keyboard number\_pad off        \# Do not show the number pad \\
     keyboard f\_keys off            \# Do not show the f-keys.}\\
      
The default value for all of the above elements is {\it ON}

    \subsection{Toolbar Statements}

Mentioned above, a statement of the form \\
{\it toolbar ELEMENT VALUE}\\
Allows the user to customize the toolbar via the resource file.
ELEMENT stands for the name of a toolbar element, and VALUE for what
that element should be.  An example of this would be something like
the following:\\
{\it toolbar window\_grab OFF}\\
Which would cause the window grabbing button on the toolbar not to be
shown when GTKeyboard starts.   ELEMENTs are case INSENSITIVE, which
is to say, there is no difference between specifying the ELEMENT as
``copy'' or ``COPY''.

Each button on the toolbar has a name associated with it, which
corresponds to an ELEMENT.  You can control which ELEMENTs are shown
and which are hidden by using the ON/OFF specifiers in the resource
file.  Note that ALL toolbar buttons are always ON by default.  If you
don't want to see them, you must set them OFF in your resource file.

The following are the names of the different ELEMENT statements
possible when using the ``toolbar'' line in an rcfile.  More
can be added upon request as well as more possible toolbar buttons in
general.  Note that if you disable all of the toolbar buttons, the
{\it Options} $\Longrightarrow$ {\it Looks} -> {\it Toolbar} menu to
achieve the same effect. 

\begin{itemize}
\item {\bf Open}:  The open-file toolbar button
\item {\bf New}:  The new-file toolbar button
\item {\bf Save}:  The save-file toolbar button
\item {\bf Cut}:  The cut-text toolbar button
\item {\bf Copy}:  The copy-text toolbar button
\item {\bf Paste}:  The paste-text toolbar button
\item {\bf Window\_grab}:  The grab-window button
\item {\bf Window\_ignore}:  The ignore-window button.
\item {\bf Color}:  Button to change gtkeyboard's colors
\item {\bf Font}:  Button to change text fonts
\item {\bf Kbd\_font}:  Button to change keyboard fonts.
{\it Note:  This was known as {\bf keyboard\_font} in
previous versions}
\item {\bf Reset\_style}: The button to reset application
defaults.
\item {\bf Positioning}:  If ON, a series of buttons will be
on the toolbar to control repositioning of the application on the
screen.
\item {\bf Shortcuts}:  If this is ON, (which it is by
default) a row of 6 buttons and a define user shortcuts button will be
present on the toolbar.
\item {\bf Status\_report}:  Shows/hides a button that when
clicked, outputs a status report into the status window.
\item {\bf Raise}:  Shows an up arrow on the toolbar that you
can use to stack the GTKeyboard window above all others
\item {\bf Lower}:  Shows a down arrow on the toolbar that
when clicked sends GTKeyboard to the background.
\end{itemize}

\chapter{Text Editing}

The onscreen keyboard in GTKeyboard functions exactly like a normal
keyboard on your desktop.  Each of the buttons has its normal
function, with the exception of the buttons on the top row, (F1-F12,
ESC, Scroll Lock, etc) which do not have any function yet.  The shift
and caps lock buttons work just like they would on a normal keyboard,
as well as all the other symbols like !@\#\$ etc.

As soon as the application starts, you can begin typing, and the
output of your typing will appear in the output buffer, the text space
near the bottom of the screen where the guide buttons are at the
bottom.  Each key that you press will put its corresponding symbol
into the buffer at the bottom, possibly modified if the shift key is
on.  In addition, the NUM LOCK key and the CAPS LOCK key are toggle
keys - the status buffer will inform you when they are turned off or
on, and they will remain pressed down when on.  To release them, just
press them again.

On the bottom row of the main window, there are convenience shortcut
buttons to perform common tasks such as to select all of the text in
the widget, to open a file, to clear all the text out, to quit the
application, and so on.

For convenience, there is also a popup menu that you can use with
GTKeyboard.  Just right-click in the text area at the bottom where you
normally type into, and a menu will appear to let you perform common
GTKeyboard tasks with, such as hiding/showing different screen
elements, customizing fonts/colors, and so on.

Don't bother wasting button presses on repetitive things like quoting
certain sections of text!  The shortcuts menu in the top menubar will
help you out with things like that.  If you go into the quoting
submenu, and click on ``Quote'', it will produce ``'' and put the
cursor between the two quotes so that you can continue typing your quoted
text.  When you're done with the quoted text, use the cursor keys next
to the spacebar to go to the left or right of where you currently are
to continue typing.

In the Misc menu, there are also functions to move the cursor
automatically to the beginning or end of the file, as well as the
beginning or end of a particular line.  It will place the cursor
appropriately so that you don't have to worry about hitting the cursor
keys the right number of times in order to go to the beginning/end of
the line/document.  They function just like the HOME and END keys on a
normal keyboard.

Also, currently with the keypad, you have the buttons Home, End, and
Delete.  They function just like the keys on the keyboard.  The HOME
key takes you to the beginning of the current line, delimited by a
linebreak, the END key takes you to the very end of the line, and the
delete key deletes one key forward from your current position, just
like on a normal keyboard.

  \section{Three Mode Buttons}

GTKeyboard can define up to three different symbols for each key on
the keyboard.  Those three symbols are referred to as the normal
symbol, the ``shift'' symbol, and the ``mode-switch''
or ``alt-gr'' symbols.

Generally, the way you generate those symbols is as follows.  If
you just want the regular symbol, (the same thing as the symbol that
shows on the face of the key) you just mouse-click on top of that
button.  If you want the shift symbol, you click on the Shift keyboard
key, or possibly the Caps Lock key, and then click your symbol.  For
alt-gr symbols, an Alt-Gr or Mode Switch key must be present on the
keyboard.

GTKeyboard offers a shortcut to skip through the symbols you need
to select with each button.  The first mouse button generates the
``normal'' symbol, the second mouse button generates the
``shift'' or upper case symbol, and the third button generates
the ``alt-gr'' symbol if one exists.  If it doesn't exist,
nothing happens.  Note that button 3 on most people's mouse will
actually be the middle button, not the right-most button.

  \section{Editing Text in a non-GTKeyboard Window}

Editing text and inserting keys into a foreign window uses the same
method as editing text in the GTKeyboard window.  The only difference
is that you must make use of the window ``redirection'' feature in
order to tell GTKeyboard which foreign window you want to use.  To
that end, you must choose a redirection mode, either {\it explicit} or
{\it implicit}.

  \section{Explicit Versus Implicit Methods of Window Redirection}

There are two ways to choose a window to redirect data from the
keyboard to.  They are the implicit method, and the explicit
method. The implicit method, which is the default, is quite easy.
Whichever window had the focus last is the window that is designated
to receive the key presses.  The explicit mode is where the user
chooses a window explicitly for redirection. 

In order to use the implicit mode, all you have to do is make sure
that the window you want to redirect to is the window that last had
the keyboard focus in your window manager.  That's it.  Generally, if
you need to assign this, you can just click on the window you want to
focus on with your mouse, and then click on GTKeyboard again.  You
should see a message in your status window saying ``Found new
focus window:  window name''  All keyboard usage after that will go into
the foreign window.

In order to choose a new window to redirect output to (using explicit
mode), click on the Output menu, then click on Choose a Window.  Your
cursor will change, at which time you go out and choose a window by
clicking on an active window.  When that is done, you just type with
the on-screen keyboard as normal, or do whatever you would normally do,
except that output goes into the foreign window rather than where it
usually goes.  See the BUGS file that comes withe the source
distribution about some things that don't seem to
want to work properly like xterm which are traditionally a pain to
send X events to.  For most things, this will work just that easily.
(e.g. an rxvt window/other terminal emulator)

Sometimes, you will want to redirect text to a certain box within a
certain window.  (Like for example, the URL box in Netscape
Navigator).  This is no problem, GTKeyboard will let you do that too,
but you must make sure that the box you want to type into has the
focus.  Basically, after you select the window, click on the box that
you want one more time so a thin black border comes up around it as is
traditional for most windows that have the focus, and then you can
begin typing into that window.

Some notes about redirection to other windows:

\begin{itemize}
    \item Although implicit focus is the default, some users may want to
        toggle to explicit mode, particularly if you are using GTKeyboard in
        its editing facilities.  If GTKeyboard has a valid window to
        redirect to, it will use that window, which may cause problems
        if you expect your text to show up in the editing buffer!
    \item The most common problem is forgetting to give focus to the
    item inside an application you're typing into.  Don't forget to do
        that.  Note that this may take a special ``focus setting'' in
        your window manager.  Sloppy focus works the best in my
        experience.  Focus follows mouse often doesn't work, depending
        on whether or not the window manager takes keyboard focus with
        mouse focus when moving between windows.
    \item It should work fine for most ``well-behaved'' X applications,
    provided that the widget you want to enter text into has the
    focus.
    \item Xterm will work, but in order to make it work, you must
    control+click on your Xterm window and hit ``Allow
    SendEvents'' before the keypresses will show up in an Xterm
    \item If you find an application that it doesn't work with, let me
    know.
    \item Some programs simply will not allow events.  In order for
        this redirection to work, it has to be allowed by the client
        program.  Some programs such as {\it xterm} mentioned above
        will only let you redirect to them after you have configured
        them correctly.  Others won't allow it at all.  Carefully read
        the documentation of the program in question if it doesn't
        work, and if it doesn't allow such configuration, either drop
        me or the developer of the application an email and ask.
\end{itemize}

You will also find a ``Choose Window'' and ``Ignore Window'' option
under the {\it Shortcuts} menu.  They're just there for convenience,
there is no difference between them, only that some people look in
different places for the same things.

The ignore window button does exactly what it says it does:  It
ignores the current active window.  So if you're workin on something
within an rxvt window, and you want to go back to editing within the
GTKeyboard text buffer, click on the Ignore Window button either at
the bottom of the screen or in the Shortcuts or Output menus, and
GTKeyboard will take focus away from that window and begin sending all
keystrokes back into the GTKeyboard editing buffer.  This allows you
the flexibility to flip back and forth between small editing tasks
editing in other windows or performing other tasks with the on screen
keyboard.

\chapter{User Defined Shortcuts}

By request of several users, GTKeyboard now has the ability to let
users define their own shortcuts and use them for quick advanced
editing.  On the toolbar, you will find several buttons, DS, S1, S2,
and so on.  These buttons provide access to the different GTKeyboard
User Defined Shortcuts features.

  \section{Defining}

All you have to do to define your own shorcuts is to click on either
the ``DS'' button on the toolbar, or go to the options menu, and
choose
Define User Shortcuts.

Once you are in the definition menu, you will be able to type in
whatever you want GTKeyboard to spit out when you click on the
corresponding shortcut button.  Right now, what you can add is pretty
primitive, but it is functional, and also works when redirecting to
other windows.  {\it Important:} if you want the shortcuts to work,
you must click ``Install'' after each shortcut to let GTKeyboard know
that you have chosen what you want for that shortcut and it is to
remember the shortcut.

GTKeyboard will remember all ``installed'' shortcuts by saving them in
a file called \$HOME/.gtkeyboard-shortcuts.  By removing this file,
all shortcuts that you had saved will be erased, and all shortcuts
will default to ``''

  \section{Changing}

All you have to do to change the shortcuts is to reopen the shortcut
definition window, as described above, and
type in the new shortcut value.  In the status window, GTKeyboard will
let you know that it is throwing away the old value, and what that
value was.  After you click the ``Install'' button after entering the
new shortcut text, you're done.

\chapter{Customizing the Look of GTKeyboard}

For users who want to, GTKeyboard allows the customization of
fonts, screen layout, and colors that the application is displayed in.
This section is about how to take advantage of that support to make
GTKeyboard look they way you want it to look.

  \section{Customizing Keyboard Layout}

GTKeyboard comes with several different foreign keyboard, at this
point in time including Spanish, Italian, German, American, UK, and
French keyboard layouts.  If you don't see support for the national
keyboard you prefer to use with GTKeyboard, see the KEY/ directory of
the source distribution, which contains notes on how to create a
keyboard for your country.  If you create any keyboards that
GTKeyboard doesn't have, I would greatly appreciate hearing about it
so I can include it in future releases of GTKeyboard.

To change keyboard layouts, just click on the Options menu, and
select the ``choose layout'' menu item.  It will bring up a
file selection dialog which you can use to select the .key file
corresponding to the keyboard that you want to use.  Multiple key
files are installed wherever you installed GTKeyboard, which will most
likely be in /usr/local/share/gtkeyboard/ - but it may also be in
/usr/share/gtkeyboard/ depending on how your copy was installed.
GTKeyboard will try to choose the correct directory where the files
are located by default.  After you have chosen the correct file, press
OK in the dialog, and the keyboard will remap itself.  At this point,
if you wish to use the foreign keys in a redirect window, you will
have to remap the keyboard before continuing.  Otherwise, if you just
want to edit text, then you don't have to do anything extra.

  \section{Customizing Colors}

To customize the color look of GTKeyboard, all you have to do is
either click on the four-colored toolbar icon on the toolbar with the
C on it, or go to the Options menu, then Looks, then Colors, then
choose colors.  You will be presented with a standard GTK+ color
selection dialog that will let you choose which color you would like
to have your application displayed in.

When you've found a color you like, click ok, and the color will be
applied to the entire keyboard and application layout.  At this time,
the color is NOT applied to the pulldown menus.  I believe this is a
GTK+ issue, but I'll keep looking on my end of things too.

Please note that just because you can choose a color doesn't mean
that it will look good or be useful when you apply it to the
application.  Case in point, choose all black for your colors, and all
of the buttons will effectively disappear, making it impossible to see
which key you're hitting!  When choosing a color, you should probably
choose a color that looks ok against black, since that's usually what
color the button labels are in.  (This could differ, depending on
whether or not you're using a GTK+ Theme.)

If you ever want to return to the original application default,
i.e., what GTKeyboard looked like when you started it, click on either
the black ``C'' icon on the toolbar, or go to
Options $\Longrightarrow$ Looks $\Longrightarrow$ Colors $\Longrightarrow$ Reset Style to change them back to
the application defaults.  That's it.  With GTKeyboard, you can choose
just about any color that your X server can display to be the working
color for the application.

If you find a color that you like, and would like to keep using for
GTKeyboard in the future, you can use the {\it Options
$\Longrightarrow$ Looks $\Longrightarrow$ Save Layout Settings} menu
item to save those settings to a file.  That file will then be loaded
each time GTKeyboard runs.  (For exceptions to that rule, see the
IGNORE\_LAYOUT\_FILE rcfile option)  

  \section{Customizing Text Fonts/Sizes}

You may also customize the font type, weight, and size that the
main text widget uses for editing text with the font button on the
toolbar.  Just click on the italic ``F'' button on the toolbar, choose
your font, and click ok to apply it to the main text editing window.

As with application colors, this can be saved for future use with the
use of the {\it Options $\Longrightarrow$ Looks $\Longrightarrow$ Save
Layout Settings} menu item. 

  \section{Customizing Keyboard Fonts/Sizes}

Many people find that the keyboard is either too big or too small
for their use.  That's no problem.  On the toolbar, and in the {\it Options}
menu, there are items that allow you to select the font of the
keyboard.  Click on the red ``f'' letter on the toolbar to
customize the keyboard's font.  Not only will it allow you to downsize
the font, but you can also change the type of font used for different
``looks''

Depending on the font size, the buttons will shrink or grow, along
with the rest of the window.  If you want a very small window, go with
an 8 or 10 point font, although this can be hard to read.

As with application colors and text fonts, this can be saved for
future use with the use of the {\it Options $\Longrightarrow$ Looks
$\Longrightarrow$ Save Layout Settings} menu item.

  \section{Customizing Screen Size}

Sometimes people use GTKeyboard primarily to type into an rxvt, or
for some other task that does not require showing all of the different
screen elements on the screen.  For this, in the Options menu, there
is a Looks submenu, where you can choose from options having to do
with the main text box, the status box, the keyboard itself, the
toolbar, the bottom row of buttons, and a few other things.  All you
have to do to customize the layout of the screen is choose the element
of your choice in the {\it Options $\Longrightarrow$ Looks} menu.  Each item on
the screen is represented by a toggle button in the menu.  When the
toggle button is depressed, the item will be shown.  When it is up,
the item will be hidden.

For convenience, items have been added to the Options menu to
include the ability to hide everything,
and also to show everything.  This way you can toggle back and forth
between using GTKeyboard primarily as a tool to insert text into other
windows and using it as a simple text editor.

Currently, there are options to show or hide the following
GTKeyboard screen elements:  The keyboard itself, (which provides the
ability to hide/show the cursor keys, the f-keys, the number pad, and
the main keyboard independantly) the toolbar, the
bottom row of buttons, the text area where normal buttonpresses go,
and the status area that tells you what is going on with the
application.  Using these, you can make GTKeyboard as small as you
like.  Note that when you hide the output text area, the bottom row of
buttons is automatically hidden with it.

Once you've found a screen layout that you like, you can click on
the ``Save Layout'' item underneath the Options $\Longrightarrow$ Layout
menu.  A file called {\it \~/.gtkeyboard-layout} will be saved that
will be used to determine your keyboard layout for subsequent runs of the
program.  {\bf Important Note}:  When you use this feature, it creates
a file in your home directory called {\it \~/.gtkeyboard-layout}. It
contains statements on how the application should be laid out. This
file is read and used each time the application starts up, {\bf {\it
overriding any layout statements you may have in your
\~/.gtkeyboardrc}}.  To avoid this behavior, use the {\it
IGNORE\_LAYOUT\_FILE} option, described in the configuration section.
Also, if you wish for the application to stop using your layout
settings permanently, you can use the ``Forget Layout Settings''
located just under the ``Save Layout Settings'' menu item in the {\it
Options $\Longrightarrow$ Looks} menu. 

In recent releases of GTKeyboard, a directory called
``CONFIG'' has appeared in the source distribution - it holds
several different configuration files for GTKeyboard that seem to be
used the most by various people.  It has one file that enables all of
GTKeyboard's features, one that makes the program appear only as a
menu system and a small keyboard, and others.  Please check those
files out for different styles of layout to use the program with.

\chapter{Remapping the Keyboard}

GTKeyboard allows you to use several different foreign character
keyboard layouts to edit text in the text window of the application,
but at the same time, it lets you direct characters to foreign
windows.  Remapping the keyboard is the way that you coordinate these
two objectives.

The X Windowing System provides a way to change what each keypress on
the keyboard does.  In order to go from using an American keyboard to a German
keyboard in a foriegn window, you first have to change the layout of
your window to ``DE'' for German layout, and then you have to
choose the option Misc $\Longrightarrow$ Remap Keyboard which will essentially
change the function of just about every key on your keyboard.  There
are several very important things that you need to
know about this process.

\begin{itemize}
\item {\bf The process is display wide} meaning that if you
remap the keyboard using GTKeyboard, it will make those changes
everywhere.  What this means is that if you remap the keyboard, and
open another terminal emulator and begin typing into that with the
physical keyboard, it will produce foreign characters corresponding to
the way GTKeyboard is laid out, {\bf not} the way your
default keyboard is laid out. 
\item {\bf There are two ways to remap back to your original configuration}.
The first is to select your normal keyboard for your layout and use
the Remap Keyboard option, and the second is to {\bf restart your X
server}.  I recommend you remember to remap your keyboard back
to the original before you quit the application.
\item {\bf The keyboard file must be ``fully
specified''}.  Unless the .key file that you are using was
properly created, GTKeyboard will not remap to that keyboard type.
You should never have this problem with .key files distributed with
GTKeyboard, but it may be a problem with others.
\end{itemize}

  \section{Why do I keep getting remapping errors?}

This error is generated when GTKeyboard tries to send a key to a
foreign window that is not a key that The X Windowing System
understands.  In order to send nonstandard keys to redirect windows,
you must remap the keyboard.

\chapter{Word Completion}

Starting in version 1.1, GTKeyboard provides a mechanism for word
completion, similar to the mechanism provided by GNU readline.  The
only difference is that rather than working with commands, the word
completion facility in GTKeyboard works with real English (or any
other language) words.  The word completion facility allows the user
to type using the on-screen keyboard much faster than he/she would
ordinarily be able to type, because GTKeyboard can fill the rest of
the word in for you.  The majority of the guts of the code for word
completion was written by Dr. Tom {\it tomh@po.crl.go.jp} who allowed
the code to be used in GTKeyboard.

  \section{Using Word Completion}

In order to use the word completion facilities in GTKeyboard, you
need to select the {\it New Completion Window} menu item from
the {\it Misc} menu.  A new window will pop up, containing ten numbered
items with small arrow buttons on the right hand side of the rows.

This is the completion window.  Whenever you type a new character
into GTKeyboard, regardless of whether it goes to the text editing
buffer or to a redirect window, the redirection window will
``listen'' to the character you press, and will suggest up to
10 words that start with what you typed.

If you wish to use on of the listed completions, simply click on
the arrow icon to the right of the completion that is listed.
GTKeyboard will insert the remainder of the word wherever your output
was going.  (That is, if you were using a redirect window, the
completion will go there, otherwise it will go to the text editing
buffer).

  \section{Word Completion Options}

In the main word completion window, you will notice two check
buttons.  One is labeled ``Show Empty Completion Slots'', and
the other is labeled ``Insert space after completion''.

The first option, ``Show Empty Completion Slots'' controls
whether or not GTKeyboard presents you with empty options.  This is
merely a visual distinction - if this button is pressed down, then all
10 completion possibilities will be shown all of the time, even if one
or more of them is empty.  If this button is unchecked, then options
that do not contain a valid completion will be hidden from view.

The second option is ``Insert space after completion''
which controls the way GTKeyboard completes words.  Normally, if you
type {\bf q} and GTKeyboard suggests the completion
{\bf quickening}, when you choose to insert the completion,
the result is ``{\bf quickening}'', as it should
be.  If the ``Insert space after completion'' button is
checked, instead of inserting ``{\bf quickening}''
GTKeyboard will insert ``{\bf quickening  }''. (The same word
followed by a space character). For people who use this feature, it is
to account for the fact that if a word is completed, the user will
usually go on to type the next word rather than adding on to the
current word.  If that is the case, it can save time to insert a
regular space for the user.

  \section{Word Completion Cache Files}

Word completion in GTKeyboard uses a special cache file that guides
GTKeyboard in suggesting which word may be the most useful to insert
given a particular set of characters.  For example, when you type the
letter ``c'', how does GTKeyboard know whether you're thinking
of the word ``cache'', ``communist'', ``catchy'', ``cantankerous'', or
any of the other hundreds of words that start with ``c''?

Well, frankly, it doesn't.  But it can take a good guess.  This is
what cache files are for.  A cache file specifies a list of words with
their frequencies.  For example, in a text file about Darwin and
Evolution, the term ``evolution'' or the term
``species'' may be quite common.  The common terms are the
terms that we want to appear first in the completion list given the
beginning of the word.  The frequency of different words provided by
the cache file fits this role perfectly.

The default user cache file is located at
{\it \~/.gtkeyboard-wordcache}.  It will contain a list of an
arbitrary number of words with their frequencies in a given document.
Although the file is not meant to be edited by hand, its general form
looks like this:\\
\\
{\it 5 above\\
1 absence\\
2 accept\\
1 acceptance\\
2 access\\
1 accompanies\\
1 accord\\
1 achieve\\
2 act\\
1 actions\\
2 add\\
1 addition\\
}
Simply a number corresponding to the number of times the word occured
in the document followed by the word itself.  (The word
``above'' occurred 5 times, but the word
``acceptance'' occured only once) If this cache file were
used in GTKeyboard, and the character ``a'' were typed,
GTKeyboard would suggest 10 completions, from the most often occuring
to the least often occuring.  The way the words are ranked is by the
frequency number found in the cache file.

When a new completion window is created, GTKeyboard will always
load {\it \~/.gtkeyboard-wordcache} if it exists.  If it doesn't,
then GTKeyboard has to do the best it can, and usually loads the
dictionary file.  (This file is often located at
{\it /usr/dict/words} on may GNU/Linux systems).  While the
dictionary file is not optimal, it still produces decent results
depending on the application.

To load a new cache file into GTKeyboard's word completion
facility, click on the ``Load Cache File'' button in the main
word completion window.  It will present you with a file chooser
dialog.  Once you hit ``OK'', the new cache file will be
loaded in.

Users may find it interesting to have different cache files for
different tasks to speed up the task at hand.  For general text
editing that doesn't really have a particularly well defined domain,
using no cache file, (letting GTKeyboard use only
{\it /usr/dict/words}) is usually best.  For specialized tasks,
such as Perl or HTML programming with GTKeyboard, a specialized cache
the word ``print'' over the word ``perfect'' would be
very helpful, since ``print'' is the name of a built in Perl
function, and ``perfect'' isn't, even though it would occur
more often than ``print'' if the document were a general text
document.

  \section{Creating Cache Files}

Please note that you may find several different cache files which
may be of use located in the {\it cache/} subdirectory of the
GTKeyboard documentation directory.

Creating word completion cache files is quite easy - simply choose
the ``Convert Text File to Word Cache'' button located in the
main word completion window.  It will present you with a dialog asking
you to specify which file is to be converted, and what it should be
saved as.  The default is to save the newly created cache file as
{\it \~/.gtkeyboard-wordcache}, which will overwrite your previous
word cache.

Using the browse buttons to the right of the entry areas, you may
choose a filename to convert, and what to convert it to.  Note that
this process works only for text files.  It will also work on any file
you give it, but the results will most likely be an ugly, unusable
cache.  The cache file creation mechanism makes each block of letters
it sees into a word in the cache.  If you try to make a cache out of a
bit of HTML such as ``<P>This is a bit of HTML''; the
result will be a cache that looks like this:\\
{\it 1 <P>This\\
1 is\\
1 a\\
1 bit\\
1 of\\
1 HTML}\\
(Notice that GTKeyboard saw ``<P>This'' as a word, which
you probably didn't intend)

You may also choose to click the toggle button below the entry
areas, labled ``Cache words in lower case'' which will cause
words in the cache to be all lower case.  This can be helpful, since
GTKeyboard would normall consider the words ``Hello'' and
``hello'' to be different words and would count their
occurance seperately.

When you are done picking options, click the ``OK'' button,
and the cache will be created.  A status message signalling completion
will be printed into the status window.  {\it Note: GTKeyboard does not
automatically load newly converted cache files.}

In addition to this method, there is a perl script distributed with
GTKeyboard called gtkeyboard-create-cache-file.  It is located in the
same directory that the GTKeyboard binary was installed in.  To use
this program, call it with two arguments.  The first argument should
be the file to read from, and the second argument the file to save the
new cache to.

By default, gtkeyboard-create-cache-file caches all words as lower
case, and strips all punctuation from the words.  Please note that
using this additional program requires Perl, which is freely available
from {\it http://www.perl.com/}.

\chapter{HTML Coding}

GTKeyboard is also in the early stages of supporting HTML editing by
way of the graphical user interface.  In the HTML menu on the top bar
of the application, you will find a menu full of different items, all
corresponding to HTML tags.  Clicking on any of the tagnames will
cause the related tag to pop into the output text box at the bottom of
the screen.

  \section{Tag Behavior}

Some tags have mandatory input areas.  Rather than pop up a dialog as
other applications do, (which I happen to hate :)  GTKeyboard prints
the full tag out to the output section, and then places the cursor (or
point) at the location where the {\it first} input is needed.

Example:  When clicking on the LINK item in the HTML menu, the
following text is inserted into the output buffer:

<A HREF=''''></A>

GTKeyboard will then place the point between the set of quotation
marks, where the first input for the link is expected, i.e. the target
of the link.  ({\bf Note}:  Sometimes the cursor doesn't
appear to be in the right place right after a tag has been inserted, 
but it is.) 

  \section{Supported Tags}

Any tags that are not included in GTKeyboard can be added very quickly
by simply requesting them.  Alternately, write your own function to
put into html\_mode.c and send it to me.

GTKeyboard already has a long list of supported tags.  You can't find
a complete list here, but here's a sampling of some of the most
commonly used tags in super-unorganized format: 

HTML, BODY, A, B, STRONG, P, I, BR, HR, UL, LI, TABLE, TD, TR, H1, H2,
H3, H4, H5, H6, PRE, comments, FONT, BLINK, etc.

There are also a few ``convenience'' buttons that include FTP and HTTP
which simply print out ``ftp://''and ``http://'' respectively for quicker
editing of links.  There's even a ``Close Anonymous Tag'' for any
closing HTML tag, that will print </> and put the cursor in the
appropriate place for closing a tag off.

For those of you with special needs for HTML coding, or who want
more possibilities, I suggest you check out the shortcut ability to
define your own shortcuts.

\chapter{Other Features}
  \section{Double Output Mode}

GTKeyboard provides a method of doubling the output of any
keystroke on the keyboard.  In these situations, whenever the user
presses a button on the graphical keyboard, it is both sent to the
redirect window, (if there is one) and the normal
text editing buffer.

This feature is used most often for people who want complete logs
of their keystrokes.  Normally, you would use this by hiding the
editing text buffer, and typing as normal into the redirect window.
When you're done with the redirect window, you can show the text
buffer on the screen again which will contain a rough carbon copy of
whatever you typed into the foreign buffer.  This can be used as
somewhat of a virtual ``typescript'' feature.

The option is toggled off and on through the use of the
{\it Options $\Longrightarrow$ Output $\Longrightarrow$ Double Output} menu item.  Alternatively, it can
be specified through the resource file by using the {\it
SEND\_DATA\_TO\_BOTH\_WINDOWS} option.

Note that when {\it double output} is turned off after a session
of using it, the window where keystrokes are sent depends on the state
of the application.  If there is an identified redirection window, all
further keystrokes will go only to the redirection window.  If there
is not a redirection window, all keystrokes go to the text editing area.

  \section{External Programs}

GTKeyboard provides a quick way to get to several commonly used
networking applications as well.  Under the {\it Shortcuts $\Longrightarrow$ External
Progs} menu, there is a list of applications, containing Lynx, Telnet,
and FTP.  Selecting each of those items will launch the corresponding
application.  By default, they are launched inside of an RXVT terminal
emulation window if that program is available.

\chapter{Language Coding}

The first thing that should be said under any heading in the manual
for GTKeyboard is that if you don't see a shortcut in the menu that
you would like to have, please email David Allen and we'll see what we can do
about building it into the program.  They are very easy and quick to
build in, and if you check what things look like in the shortcuts.c
file and in master.h you may be able to add them yourself even.  Even
obscure ones are ok with me, because you can put the less used ones
fairly deep into a branching hierarchy so it doesn't clutter things
but is still there to speed up the process.

If you would like to use GTKeyboard for programming, no problem!  The
shortcuts provided in the shortcuts menu should speed the entry of
programming code in just about any language.  For example, in C, where
you might have to enter something like\\
{\it \#include <stdio.h>}\\
there is a shortcut for the angle braces, that will produce < > and
position the cursor between the angle braces.  You may also use the
quotation short cut for grouping text, and so on, so that you can
speed up cursor positioning and not have to hit the shift key and the
`` to produce the quotation marks. 

There are many shortcuts that are available for the user to speed
things up, from the most normal to some that are a bit strange, such
as the smiley, which will automatically insert ``:)''.  Play around with
the shortcuts menu a while, and you'll definately find a bunch of
shortcuts that can help speed up your work with GTKeyboard.

You can use these shortcuts to use emacs within a rxvt window, run
make to compile the latest version of GTKeyboard, or do any number of
other things.

\chapter{For Hackers...}

If you are a user of GTKeyboard, and have no interest in developing on
it, feel free to ignore this section.

Please, If you create any additions or modifications of this program,
I would really appreciate it if you let me know, and if it seems
reasonable, I will add it into the ``official'' release of GTKeyboard
giving credit to you in the README and AUTHORS files as well as where
the actual code is. 

  \section{Writing Keyboard Definition Files}

Keyboard definition files contain data that tells GTKeyboard not only
how to lay the keyboard out, but also contains information on how to
remap the physical keyboard settings.  They usually end in a {\it
.key} extension, and are just plain text.  They are located in the KEY
directory of the source distribution of GTKeyboard, and are usually
installed in share/gtkeyboard/ off of the prefix where the program is
installed.  

     \subsection{Sample Keyboard Definition File}

Here are the contents of one version of {\it QWERTY.key},
the file most people use by default.  Line numbers which are not a
part of the file's syntax are in {\it italics}.  Following the example are
details on the syntax and meaning of the items in the file.

{\it 1:} 14 14 13 12 5\\
{\it 2:} quoteleft asciitilde asciitilde 49      \# Begin row 1\\
{\it 3:} 1 exclam 1 10\\
{\it 4:} 2 at 2 11\\
{\it 5:} 3 numbersign 3 12\\
{\it 6:} 4 dollar 4 13\\
{\it 7:} 5 percent 5 14\\
{\it 8:} 6 asciicircum 6 15\\
{\it 9:} 7 ampersand 7 16\\
{\it 10:} 8 asterisk 8 17\\
{\it 11:} 9 parenleft 9 18\\
{\it 12:} 0 parenright 0 19\\
{\it 13:} minus underscore minus 20\\
{\it 14:} equal plus equal 21\\
{\it 15:} BackSpace BackSpace BackSpace 22\\
{\it 16:} Tab Tab Tab 23    \# Begin row 2\\
{\it 17:} q Q q 24\\
{\it 18:} w W w 25\\
{\it 19:} e E e 26\\
{\it 20:} r R r 27\\
{\it 21:} t T t 28\\
{\it 22:} y Y y 29\\
{\it 23:} u U u 30\\
{\it 24:} i I i 31\\
{\it 25:} o O o 32\\
{\it 26:} p P p 33\\
{\it 27:} bracketleft braceleft bracketleft 34\\
{\it 28:} bracketright braceright bracketright 35\\
{\it 29:} backslash bar backslash 51\\
{\it 30:} Caps\_Lock Caps\_Lock Caps\_Lock 66 LockMask \# Begin row 3\\
{\it 31:} a A a 38\\
{\it 32:} s S s 39\\
{\it 33:} d D d 40\\
{\it 34:} f F f 41\\
{\it 35:} g G g 42\\
{\it 36:} h H h 43\\
{\it 37:} j J j 44\\
{\it 38:} k K k 45\\
{\it 39:} l L l 46\\
{\it 40:} semicolon colon semicolon 47\\
{\it 41:} apostrophe quotedbl apostrophe 48\\
{\it 42:} Return Return Return 36\\
{\it 43:} Shift\_L Shift\_L Shift\_L 50 ShiftMask        \# Begin row 4\\
{\it 44:} z Z z 52\\
{\it 45:} x X x 53\\
{\it 46:} c C c 54\\
{\it 47:} v V v 55\\
{\it 48:} b B b 56\\
{\it 49:} n N n 57\\
{\it 50:} m M m 58\\
{\it 51:} comma less comma 59\\
{\it 52:} period greater period 60\\
{\it 53:} slash question slash 61\\
{\it 54:} Shift\_R Shift\_R Shift\_R 62 ShiftMask\\
{\it 55:} Control\_L Control\_L Control\_L 37 ControlMask   \# Begin row 5\\
{\it 56:} Alt\_L Alt\_L Alt\_L 64 Mod1Mask\\
{\it 57:} space space space 65\\
{\it 58:} Alt\_R Alt\_R Alt\_R 113 Mod1Mask\\
{\it 59:} Control\_R Control\_R Control\_R 109 ControlMask\\

    \subsection{Explanation of Sample Keyboard File}

Each keyboard definition in GTKeyboard consists of 5 rows of keys.
Each row contains multiple keys.  Line 1 in the file always tells
GTKeyboard how many keys are going to be on each row. In this case,
the first line, {\it 14 14 13 12 5} means that there will be 14 keys
on the first row, 14 keys on the second row, 13 keys on the third row,
12 keys on the fourth row, and 5 keys on the fifth row.  With that
laid out, the rest of the file consists of one key definition per
line.  If you specified that there are 14 keys in the first row, then
the first 14 key definitions will be assigned to the first row, from
left to right.  If you specified that the second row should have 14
keys as well, the next 14 keys will comprise the second row, from left
to right.

In the sample file you will notice commentary such as {\it \# Begin row
2}.  GTKeyboard ignores these comments - they are merely there to
remind the person writing the file where each row begins.

Now all the file really consists of is a series of key definitions.
Key definitions contain up to 5 parts.  The first three parts are all
KeySyms.  KeySyms are the X server's way of keeping track of various
symbols.  Names for all of the possible KeySyms may be found in {\it
/usr/include/X11/keysymdef.h}.  If this file doesn't exist you may
want to consult your local administrator for the location of the X
server include files.  In that file, you will find lists of KeySyms
looking like this:

\#define XK\_Y                   0x059\\
\#define XK\_Z                   0x05a\\
\#define XK\_bracketleft         0x05b\\
\#define XK\_backslash           0x05c\\

In this case, XK\_Y refers to the character ``Y'' (upper case).  XK\_Z
refers to the character ``Z'' (upper case).  XK\_bracketleft refers to
``[``, and XK\_backslash refers to the blackslash character.  In all of
these lists, take the name of the KeySym as listed in {\it
/usr/include/X11/keysymdef.h}, remove the beginning ``XK\_'' and you
have a KeySym name for the GTKeyboard keyboard definition file.

Each key definition line starts with three KeySym definitions.  For
example, in line 37, we see a lower case j, followed by an upper case
J, followed by another lower case j.  The first KeySym is what the
pressed key will do under normal conditions.  The second KeySym is
what the key will do when pressed in combination with either Shift or
Caps Lock.  The third KeySym is what the key will do when pressed in
combination with the Mode Switch key.  Usually this is labeled ``Alt
Gr'' on most keyboards.  For US keyboard layouts, generally this isn't
used, but still must be specified.

Following the three KeySyms is the KeyCode.  The KeyCode is an integer
assigned to each key on a physical keyboard.  This KeyCode is what
allows GTKeyboard to do much of its remapping work.  While it is not
required, it is strongly recommended.  Without specifying the KeyCode
for each and every key in the keyboard definition file, GTKeyboard
will be unable to remap your physical keyboard to the settings you
specify in that file.

In order to find the KeyCode for a particular key, use the ``xev''
program that comes with your X server.  By placing the mouse in the
xev window and pressing a button, xev outputs data about the key to
standard out.  Example:

KeyPress event, serial 27, synthetic NO, window 0x3800001,\\
    root 0x26, subw 0x0, time 492725957, (100,0), root:(101,521),\\
    state 0x0, keycode 40 (keysym 0x64, d), same\_screen YES,\\
    XLookupString gives 1 characters:  ``d''\\

This information tells us that the ``d'' key is bound to KeyCode 40.
When trying to find keycodes for particular keys, xev is very
helpful.  Remember that KeyCodes are bound to particular physical keys
on the physical keyboard.  KeySyms are not until you use the keyboard
remapping feature in GTKeyboard.

The final field is a modifier mask.  This field is only used for
modifier keys.  A modifier key is generally a key that doesn't output
a character by itself, it modifies another keystroke.  Examples
include Caps Lock, Alt, Control, and Shift.  Each modifier key may be
followed by a modifier mask.  There are eight possible modifier masks,
{\it ShiftMask}, {\it LockMask}, {\it ControlMask}, {\it Mod1Mask},
{\it Mod2Mask}, {\it Mod3Mask}, {\it Mod4Mask}, and {\it Mod5Mask}.
Modifier masks for modifier keys are mandatory for keyboards which you
wish to do remapping with.  GTKeyboard cannot successfully remap
keyboards whose definitions do not contain modifier masks.

You may specify the mask for each modifier.  As the name suggests,
{\it ShiftMask} is a good choice when specifying the modifier for
Shift\_L and Shift\_R.  The keyboard file may specify any modifier mask
for any modifier, but the general rule is that Shift\_L and Shift\_R are
assigned to {\it ShiftMask}, Control\_L and Control\_R are assigned to
{\it ControlMask}, Caps\_Lock is assigned to {\it LockMask}, Alt\_L and
Alt\_R are assigned to {\it Mod1Mask}, and Mode\_switch is assigned to
{\it Mod2Mask}.  Keys that perform the same function, (as with Shift\_L
and Shift\_R) should use the same modifier mask.  Each modifier mask
may hold no more than 2 distinct keys unless you know that your X
server can handle more.

Once your keyboard definition file is successfully constructed,
there's nothing else to it - you can simply load GTKeyboard, and use
the ``Change Layout'' function to load your new keyboard onto the screen.

  \section{Debugging}

Compilation with debugging symbols is usually OFF by default.  If you
would like to change that, then just add the {\it -g} option inside of
the CFLAGS variable in the main ``Makefile''.  Different versions differ
in policy about that.  Along with debugging, there is an option in the
help menu, under debugging, that is for you to be able to dump core if
you want to.  That's something I've used on and off, and it can be
useful, so it was added in.  I'm trying to force people to use that if
they want a corefile, since hopefully it's set up so you can't get it
to dump core any other  way. :)

If you would like to compile with all debugging enabled, make sure
that the symbol ``PROD'' is {\bf not} defined in the
Makefile, and recompile with ``make static''.  (Note:  Before you can
``make static'', you have to run ``make obscure'' which copies your static
libraries into the foo/ directory, where it will link against them.
If your static libraries are in different places, you'll need to copy
them into that location.)  With ``make static'', GTKeyboard will compile
with static libraries, with calls like g\_mem\_profile() compiled in.
(You {\it did} compile your glib/GTK+ with memory profiling, didn't
you?)  It will also print the result of various memory macros that are
located in the include/ directory in mem\_header.h.  This causes quite
verbose output, but in the end you get a total of how much memory has
been allocated/freed by GTKeyboard.  The g\_mem\_profile() call of
course includes statistics on memory allocated by GTK+ as well.

Note that in the file {\it include/memheader.h} there are
several macros for tracking memory usage which won't really expanded
to much if debugging is not on, but if it is, sometimes to multiple
statements.  Particularly the {\it glib} calls that end with an
underscore.  Because they are multiexpression macros, you really don't
want to do something like:\\
{\it if(mem)\\
      g\_free\_(mem);}\\
But rather do this:\\
{\it if(mem)\\
  \{\\
     g\_free\_(mem);\\
  \}}\\
To account for the fact that it may or may not be a single replacement
line macro.

Also of interest to developers are the files INTERNALS and
gtkeyboard-arch.txt located in the main directory of the source tree.
They explain parts of the way the source works, to facilitate others
in hacking on GTKeyboard.  At the moment, that documentation isn't
really all that great, but at least it's there, and it's something.
If you would like to see any more specific information in that
document, please write the section and submit it to {\it
s2mdalle@titan.vcu.edu} for inclusion in the next version or let me
know and I'll do the write up myself when time becomes available. 

  \section{Extra Macros}

Extra debugging messages that are normally sent to stderr are also off
for regular use as a program.  If you'd like to see those messages,
then make sure the symbol ``DEBUGGING'' is defined, for example, insert
the line -DDEBUGGING=1 into the CFLAGS line of the Makefile.  Then the
program will compile with extra debugging messages letting you know
what it's doing at any given time.  Also, for a given version, defining
TEMP\_DEBUGGING will spit out debugging messages that have been
recently added and so on.  Finally, if you're paranoid about the way
that keysym\_callback() is working, (it is what
drives the insertion of text into output\_text widget) then define
CONSOLE\_OUTPUT and it will spit diagnosticts to stdout and stderr as
it's needed.  To enable all possible ugliness in the code, put the
following in the CFLAGS variable in the top level Makefile:
-DCONSOLE\_OUTPUT=1 -DDEBUGGING=1 -DTEMP\_DEBUGGING=1 -DV\_DEBUGGING=1
and recompile. Also, if you define {\bf GUI\_EVERYTHING} in app.c, then write
success/error messages will pop up in their own windows rather than
just in the status buffer. 

  \section{HTML Mode}

Probably the easiest part of GTKeyboard to hack on is to add HTML
items. If you're interested, check out html\_mode.c where you can add all of
the new HTML tags that you want.  You then have to edit master.h and
edit the menu structure to include whatever function you put in
there.  If you're familiar with item factories, it's criminally
simple.  The same goes for shortcuts.c which I would like to see more
shortcuts in.  Basically when I code, I put in what I think people can
use, and if anybody sends me a suggestion that gets put in to.  In
html\_mode.c I use the function {\it vanilla(char *input)} which inserts into
output\_text heavily.  That way, if I find I wanna redirect things
later, I make some simple changes to vanilla and change where
everything goes.  Also I provided cursor\_left\_x\_times(int whatever) so
that you could repeat cursor\_left() without having to set up for loops
and extra variables.  Just pass it the strlen(something) where
something is usually the closing HTML tag.  (html\_mode.c has 1000 examples)

  \section{The Future}

We're currently working on cleaning up the issues with remapping
keyboards, and adding more keyboards, which may be somewhat slow.  I
incorporate user requests for features as long as they're reasonable.
(Don't ask for a 3D graphics keyboard ``visualizer''  :)

And of course, the future brings the hope that I will ruthlessly
eradicate any bug that I (or you) can find in GTKeyboard.  As said,
the redirection code is up for a rewrite, and when that happens, there
may be some small issues to work out.

\chapter{Troubleshooting Guide}
  \section{Compiling GTKeyboard}

To successfully compile GTKeyboard, you need a few things.  First,
you'll need GTK+/glib (The GIMP Toolkit) which can be obtained from
{\it http://www.gtk.org}, a standard C library, an ANSI C compiler, (such as
gcc/egcs), the GNU make program, and of course, a shell, and a
reasonably recent version of X11 (with headers).  If you already have
GTK+ installed, you shouldn't have much of a problem, since GTK+ and
GTKeyboard share many prerequisites.

GTKeyboard is written and tested on Debian GNU/Linux (Woody) dual P3
933Mhz system.  The program compiles with special flags telling the
compiler to issue all relevant warnings, and compiles without any
warnings on my machine.  I have also compiled it on a few 64bit alpha
CPUs with a few warnings, but no problem in the functioning of the
resulting binary.  Binaries for other platforms are made available
when they are provided by outside porters.

If you have problems compiling GTKeyboard, I'm betting that its one
of a few things right off the bat:  Do you
{\bf {\it really}} have an ANSI C standard compiler?  If
not, go grab a copy of GCC from the Cygnus EGCS page at {\it
http://egcs.cygnus.com}.  Previously, you would have also needed to have
a libc that contained the {\it strsep()} call, but this requirement
has been eliminated and replaced with {\it glib} calls.

If you have a compilation problem that you're sure is not one of
the above, and you have all of the needed libraries/software to
compile it, please contact David Allen and let him know about it,
along with the {\it exact} output of the configure script, and of the
make process, and a copy of your config.h file which will be generated
at the end of the configure process. 

  \section{Installing GTKeyboard}

When you ran the configure script, did you give it a
{\it --prefix=/my/home/directory argument}?  If you didn't, then GTKeyboard
is going to install itself into /usr/local/bin/ by default, with the
documentation in /usr/local/share/gtkeyboard.  If you have problems
installing, edit the Makefile, and change the PREFIX = line to
wherever you want it to install.  Failing that, just move the
gtkeyboard binary to wherever you like, and copy the documentation
wherever you like as well.  (Some information popups look for the
documentation in predictable places though, and if it can't find it
there, it won't display properly.)

  \section{Redirecting Output To Another Window}

First, are you trying to insert text into a box within a window?
If so, make sure that the box you want to redirect to is focused.
(Just click on it once, and it should get a thin black border to let
you know that it's focused).

Are you using xterm or XEmacs?  Some users just have problems with
that.  See the section on redirecting to other
windows for some notes on what will work and what will work with
some special configuration.

Are you using an application that should work, but doesn't?  Please
contact {\it s2mdalle@titan.vcu.edu} with these issues.

  \section{Program Layout}

The most common problem in this area is that a person will have
spent a few minutes writing his/her {\it \~/.gtkeyboardrc} file to make the
program look the way he/she wants it to, they start the application
up, and the layout is totally different.  What gives?  Usually this is
due to a {\it \~/.gtkeyboard-layout} file which the program is reading and
using as your layout, ignoring your configuration file settings.  If
you'd rather use your configuration file to specify layout, use the
{\it IGNORE\_LAYOUT\_FILE} option in your {\it .gtkeyboardrc} to tell the
program to ignore the layout file.  Restart the program, and
everything should be peachy.

To customize the program's looks, your first stop is the options
section of the manual to see what's available.  Then, check out the
layout section to see what you can do in the way of showing/hiding
different elements of the screen layout. 

Other than that, if you've gotten GTKeyboard to a layout that you
like, use the ``Save Layout Settings'' option in the
{\it Options} $\Longrightarrow$ {\it Looks} menu to save it all to a file,
{\it \~/.gtkeyboard-layout}.  Please note though that this may cause the
first problem in this section if you're not paying attention. :)

\chapter{Miscellaneous}
  \section{Undocumented Features}

There are a many other features to GTKeyboard that aren't
included in this manual that give you various degrees of freedom with
the application.  Among the (currently) undocumented features in
GTKeyboard are the following that you can play with.  Most that aren't
described here are fairly straightforward.  Actually, some are
documented in the various README files within the source distribution,
if you're interested.  Failing enough information on any particular
topic, please contact the author for clarification.

\begin{itemize}
    \item Defining new keyboard layouts for GTKeyboard.  (see
        {\it KEY/README} in the source distribution) 
    \item Building RPMs of GTKeyboard (see
        {\it rpm/RPM-BUILDING-README} in the source distribution -
        a spec file is included)
    \item Example configuration files outside of manual examples (see
        {\it CONFIG/README} in the source distribution)
    \item Hacking on GTKeyboard
\end{itemize}

  \section{Other Similar Programs}

There is a package similar to GTKeyboard available currently for
Windows called EOSK the Extended On Screen Keyboard. As I understand,
this package is available under the GNU General Public License, and is
written in Delphi if my memory serves me right.  Unfortunately, I do
not have a pointer to more information on this program; you may be
able to find more through various internet search engines.

\section{Bugs}

The buglist for gtkeyboard is provided through GNU at 
{\it bug-gtkeyboard@gnu.org} for your enlightenment. It is a currently
a mail alias, but may be a list in the future.  Send all bug reports
there.  You will find a list of known bugs in the BUGS file in the
main source directory.  You may also send bug reports to {\it
s2mdalle@titan.vcu.edu} 

The current bugs in GTKeyboard are usually small cosmetic issues,
and sometimes minor annoying things that I'm working on currently or
are planned to be fixed.  There aren't any major stability issues that
I know of.  If you find one, email the bug list and let us know.

\section{Helping With GTKeyboard}

If you would like to help with the development of GTKeyboard, please email
the author, and specify what you'd like to help with.  There are currently 
about 4 active people working on the project, with many others helping
out by sending in coredumps, compilation problems, requests for documentation
updates, and so on.  If you think this documentation sucks, 

\begin{itemize}
\item I agree
\item Help out.
\end{itemize}

\section{GTKeyboard's Direction}

There should be a good number of very interesting things happening
with the program in the future.  I've gotten submissions from various
people around the net of pieces of code that would possibly allow us
to build in handwriting recognition and word completion against a
fixed cache of words.  There also seem to always be the calls for more
customizeability which will possibly be added as we get the time to
deal with them.

If you think you can do any part of GTKeyboard better, let me know and I'd
love to get other people involved to speed up development.  I'm also always
totally open to suggestions for features.  Whether they're incorporated or
not has to do with whether I can code them, but I try hard to keep the users
happy since this project is primarily for the users.

  \section{Things that don't belong in any other category}

GTKeyboard is written in C, using the fine GTK+ toolkit available from
{\it http://www.gtk.org}.  It is written
and tested on a Debian GNU/Linux machine.  GTKeyboard
is completely Free Software, licensed under the terms of the GNU
General Public License.  If you would like to reuse some of the code
that is in GTKeyboard, feel free.  I would appreciate it if you would
mention my name in the list of contributors to the project that you
include some of this code into - and most of all, that if you use any
of the code from this program, you respect the fact that it is covered
under the GPL...  

The file COPYING that should come with the source distribution of
GTKeyboard as well as any binary packages you may download contains
the terms of the license.  If you did not get a copy of the license
with this program, you can either write David Allen,
or you can get in touch with the Free Software Foundation, at {\it
http://www.gnu.org/} for a copy of the license.  Since it is under the
GNU General Public License, I should probably tell you about... 

\section{Disclaimers and Important Information}

Do not use GTKeyboard to run nuclear power plants, pilot aircraft,
please your wife, start international war, blend fruits and nuts into
a creamy shake, self-medicate, or as a treatment or cure for any
disease.  I have tried to make the program as robust as possible, but
there is always the vague possibility that the application will
suddenly start cursing at you in Russian or otherwise behave strangely
depending on your platform, operating system, day of the week, or
configuration.  GTKeyboard is written and tested on a modified Red Hat
Linux workstation, with several other users contributing patches for
interoperability with other operating systems including Solaris, and
Linux/PPC. 

And now less chicanery and what I really came here to say...

{\bf GTKEYBOARD COMES WITH NO WARRANTY}

\begin{sloppypar}
{\bf BECAUSE THE PRO\-GRAM IS LICENSED FREE OF CHARGE, THERE IS NO WAR\-RANTY
FOR THE PROGRAM, TO THE EXTENT PER\-MITTED BY APPLICABLE LAW.  EXCEPT
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.}
\end{sloppypar}

So, hoping that didn't scare you off, enjoy the program!  If you enjoy
the software, you can pay me simply by emailing me with your name, and
where you live, and how you use GTKeyboard.  You are of course not
obligated to do that, I just enjoy hearing about where GTKeyboard has
traveled, as I like to live vicariously through software.
  
\chapter{Outro}

\section{Closing Observations}:

\begin{itemize}
\item I am not a writer, and I don't particularly think much of my own
documenting skills.  Email me at {\it s2mdalle@titan.vcu.edu} if you
have any questions or problems relating to GTKeyboard that aren't
addressed here, or if you can alleviate some of the discomfort of my
pathetic wallowing attempts at documentation.  :)
\item This document is the manual, and the FAQ, both wrapped into one
cumbersome document.  :)  If someone told you to RTFM, you are in the
right place.
\item Documentation is like sex; when it's {\bf good}, it's very, very
good.  And when it's {\bf bad}, it's better than nothing.
\end{itemize}

\section{Useful Internet Resources}

Here are some internet resources directly applicable to GTKeyboard.

\begin{itemize}
\item The Free Software Foundation located at {\it
http://www.gnu.org/}, providers of Free Software.  Life is good.
\item David Allen's page, located at {\it http://opop.nols.com}
\item GNU GTKeyboard Pages at {\it
http://www.gnu.org/software/gtkeyboard/}
\item GNU GTKeyboard Downloads at {\it ftp://alpha.gnu.org/pub/gnu/}
\end{itemize}

Other Resources:

\begin{itemize}
\item XKeyCaps, written by Jamie Za-winski, can be found at {\it
http://www.jwz.org/xkeycaps}.  It is a program similar to GTKeyboard,
but primarily used as a front end to xmodmap.
\item Freshmeat.net, located at {\it http://www.freshmeat.net}.
Freshmeat is a directory where GTKeyboard is listed that provides
links to hundreds of Free Software applications.
\end{itemize}

Author Contact Information:\\
M. David Allen\\
1108 W. Franklin St. Apt \#206\\
Richmond, VA  23220\\
USA\\
Email: {\it s2mdalle@titan.vcu.edu}\\
Web: {\it http://opop.nols.com/}

Document last updated on November 28, 2000 01:14 AM to reflect GTKeyboard
1.1.5. This manual was written with the One True Editor, {\bf GNU
Emacs} which can be obtained through the Free Software Foundation
located at {\it http://www.gnu.org/}

\end{document}

