From AlphaWiki

Commands: The [binding] command

This file documents the new [binding] command introduced in version 8.2a1d1 of AlphaX.

• Introduction
• Synopsis
• Specifying a key combo
• Binding subcommands
  • The [create] subcommand
  • The [delete] subcommand
  • The [info] subcommand
  • The [list] subcommand
• Character codes vs. virtual keycodes
• Symbolic key names
• Composite bindings
• Glyph codes
• Examples

Introduction

The [binding] command lets you create and manipulate key bindings in Alpha. The [binding] command is a proposed replacement for the old [bind] (or [Bind]) command.

Bindings are associated with Tcl procs (or Tcl code snippets): this is a characteristic they share with menu items which can also be associated with Tcl procs using the new [menuItem] command (see the MenuItemCommand page on this wiki). The purpose of this new approach is to resolve the conflictual situations caused by key combinations defined directly by menu definitions or by an explicit call to the old [Bind] command.

A key binding is defined by the following attributes:

• a code which identifies the key. This key can be designated either by a character code (i-e the macRoman ASCII code of a letter, a digit, a symbol, etc.) or by a virtual keycode designating a physical key on the keyboard.
• a numeric value specifying which modifier keys are pressed together with the key
• a boolean value telling if 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.

A key binding is uniquely determined by these parameters. The code and the modifiers are required parameters. The other parameters are optional. By default, a code is interpreted as a character code. If the tag is empty or unspecified, the binding is global.

Synopsis

The formal syntax of the [binding] command is:

binding subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, various options can be additionnally specified.

Specifying a key combo

Many subcommands of the [binding] command take a command key argument of the form

 
     {modifiers key}

This argument describes a key combination. It is a two elements Tcl list:

• the first item of this list (modifiers) corresponds to the modifier keys pressed in this combination
• the second item (key) is the main key which will be bound to some proc by the [binding create] command

The modifiers are specified as a string made of some of the following letters:

The modifier string must be an empty string if no modifiers are associated with the key combo.

There are three ways of specifying the main key:

• as a numeric value representing the code of the character in the MacRoman ASCII encoding (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 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 ASCII code 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 main non-letter keys of the keyboard. See the table in the Symbolic key names section below.

Note that character code bindings are case insensitive. So Command-a and Command-A are identical. If you really want the Shift key to be part of the binding, you must specify the letter s in the modifier string. For instance, the argument {cs 65} would correspond to the Command-Shift-A combination.

Binding subcommands

The [create] subcommand

This subcommand creates a new binding or redefines an already existing binding. It accepts a few options. The complete syntax is:

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

The command has two required arguments:

• the {modifiers key} argument represents the key combination as explained in the previous section
• the proc argument is a Tcl proc or a Tcl code snippet.

Here are the currently defined options:

• the -creator option lets you specify a four-character type (similar to Mac OS creator types) to identify the package which created the binding. This can be useful for packages which want to keep track of their bindings (see the [binding list] command below).
• the -glyph option lets you specify a particular glyph for a virtual keycode binding. By default Alpha knows the glyph which should be associated with a particular virtual keycode and picks it automatically. This option is useful only if you want to specify a substitution glyph, for instance a dashed arrow instead of a plain arrow.
• the -help option lets you specify a useful description of the binding
• 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 tag associated with the key binding. If it is not specified, the key binding will be global.

The [delete] subcommand

This subcommand lets you delete a key binding. The syntax is:

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

The possible options are -tag and -prefix which have the same meaning as with the [binding create] command.

The [info] subcommand

This subcommand lets you get information about an existing key binding. The syntax is:

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

The third argument indicates which info is desired. It can be one of the following keywords:

• command to get the Tcl code associated with the binding
• help to get the description of the binding. This is the string which was optionnally specified with the -help switch when the binding was created with the [binding create] command.

The possible options are -tag and -prefix which have the same meaning as with the [binding create] command. If the binding does not exist, the command raises an error.

The [list] subcommand

This subcommand returns a list of the currently existing key bindings. The syntax is:

 
     binding list ?option value...?

One can specify some options to restrict the returned list to only the bindings satisfying these options. The available options are:

-command, -creator, -glyph, -key, -modifiers, -prefix, -tag, -virtual

This allows you to specify key codes or modifiers separately. The value of the -key option can be either a numeric value or a letter enclosed between single quotes. The value of the -modifiers option is a string made of the c, o, s, z, v letters (see the section Specifying a key combo above). The -virtual option can be used to list only character code bindings (if the value is 0) or only virtual keycode bindings (if the value is 1).

Each element of the list returned by the [binding list] command is a sublist describing a particular key binding. The sublist contains 6 or 8 elements:

1. the modifier string (an empty string if there are no modifier specifications)
2. the key code (decimal value)
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)

The last two elements are present only if the binding is composite and has been defined with a -prefix option. For instance, if a binding is created like this:

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

the returned sublist will be

 
     {cv 112 Tcl abcd Tcl::doSomethingProc ""}

This command can be used to find if there exists some key bindings pointing to a particular Tcl proc. For instance:

 
     binding list -command Tcl::doSomethingProc

The command can also be useful with the -creator option to identify certain groups of bindings. For instance, a package might want to keep track of the bindings it defines: if the bindings were declared with a -creator option like this

 
     binding create -creator "ABCD" {modifiers key}

the package can expose them later via:

 
     binding list -creator "ABCD"

See examples in the Examples section below.

Note that character code bindings corresponding to a letter are case insensitive: they are stored internally using the code of the lowercase letter even if the definition was invoked using an uppercase letter. On output, all the character code bindings corresponding to a printable character are written with this character (uppercase form between single quotes); the other bindings (including virtual key bindings) are represented by the decimal value of the key. So, if a binding has been defined for 'a', the value returned by [binding list] will be 'A'.

Character codes vs. virtual keycodes

A keyboard equivalent may be either a character code or a virtual keycode. Only one is used by the application at any given time: a virtual keycode binding always has precedence over a character code binding.

Here is a list of the main virtual keycodes:

You can obtain the value of any virtual keycode using the Key Codes... command found is the Ascii Etc submenu of the Tools menu. Note that zero is a valid virtual keycode.

Symbolic key names

Here is the list of the predefined symbolic names which can be used to specify a virtual key binding. These values are case insensitive, so one can use HOME, home, Home indifferently.

The following table gives the symbolic names, the corresponding key codes and the values of the glyph automatically associated by default by Alpha (unless the -glyph option was specified):

In the case of key pad bindings, there is no glyph provided by the system. Alpha uses the character glyph instead.

Composite bindings

The -prefix option can be used in the binding create command to define composite bindings. Its value is a two-elements Tcl list of the form {modifiers key} with the same meaning as for the main key argument.

For instance, in order to define the binding ctrl-opt-B Z (which means, first press ctrl-opt-B, then press Z), the instruction is:

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

The ctrl-opt-B Z binding would trigger the Tcl proc designated by someProc.

For this mechanism to work, the simple ctrl-opt-B binding must also be defined and must be attached to the [prefixChar] core command. For instance:

 
     binding create {oz 'B'} prefixChar

The [prefixChar] core command takes care of waiting for the second part of the binding to be entered (here the letter Z) and then to execute the code designated by someProc.

Glyph codes

Here is a table of the numerical constants which can be used with the -glyph option. Glyphs are used with virtual keycode bindings (not with character code bindings) to represent keys which are not associated with a single letter or symbol on the keyboard. Most of these values have already been listed in the table of the Symbolic key names section above.

Virtual keycode bindings attached to a key corresponding to a simple letter or symbol are represented by this letter or symbol.

You would not normally have to invoke this option unless you wanted to modify the default glyph automatically provided by Alpha. For instance, in some circumstances, you might want to replace the Left Arrowglyph by the Left Arrow Dashed glyph.

Examples

Here are a few basic examples which can be executed one by one in the Tcl shell in AlphaX:

 
     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 "opt-cmd-A combo" {co 65} $cmd1
     binding create -help "ctrl-cmd-A combo" {cz 65} $cmd2
     binding create -help "ctrl-opt-cmd-A combo" {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
     binding create {cozv F5} $cmd8
     binding create -tag Tcl {cozv F5} $cmd9
     binding create -tag Ruby {cozv 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 act1
     binding list -command $cmd1

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

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

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

(add your comments here...)