Key Tables

Contents

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.

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

The Bind Directive

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 The Command Reference.

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

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:

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:

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

hide state

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

and text added by:

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

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

ifKey key directive

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

key
The name of the key whose availability is to be tested.
directive
The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

ifKey Key1 ifkey Key2 bind Key1+Key2 HOME

The IfNotKey Directive

ifNotKey key directive

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

key
The name of the key whose availability is to be tested.
directive
The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

ifNotKey Key2 bind Key1 HOME

The IfPlatform Directive

ifPlatform platform directive

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

platform
The name of a host platform. The following platform names are recognized: android, apple, cygwin, dos, grub, linux, mingw32, mingw64, openbsd, sun, windows.
directive
The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

ifPlatform android include android.kti

The IfNotPlatform Directive

ifNotPlatform platform directive

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

platform
The name of a host platform. The following platform names are recognized: android, apple, cygwin, dos, grub, linux, mingw32, mingw64, openbsd, sun, windows.
directive
The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

ifNotPlatform grub include advanced.kti

The Ignore Directive

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

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

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

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

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

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

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

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

The Include Directive

include file # comment

Use this directive to include the content of another file. It is recursive, which means that an included file can itself include yet another file. Care must be taken to ensure that an "include loop" is not created.

file
The file to be included. It may be either a relative or an absolute path. If relative, it is anchored at the directory containing the including file.

The Assign Directive

assign variable value

Use this directive to create or update a variable associated with the current nesting level (see The BeginVariables Directive) of the current include level (see The Include Directive). The variable is visible to the current and to lower include levels, but not to higher include levels.

variable
The name of the variable. If the variable doesn't already exist at the current include level then it is created.
value
The value that is to be assigned to the variable. If it's not supplied then a zero-length (null) value is assigned.

Examples:

assign nullValue
assign shortValue word
assign longValue a\svalue\swith\sspaces
assign IndirectValue \{variableName}

The AssignDefault Directive

assignDefault variable value

Use this directive to assign a default value to a variable associated with the current nesting level (see The BeginVariables Directive) of the current include level (see The Include Directive). It's functionally equivalent to:

ifNotVar variable assign variable value

See The Assign Directive and The IfNotVar Directive for more details.

variable
The name of the variable. If the variable doesn't already exist at the current include level then it is created. If it does already exist then it is not modified.
value
The value that is to be assigned to the variable if it doesn't already exist. If it's not supplied then a zero-length (null) value is assigned.

Examples:

assignDefault format plain\stext

The IfVar Directive

ifVar variable directive

Use this directive to only process one or more directives if a variable exists.

variable
The name of the variable whose existence is to be tested.
directive
The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

ifVar var1 ifVar var2 assign concatenation \{var1}\{var2}

The IfNotVar Directive

ifNotVar variable directive

Use this directive to only process one or more directives if a variable doesn't exist.

variable
The name of the variable whose existence is to be tested.
directive
The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

ifNotVar var1 assign var1 default\svalue

The BeginVariables Directive

beginVariables

Use this directive to open a new variable nesting level. The Assign Directive) will define variables at this new nesting level, and will hide variables with the same names in any previous nesting level. These variables will remain defined until The EndVariables Directive that is at the same variable nesting level.

Examples:

assign x 1
# \{x} evaluates to 1
beginVariables
# \{x} still evaluates to 1
assign x 2
# \{x} now evaluates to 2
endVariables
# \{x} evaluates to 1 again

The EndVariables Directive

endVariables

Use this directive to close the current variable nesting level. See The BeginVariables Directive for details.

The ListVariables Directive

listVariables

Use this directive to list all of the currently defined variables. It can be helpful when debugging.

The EndIf Directive

endIf

Use this directive to terminate the current conditional nesting level.

Examples:

ifVar x
   These lines will be processed if a variable named x exists.
endIf

The Else Directive

else

Use this directive to negate the test associated with the current conditional nesting level.

Examples:

assign x some\svalue
ifVar x
   These lines will be processed.
else
   These lines won't be processed.
endIf

Keyboard Table List

name description
off no keyboard table
braille bindings for braille keyboards
desktop bindings for full keyboards
keypad bindings for keypad-based navigation
laptop bindings for keyboards without a keypad
sun_type6 bindings for Sun Type 6 keyboards

Braille Driver List

code name aliases others usage
auto autodetect      
al Alva     ABT(3nn), Delphi(4nn), Satellite(5nn), Braille System 40, Braille Controller 640/680, Easy Link 12
at Albatross     46/80
ba BrlAPI     BrlAPI client
bc BrailComm     III
bd Braudi     Pro
bl BrailleLite     18/40/M20/M40
bm Baum   Refreshabraille, Orbit, NLS eReader Zoomax, NBP B2G BrailleConnect 12/24/32/40/64/80, Brailliant 24/32/40/64/80, Conny 12, DM80 Plus, EcoVario 24/32/40/64/80, Inka, NLS eReader Zoomax, Orbit Reader 20/40, PocketVario 24, Pronto! V3 18/40, Pronto! V4 18/40, RBT 40/80, Refreshabraille 18, SuperVario 32/40/64/80, Vario 40/80, VarioConnect 12/24/32/40/64/80, VarioPro 40/64/80, VarioUltra 20/32/40
bn BrailleNote     18/32, Apex
cb CombiBraille     25/45/85
ce Cebra     20/40/60/80/100/120/140
cn Canute     360 (40x9)
dp DotPad      
ec EcoBraille     20/40/80
eu EuroBraille     AzerBraille, Clio, Esys, Iris, NoteBraille, Scriba
fa FrankAudiodata     B2K84
fs FreedomScientific VFO, Vispero   Focus 1 44/70/84, Focus 2 40/80, Focus 3+ (Blue) 14/40/80, PAC Mate 20/40
hd Hedo     ProfiLine, MobilLine
hm HIMS     Braille Sense, SyncBraille, Braille Edge, Smart Beetle, QBrailleXL
ht HandyTech HelpTech   Modular 20/40/80, Modular Evolution 64/88, Modular Connect 88, Active Braille, Active Braille S, Active Star 40, Actilino, Activator, Basic Braille 16/20/32/40/48/64/80, Braillino, Braille Wave, Easy Braille, Braille Star 40/80, Connect Braille 40, Bookworm
hw HumanWare   APH Chameleon, APH Mantis, NLS eReader Brailliant BI 14/32/40, Brailliant BI 20X/40X, Brailliant B 80, BrailleNote Touch, BrailleOne, APH Chameleon 20, APH Mantis Q40, NLS eReader
ic Inceptor Innovision   BrailleMe (20)
ir Iris     KB
lb Libbraille     Libbraille
lt LogText     32
mb MultiBraille     MB125CR, MB145CR, MB185CR
md MDV     MB208, MB248, MB408L, MB408L+, Lilli Blu
mm BrailleMemo     Pocket (16), Smart (16), 32, 40
mn MiniBraille     20
mt Metec     BD-40
np NinePoint     8
pg Pegasus     20/27/40/80
pm Papenmeier     Compact 486, Compact/Tiny, IB 80 CR Soft, 2D Lite (plus), 2D Screen Soft, EL 80, EL 2D 40/66/80, EL 40/66/70/80 S, EL 40/60/80 C, EL 2D 80 S, EL 40 P, EL 80 II, Elba 20/32, Trio 40/Elba20/Elba32, Live 20/40
sk Seika     3/4/5 (40), 80, Mini (16)
tn TechniBraille     Manager 40
ts TSI     Navigator 20/40/80, PowerBraille 40/65/80
vd VideoBraille     40
vo Voyager   Braille Pen, Easy Link 44/70, Part232 (serial adapter), BraillePen/EasyLink
vs VisioBraille     20/40