Version 0.11.3

GNOME On-screen Keyboard (GOK)
******************************


Welcome to GOK.  Please note that although this is a "stable branch"
of GOK, this is still an "evaluation release"; in 
other words GOK is still undergoing active development and testing, and
may crash or behave unexpectedly.   With this in mind we would like
to thank you very much for your interest in GOK and hope very much
that you find it useful.

Before reporting GOK problems, or attempting to make significant use of GOK, 
please read this file and the file named "NEWS" carefully for hints about
how to configure your system and GOK to work together, paying particular 
attention to the section titled "Input Devices" (below).  

Contact
=======

The GOK web site is:

http://www.gok.ca/

There is a GOK mailing list, please see the GOK web site for
information on joining and for an archive of the mailing list.
There are also a general-interest accessibility mailing list for
developers (gnome-accessibility-devel@gnome.org) and users 
(gnome-accessibility-list@gnome.org) of Gnome accessibility features; 
please see http://mail.gnome.org for subscription info.

If you would like to contribute to this project please feel free to
contact David Bolter (david.bolter@utoronto.ca).

Reporting Bugs
==============

If you experience problems using GOK we encourage you to report the
problem so that we can address it and make GOK a better and better
piece of software.  GOK is using the GNOME Bugzilla to track bugs.  To
report a bug please go to:

http://bugzilla.gnome.org/

and select 'gok' from the product list.

Overview
========

The GNOME On-screen Keyboard (GOK) is a dynamic on-screen keyboard for
UNIX and UNIX-like operating systems.  It features Direct Selection,
Dwell Selection, Automatic Scanning and Inverse Scanning access
methods and includes word completion.

GOK includes an alphanumeric keyboard and a keyboard for launching
applications.  Keyboards are specified in XML enabling existing
keyboards to be modified and new keyboards to be created.  The access
methods are also specified in XML providing the ability to modify
existing access methods and create new ones.

GOK is not limited to presenting keyboards that have been designed by
hand and is able to dynamically create keyboards so that it can adapt
to the user's current situation.  GOK is able to redisplay components
of the user interfaces of running applications directly within GOK as
keyboards.  This provides efficient access to elements of the user
interface, removing the need to navigate the interface indirectly
though keyboard accelerators.  GOK supports the redisplay of
application menus and toolbars.  GOK contains a window activator
keyboard that lists the current windows on the desktop and provides
the ability to switch between them.

Users have the option of setting key width, height, and spacing as
well as visual and auditory feedback on highlighting and selection.

GOK can be further customized if you have programming skills, and
contributions are welcome.  If you build GOK from source, you will
find some documentation about Gok's internal APIs the 
gok/docs/reference/html directory.

Installing
==========

Please see the INSTALL file for information on building and
installing GOK from source code.

Running
=======

Once GOK is installed it can be run from anywhere.  For example, if
the gok binary is in your PATH, open a shell:

$ gok

Notes
=====

To use the dynamic features of GOK, such as the "Menus" and "Toolbars"
keyboards, you will need to run an application that is compatible with
the GNOME 2 accessibility features, such as GNOME 2 applications.
Please also set the GNOME accessibility GConf key:

$ gconftool-2 -s /desktop/gnome/interface/accessibility -t bool true

Documentation
=============

The User Manual for GOK can be viewed using the GNOME help browser and
can be found under the category "Accessibility".  The User Manual may
also be viewed by selecting the "Help" button on the GOK Settings
dialog.

Keyboard Editor
===============

GOK has a keyboard editor that can be used to create new keyboards and
modify existing ones.  The keyboard editor is started by running GOK
as follows:

$ gok --editor

Please note that the editor is still in development and is not yet of
product quality.

Input Device Configuration
==========================

GOK can be configured to respond to user input from pointing devices
and button or switch devices.  In most cases these are devices which are
capable of emulating mice, either as 2d pointing devices, mouse-buttons, 
or both.  In addition there are commercially available USB and serial 
devices which emulate mouse clicks directly or which allow the connection 
of simple contact switches.  (It is even possible for the inventive person
to modify a standard commercial mouse to accept a switch device, with a 
soldering iron and a female "mini phono plug").

In all of the above cases, standard mouse drivers shipped with your
operating system can be configured to operate with these devices.  

One important distinction is that between the "core pointer", i.e. the 
main pointer usually associated with a desktop mouse, trackball, or 
touch pad, and "extended input devices".  The same device drivers can
be configured in one of three ways:

(a) as the primary/core pointing device;
(b) as an additional pointing device which is 'chained' to the core pointer;
(c) as an additional pointing device which is NOT associated with 
    the primary pointing device.

GOK can be used with devices in category (a) and (c); best results are
obtained via (c) since there are known conflicts between GOK's use of the 
core pointer and some functions of the user's desktop software and 
applications.  In such cases the device via which the user interacts with
GOK does not drive the system pointer directly, though GOK's "Mouse"
keyboard allows the user to manipulate the system pointer indirectly.

To configure a physical device as an "extended input device" of type c, you 
must modify your X Window System's configuration.  The name of the file,
and the exact details of its syntax, vary according to your operating system.
The file is human-readable and editable by the 'root' user or system 
administrator.  Common names for the configuration file include
"XF86Config", "XF86Config-4", "owconfig"; you should consult your
operating system documentation for details.  Many recent systems 
already include support for multiple "mice", so you need only 
change a configuration of type (b) to one of type (c) by telling 
the X Windows system _not_ to chain the devices together.

Example:  

     In XF86Config, there exist "InputDevice" sections called
     "Mouse0", associated with '/dev/psaux' (the PS/2 mouse port), 
     and "DevInputMice" which is associated with '/dev/input/mice'
     which on this system is the driver for USB mice.  In section
     "ServerLayout", "Mouse0" has the "CorePointer" attribute,
     and "DevInputMice" has the "AlwaysCore" attribute.  To
     change this configuration to allow GOK to be driven by a
     USB pointer or switch device, we should remove the "AlwaysCore"
     attribute from "DevInputMice" and also remove any "AlwaysCore"
     or "SendCore" attributes from the "DevInputMice" InputDevice 
     section itself.  These changes take effect the next time the 
     X Windows System is restarted, or on system reboot.  

     For more information please contact your operating system
     distributor or system administrator.

     Not every system has multiple connections for the system mouse;
     furthermore, some users may prefer to operate GOK via the
     primary pointing device.  If those users are able to both
     point and activate a switch, they can recover from any 
     conflicts between GOK and the primary pointing device.  For such
     users, it may be preferable to configure GOK's access methods to
     use the 'core pointer' device rather than extended input devices.
     
By default GOK lists core-pointer mouse actions, called "Left Mouse 
Button", "Right Mouse Button", etc., and switch actions, called
"Switch 1", etc. which are associated with the user-specified extended
input device.  Please see the GOK Help pages for more details.

Known Issues
============

1. GOK is not responsive when applications have a core pointer grab

GOK is not responsive when applications have a core pointer grab, unless
GOK has been configured to use alternate input devices 
(i.e. 'XInput' devices).

This situation arises when an application that uses the GTK+ toolkit,
such as a GNOME application, displays a menu on the screen.  The
result of this is that application menus should currently not be
navigated using GOK with keyboard accelerators, such as Alt + F.  Menus
should instead be navigated using the GOK dynamic "Menus" keyboard
which redisplays an application's menus in a GOK keyboard and is
available on the "main" GOK keyboard.

Alternatively, reconfiguring your X Windows environment and GOK to associate
the physical device with an "extended input device" rather than the
mouse device will circumvent this conflict and allow menu navigation via
synthesized keystrokes as well as via the GOK dynamic 'Menu' keyboard.

2. When using the "Switch" actions the mouse pointer cannot send
   clicks to applications other than GOK

When using the "Switch" actions, for example in a scanning access
method, the mouse pointer cannot send clicks to applications other
than GOK.  In order to exit GOK it may, therefore, be necessary to
switch to a terminal window and kill GOK there.

This limitation does not arise when using GOK in "extended input device" 
mode (see issue #1 above).

3. GOK cannot latch or lock modifier keys using Sticky Keys in Direct
   Selection

As a convenience feature, GOK reacts to direct-selection mouse clicks
even when another access method has been chosen, [exception: 
this convenience feature is not available if the primary mouse
is being used to drive GOK one of the scanning modes.]  
However this convenience feature is not compatible with Sticky Keys.
If you wish to use GOK in direct-selection mode, it is preferable to 
specify 'Direct Selection' from the Access Methods preference dialog.
Please check to make sure that you are using the specified
input device (e.g. 'corepointer' or 'other input device') rather than
relying on the fallback/convenience direct selection mode.

4. Cannot latch modifiers using GOK

This problem arises if GOK is configured to use an extended input device,
and that input device is configured to drive the "core pointer" (i.e. 
primary mouse device) as well.  To fix this, please reconfigure your
X Windows System to dis-associate the extended input device from the
core pointer (in most cases this means removal of the 'AlwaysCore' or
'SendCore' flags from the section of your X configuration file which
deals with your input device).

5. Dynamic keys remain active when they are not applicable

Under some circumstances dynamic keys, such as keys that redisplay an
application's menus, remain active when they are not applicable.  This
can happen when the application looses focus or is shutdown.  In this
situation please use the "back" button to return to the "main"
keyboard.

6. GOK battles with other panels when docked.

If you plan on docking GOK where there is already a panel, we recommend
moving of removing the existing panel.

Troubleshooting
===============

1. When GOK runs it displays a message saying that it cannot retrieve
   GConf settings.

GOK requires certain settings to be in GConf in order to run. Those
settings should have been added to GConf when GOK was
installed. Please ensure that GOK has been installed correctly. Please
see the file INSTALL for details. If GOK has been installed following
those suggestions and there are still problems see the next point for
a possible solution.

2. After a 'make install' GOK still fails to retrieve GConf settings.

You may need to restart gconfd.  You can use this command:

$ gconftool-2 --shutdown

or log out and back in again.

Your problems may also be due to interaction between GConf 1 and GConf
2. GOK uses GConf 2 and there seem to be problems installing and
running GOK if GConf 1 is running on your machine. In order to check
if GConf 1 is running please use this command:

$ ps -ef | grep gconf

If you see a line for gconfd-1 please shutdown GConf 1 with:

$ gconftool-1 --shutdown

Now 'make install' and GOK should work as intended.

3. The GOK User Manual does not appear in the GNOME help browser

The GOK User Manual should be listed under the "Accessibility"
category.  If it is not it may be because GOK was not installed with
the correct localstatedir.  GOK needs to be configured with a
localstatedir such that the scrollkeeper_docs file is at this
location:

$localstatedir/scrollkeeper/scrollkeeper_docs

You can specify the localstatedir when GOK is built:

$ ./configure --localstatedir=LOCALSTATEDIR

If localstatedir is not specified when GOK is built it defaults to
/var/lib.  For more information on building GOK please see the INSTALL
file.

4. Modifiers do not latch or lock on the Compose keyboard

Latching or locking of modifier keys, such as Shift and Ctrl, may be
performed by enabling Sticky Keys.  Sticky Keys requires that the 'XKB' 
feature be enabled on your X Windows system, and that the keyboard 
accessibility features of your desktop be enabled.  Keyboard accessibility
features of your desktop can be configured via the Keyboard Accessibility
Preferences dialog, which on most systems is found in the 
Applications->Desktop_Preferences->Accessibility menu reachable from the
GNOME panel or right-click context menu on the desktop.

5. GOK is stuck on a broken access method

You can start GOK directly at the settings dialog with the following
command:

$ gok --settings

This should enable you to fix GOK settings.

6. I would like to reset GOK to its default settings

Currently, the only way to do this is to delete your GConf
settings. Typically this can be done with this command:

$ rm -r $HOME/.gconf/apps/gok

--

This document last updated: Monday, September *th, 2003.
