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


Welcome to GOK.  Please note that this is an unstable release and that
GOK 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.

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.

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/

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.

Installing
==========

Please see the INSTALL file.

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 at
product quality.

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.
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.

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.

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

GOK cannot currently latch or lock modifier keys using Stick Keys in
Direct Selection.  This means that GOK cannot output keystrokes with
any modifiers applied in Direct Selection.

4. Modifiers lock and cannot be turned off when using Sticky Keys and
   "Switch" actions

Modifiers lock and cannot be turned off when using Sticky Keys and
"Switch" actions, for example in scanning access methods.  In addition
once one modifier is locked no others can be locked.  The result of
this is that using modifiers should be avoided when using "Switch"
actions.

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.

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.  To enable Sticky Keys use the
Keyboard accessibility preference tool in the Accessibility section of
the GNOME Desktop Preferences.

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: Friday, April 4th, 2003.
