Documents/README.KeyTables - brltty - Git at Google

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