Documents/README.KeyTables

~~~~~~~~~~
Key Tables
~~~~~~~~~~

.. include:: prologue.rst

Description
===========

Files with names of the form ``*.ktb`` are key tables, and with names of the
form ``*.kti`` are key subtables. They are used to bind braille device and
computer keyboard key combinations to BRLTTY commands.

*  Braille device key tables can usually be found in the
   ``/etc/brltty/Input/xx/`` directory, where ``xx`` is the two-letter braille
   driver identification code (see `Braille Driver List`_). The name of a
   braille device key table identifies the model(s) for which it is used. The
   driver selects which key table is to be used.

*  Computer keyboard key tables can usually be found in the
   ``/etc/brltty/Keyboard/`` directory. The name of a keyboard key table
   describes the kind of keyboard for which it has been designed. See
   `Keyboard Table List`_ for a list of BRLTTY's keyboard tables.

*  See |README.Customize| for more details regarding key table locations.

A key table consists of a sequence of directives, one per line, which define 
how keys and key combinations are to be interpreted. UTF-8 character encoding 
must be used. Whitespace (blanks, tabs) at the beginning of a line, as well as 
before and/or after any operand, is ignored. Lines containing only whitespace 
are ignored. If the first non-whitespace character of a line is ``#`` then
that line is a comment and is ignored.

The precedence for resolving each key press/release event is as follows:

1) A hotkey press or release defined within the current context.
2) A key combination defined within the current context.
3) A braille keyboard command defined within the current context.
4) A key combination defined within the default context.

Directives
==========

.. |key operand| replace::
   The name of the key whose availability is to be tested.

.. |platform operand| replace::
   The name of a host platform.
   The following platform names are recognized:
   android, apple, cygwin, dos, grub, linux,
   mingw32, mingw64, openbsd, sun, windows.

The Bind Directive
------------------

.. parsed-literal:: bind *keys* *commands*

Use this directive to define which BRLTTY command is executed when a particular
combination of keys is pressed. The binding is defined within the current
context.

*keys*
   The key combination which is to be bound. It's a sequence of one or more key
   and/or key group names separated by plus (``+``) signs. The final (or only)
   key name may be optionally prefixed with an exclamation (``!``) point. For
   example::

      key1
      group1
      key1+key2
      key1+key2+group1
      !group1
      key1+!key2

   A key group name refers to any key within the named group. A specific key
   within the group may be identified by appending a dot (``.``) and a number
   to the group's name. The first key within a group is key #1 (e.g.
   ``keyGroupName.1``).

   The keys may be pressed in any order, with the exception that if the final
   key name is prefixed with an exclamation point then it must be pressed last.
   The exclamation point prefix means that the primary command (see below) is
   executed as soon as that key is pressed. If not used, the primary command is
   executed as soon as any of the keys is released.

*commands*
   The primary and secondary BRLTTY commands that are to be bound to the key
   combination. The two commands (primary first and secondary last) are
   separated from one another by a colon (``:``). Both commands are optional.
   If just a primary command is being bound then the colon needn't be supplied.
   All of these are valid:

   *  bind key primaryCommand
   *  bind key primaryCommand:
   *  bind key primaryCommand:secondaryCommand
   *  bind key :secondaryCommand
   *  bind key :

   The primary command is executed as described above. The secondary command is
   executed if the key combination is held for a while (i.e. when a long key
   press is detected). If the **autorepeat** feature is enabled then the
   secondary command is autorepeated if it has been defined, else the primary
   command is autorepeated.

   For a list of commands, see |README.CommandReference|.

.. _Bind Command Modifiers:

One or more modifiers may be optionally appended to a command name by using a 
plus (``+``) sign as the separator. For example::

   bind key command
   bind key command+modifier1
   bind key command+modifier1+modifier2

For commands which enable/disable a feature:

*  If the modifier ``+on`` is specified then the feature is enabled.
*  If the modifier ``+off`` is specified then the feature is disabled.
*  If neither ``+on`` nor ``+off`` is specified then the state of the feature
   is toggled on/off.

For commands which move the braille window:

*  If the modifier ``+route`` is specified then, if necessary, the screen
   cursor is automatically routed so that it's always visible on the braille
   display.

For commands which move the braille window to a specific line on the screen:

*  If the modifier ``+toleft`` is specified then the braille window is also
   moved to the beginning of that line.
*  If the modifier ``+scaled`` is specified then the key group bound to the 
   command is interpreted as though it were a scroll bar. If it isn't
   specified then there's a one-to-one correspondence between keys and lines.

For commands which require an offset:

*  The modifier ``+offset``, where ``offset`` is a non-negative integer, may be
   specified. If it isn't specified then ``+0`` is assumed.

For commands which input any keyboard key (print or braille): 

*  The ``+shift`` modifier adds the shift key.
*  The ``+control`` modifier adds the control key.
*  The ``+meta`` modifier adds the left alt (or meta) key.
*  The ``+altgr`` modifier adds the right alt (or altgr) key.
*  The ``+gui`` modifier adds the gui (or windows) key.

For commands which input characters (print or braille):

*  The modifier ``+upper`` converts a lowercase character to uppercase.

For commands which input braille characters:

*  The modifiers ``+dot1`` through ``+dot8`` add those dots to the character.
*  The modifier ``+space`` adds the space bar (or "chord" key) to the
   character.

For commands which input keyboard scancodes:

*  The ``+release`` modifier means that it's a key release scancode. If it
   isn't specified then it's a key press scancode (unless, of course, the
   scancode itself indicates something else).
*  The ``+emul0`` modifier means that it's an emulation mode 0 scancode.
*  The ``+emul1`` modifier means that it's an emulation mode 1 scancode.

Examples::

   bind Key1 CSRTRK
   bind Key1+Key2 CSRTRK+off
   bind Key1+Key3 CSRTRK+on
   bind Key4 TOP
   bind Key5 TOP+route
   bind VerticalSensor GOTOLINE+toleft+scaled
   bind Key6 CONTEXT+context1

The Context Directive
---------------------

.. parsed-literal:: context *name* *title*

Use this directive to define alternate ways to interpret certain key events
and/or combinations.
Switching to another context is done via the BRLTTY command CONTEXT+name.

A context contains definitions created by any of:

*  `The Bind Directive`_
*  `The Hotkey Directive`_
*  `The Ignore Directive`_
*  `The Macro Directive`_
*  `The Map Directive`_
*  `The Run Directive`_
*  `The Superimpose Directive`_

*name*
   Which context subsequent definitions are to be created within.

*title*
   A person-readable description of the context. It may contain spaces.
   Standard capitalization conventions should be used. This operand is
   optional. If supplied when selecting a context which already has a title
   then the two must match. Special contexts already have internally-assigned
   titles.

A context is created the first time it's selected. It may be reselected any
number of times thereafter. These special contexts are predefined:

``default``
   The default context. If a definition can't be found within the current
   context then it's looked up within the default context. This only applies
   to definitions created by:

   *  `The Bind Directive`_.
   *  `The Macro Directive`_.
   *  `The Run Directive`_.

``menu``
   This context is used when within BRLTTY's Preferences Menu.

All subsequent definitions until either the next ``context`` directive or the
end of the current include level are created within the selected context. The 
initial context of the top-level key table is ``default``. The initial context
of an included key subtable is the context which was selected when it was 
included. Context changes within included key subtables don't affect the 
context of the including key table or subtable.

If a context has a title then it is persistent. When a key event causes a
persistent context to be activated, that context remains current until a
subsequent key event causes a different persistent context to be activated.

If a context doesn't have a title then it is temporary. When a key event causes
a temporary context to be activated, that context is only used to interpret the 
very next key event.

Examples::

   context menu
   context braille Braille Input
   context DESCCHAR

The Hide Directive
------------------

.. parsed-literal:: hide *state*

Use this directive to specify whether or not definitions created by:

*  `The Bind Directive`_
*  `The Hotkey Directive`_
*  `The Map Directive`_
*  `The Superimpose Directive`_

and text added by:

*  `The Note Directive`_

are to be included within the key table's help text.

*state*
   One of these keywords:

   ``on``
      They're excluded.
   ``off``
      They're included.

The specified hide state applies to all subsequent definitions and notes until 
either the next ``hide`` directive or the end of the current include level. The
initial hide state of the top-level key table is ``off``. The initial hide
state of an included key subtable is the hide state that was in effect when it
was included. Hide State changes within included key subtables don't affect the
hide state of the including key table or subtable.

Examples::

   hide on

The Hotkey Directive
--------------------

.. parsed-literal:: hotkey *key* *press* *release*

Use this directive to bind the press and release events of a specific key to
two separate BRLTTY commands. The bindings are defined within the current
context.

*key*
   The name of the key which is to be bound.

*press*
   The name of the BRLTTY command which is to be executed whenever the key is
   pressed.

*release*
   The name of the BRLTTY command which is to be executed whenever the key is
   released.

Modifiers may be appended to the command names. See
`Bind Command Modifiers`_ for details.

Specify the ``NOOP`` command if no command is to be executed. Specifying the
``NOOP`` command for both events effectively disables the key.

Examples::

   hotkey Key1 CSRVIS+off CSRVIS+on
   hotkey Key2 NOOP NOOP

The IfKey Directive
-------------------

.. parsed-literal:: ifKey *key* *directive*

Use this directive to only process one or more directives if the device has a
particular key.

*key*
   |key operand|

*directive*
   |directive operand|

Examples::

   ifKey Key1 ifkey Key2 bind Key1+Key2 HOME

The IfNotKey Directive
----------------------

.. parsed-literal:: ifNotKey *key* *directive*

Use this directive to only process one or more directives if the device doesn't
have a particular key.

*key*
   |key operand|

*directive*
   |directive operand|

Examples::

   ifNotKey Key2 bind Key1 HOME

The IfPlatform Directive
------------------------

.. parsed-literal:: ifPlatform *platform* *directive*

Use this directive to only process one or more directives if running on the
named host platform.

*platform*
   |platform operand|

*directive*
   |directive operand|

Examples::

   ifPlatform android include android.kti

The IfNotPlatform Directive
---------------------------

.. parsed-literal:: ifNotPlatform *platform* *directive*

Use this directive to only process one or more directives if not running on
the named host platform.

*platform*
   |platform operand|

*directive*
   |directive operand|

Examples::

   ifNotPlatform grub include advanced.kti

The Ignore Directive
--------------------

.. parsed-literal:: ignore *key*

Use this directive to ignore a specific key while within the current context.

*key*
   The name of the key which is to be ignored.

Examples::

   ignore Key1

The Isolated Directive
----------------------

.. parsed-literal:: isolated

Use this directive to isolate the current context.
If a key binding can't be found within an isolated context
then it won't be looked up within the default context.

Examples::

   isolated

The Macro Directive
-------------------

.. parsed-literal:: macro *keys* *command* ...

Use this directive to bind a sequence of BRLTY commands to a key combination.

*keys*
   The key combination being defined.

*command* ...
   The BRLTTY commands that are to be executed.

Examples::

   macro Key1+Key2 TOP LNEND

The Map Directive
-----------------

.. parsed-literal:: map *key* *function*

Use this directive to map a key to a braille keyboard function. The mapping is
defined within the current context.

*key*
   The name of the key that is to be mapped. More than one key may be mapped to
   the same braille keyboard function.

.. _The Map Function Operand:

*function*
   The name of the braille keyboard function. It may be one of the following
   keywords:

   ``DOT1``
      The upper-left standard braille dot key.
   ``DOT2``
      The middle-left standard braille dot key.
   ``DOT3``
      The lower-left standard braille dot key.
   ``DOT4``
      The upper-right standard braille dot key.
   ``DOT5``
      The middle-right standard braille dot key.
   ``DOT6``
      The lower-right standard braille dot key.
   ``DOT7``
      The lower-left computer braille dot key.
   ``DOT8``
      The lower-right computer braille dot key.
   ``SPACE``
      The space bar.
   ``SHIFT``
      The shift key.
   ``UPPER``
      If a lowercase letter is being entered then translate it to its
      uppercase equivalent.
   ``CONTROL``
      The control key.
   ``META``
      The left alt (or meta) key.
   ``ALTGR``
      The right alt (or altgr) key.
   ``GUI``
      The gui (or windows) key.

If a key combination consists only of keys which have been mapped to braille 
keyboard functions, and if those functions, when combined, form a valid braille 
keyboard command, then that command is executed as soon as any of the keys is 
released. A valid braille keyboard command must include either any combination 
of dot keys or the space bar (but not both). If at least one dot key is 
included then the braille keyboard functions specified by
`The Superimpose Directive`_ within the same context are also implicitly
included.

Examples::

   map Key1 DOT1

The Note Directive
------------------

.. parsed-literal:: note *text*

Use this directive to add a person-readable explanation to the key table's help
text. Notes are commonly used, for example, to describe the placement, sizes,
and shapes of the keys on the device.

*text*
   The explanation that is to be added. It may contain spaces, and should be
   grammatically correct.

Each note specifies exactly one line of explanatory text. Leading space is 
ignored so indentation cannot be specified.

There's no limit to the number of notes that may be added. All of them are 
gathered together and presented in a single block at the start of the key 
table's help text.

*  A note that doesn't have a special prefix begins a new outer bulleted list
   element.

*  A note that is prefixed with an asterisk (``*``) continues the current outer
   bulleted list element.

*  A note that is prefixed with a plus (``+``) sign is an inner bulletged list
   element.

Examples::

   note This is the first outer list element.
   note This is the second outer list element.
   note * Continue the second outer list element.
   note + The first element of an inner list.
   note + The second element of an inner list.
   note * The third line of the second outer list element.

The above example would be rendered as:

*  This is the first outer list element.

*  This is the second outer list element.
   Continue the second outer list element.

   +  The first element of an inner list.

   +  The second element of an inner list.

   The third line of the second outer list element.

The Run Directive
-----------------

.. parsed-literal:: run *keys* *name* [*argument* ...]

Use this directive to bind a host command to a key combination.

*keys*
   The key combination being defined.

<name*
   The name of the host command. It may also be the path.

*argument* ...
   The arguments to be passed to the host command.

Examples::

   run Key1+Key2 pkill --exact brltty

The Superimpose Directive
-------------------------

.. parsed-literal:: superimpose *function*

Use this directive to implicitly include a braille keyboard function whenever a
braille keyboard command consisting of at least one dot is executed. Only
implicit inclusions defined within the current context are performed. Any
number of these directives may be specified.

*function*
   The name of the braille keyboard function that is to be implicitly included.
   See `The Map Function Operand`_ for details.

Examples::

   superimpose DOT7

The Title Directive
-------------------

.. parsed-literal:: title <text>

Use this directive to specify a person-readable, one-line summary of the key
table's purpose.

*text*
   A brief summary of what the key table is used for. It may contain spaces,
   and standard capitalization conventions should be used.

The title of the key table may be specified only once.

Examples::

   title Bindings for Keypad-based Navigation

.. include:: nesting-directives.rst
.. include:: variable-directives.rst
.. include:: condition-directives.rst

Keyboard Table List
===================

.. csv-table::
   :header-rows: 1
   :file: keyboard-table.csv

Braille Driver List
===================

.. csv-table::
   :header-rows: 1
   :file: braille-driver.csv