• Introduction
• Synopsis
  • The [allowed] subcommand
  • The [create] subcommand
  • The [delete] subcommand
  • The [info] subcommand
  • The [list] subcommand
• Specifying a key combo
• Character codes vs. virtual keycodes
  • Symbolic key names
• Composite bindings
• Bindings with an infix
• Examples

Introduction

• a code which identifies the key. This key can designate either a character code (i-e the code-point of a character) or a virtual keycode corresponding to a physical key on the keyboard.
• a string specifying which modifier keys are pressed together with the key;
• a boolean value telling whether the code is to be interpreted as a character code or a virtual keycode;
• an optional tag which is used to specify that this key binding should be executed only if a particular mode is in force.

Synopsis

The [allowed] subcommand

    binding allowed
    binding allowed modifiers
    binding allowed all

• any combination of the letters c, o, s, z, e ;
• an empty string if no bindings are allowed.

The [create] subcommand

    binding create ?option value...? {modifiers key} proc

• the {modifiers key} argument represents the key combination as explained in the Specifying a key combo section.
• the proc argument is a Tcl proc or a block of Tcl instructions.

• the -context option lets you specify a required context, that is to say a condition to meet for the binding to be active. When the key combo for this binding is pressed, the binding is executed only if the application is in the given context. The value for this option is an integer. The available context values are described in the table below.
• the -creator option lets you specify a four-character type (similar to Mac OS creator types) to identify a collection of bindings, for instance all the bindings created by a package. This can be useful for packages to keep track of their bindings (see the [binding list] command).
• the -help option lets you specify a description string for the binding. It is useful only for information purposes.
• the -prefix option lets you specify a prefix combination. It is used to build composite bindings √† la emacs. See the Composite bindings section below.
• the -tag option lets you specify the name of a mode associated with the key binding. This makes the binding mode-specific instead of global. If it is not specified, the key binding will be global.

The [delete] subcommand

    binding delete ?option value...? {modifiers key}

The [info] subcommand

   binding info (command|context|help) ?option value...? {modifiers key}

• command to return the Tcl script associated with the binding.
• context to return the context required by the binding. See the -context option and the meaning of the possible values in this table.
• help to return the description string of the binding. This is the string which was optionnally specified with the -help option when the binding was created with the [binding create] command.

The [list] subcommand

    binding list ?option value...?

1. the modifier string (an empty string if there are no modifier specifications)
2. the key code (decimal value or letter)
3. the tag (an empty string if the binding is global)
4. the creator (an empty string if no creator was specified)
5. the Tcl script attached to the binding
6. the help string attached to the binding
7. the modifier string of the prefix (empty if there are no modifier specifications)
8. the key code of the prefix (decimal value)

    binding create -creator "abcd" -tag Tcl {cv 112} Tcl::doSomethingProc

    cv 112 Tcl abcd Tcl::doSomethingProc ""

    binding list -command Tcl::doSomethingProc

    binding create -creator "ABCD" {modifiers key} proc

    binding list -creator "ABCD"

Specifying a key combo

{modifiers key}

• the first item of this list (modifiers) corresponds to the modifier keys pressed in the combination;
• the second item (key) is the key.

• as a numeric value representing the code-point of the character (if it is a character code binding) or the code of the key (if it is a virtual keycode binding). The value can be expressed in hexadecimal, octal or decimal notation. For instance the character A (code 65 in the ASCII encoding) can be represented numerically by one of the following values: 65 in decimal, 0101 in octal or 0x41 in hexadecimal.
• in the case of a character code binding, instead of specifying the code-point of the character, one can specify the character itself between single quotes. For instance, {c 'A'} is the same as {c 65}.
• in the case of a virtual keycode binding, instead of specifying the code of the key, one can use a symbolic name. Some symbolic names (like Home, Up, Right) have been defined to designate the principal non-letter keys of the keyboard. See the table in the Symbolic key names section below.

Character codes vs. virtual keycodes

Symbolic key names

Composite bindings

    binding create -prefix {oz 'B'} {"" 'Z'} someProc

    binding create {oz 'B'} prefixBinding

Bindings with an infix

    binding create {z 'A'} { prefixBinding -infix {(\d+|r)} }
    binding create -prefix {z 'A'} {"" 'B'} someProc

Examples

proc bindingActionProc {idx}  {
	alertnote "Command $idx triggered"
}
# Define a few commands
for {set i 1} {$i < 12} {incr i} {
	set cmd$i "test::bindingActionProc $i"
}

# Bindings to letter A (resp opt-cmd-A, ctrl-cmd-A, and ctrl-opt-cmd-A)
binding create -help "do something" {co 65} $cmd1
binding create -help "perform something" {cz 65} $cmd2
binding create -help "something else" {coz 65} $cmd3

# Bindings to letter L
binding create {co 76} $cmd4
binding create -tag Tcl {co 76} $cmd5
binding create -tag Python {co 76} $cmd6
binding create -tag Ruby {co 76} $cmd7

# A virtual keycode binding attached to opt-F5.
# Note that the v modifier could be omitted here.
binding create {ov F5} $cmd8
binding create -tag Tcl {ov F5} $cmd9
binding create -tag Ruby {ov F5} $cmd10

# The Help key
binding create {v Help} $cmd11

# Get a list of all the bindings
binding list

# Get a list of all the bindings associated with letter L
binding list -key 76
# Get a list of all the bindings using opt-cmd
binding list -modifiers "co"
# Get a list of all the bindings defined in Ruby mode
binding list -tag Ruby
# Get a list of all the opt-cmd bindings in Ruby mode
binding list -modifiers "co" -tag Ruby
# Get a list of all the bindings attached to the action contained in 
# the cmd1 variable
binding list -command $cmd1

# Find the command associated with the opt-cmd-L combo in Ruby mode
binding info command -tag Ruby {co 'L'}

# Get the help string associated with a binding
binding info help {co 65}

   # Delete the previous binding
binding delete -tag Ruby {co 76}