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

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

made of the c, o, s, z, v letters (see the section Specifying a key combo above). The -virtual option can be used

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:

made of the c, o, s, z, v letters (see the section ''Specifying a key combo above). The -virtual'' option can be used

a sublist describing a particular key binding. The sublist contains 6 or 8

1. the creator (an empty string if no creator was specified)

1. the help string attached to the binding

This file documents the new [binding] command introduced in version 8.2a1d1 of AlphaX. This is an experimental command proposed as a part of the bindings reform. It is open to discussion.

• The [info] subcommand

Bindings are associated with Tcl procs (or Tcl code snippets): this is a

Tcl procs using the new [menuItem] command (see the

• the second item (key) is the main key which will be bound to some proc by the [binding create] command

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

• the proc argument is a Tcl proc or a Tcl code snippet.

• 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 -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 [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 bindings satisfying these options. The available options are:

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

a sublist describing a particular key binding. The sublist contains 5 or 7 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 Tcl script attached to the binding
5. the creator (an empty string if no creator was specified)
6. the modifier string of the prefix (empty if there are no modifier specifications)
7. the key code of the prefix (decimal value)

The last two elements are present only if the binding is composite and

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 Tcl::doSomethingProc abcd}

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"

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

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

     binding create {oz 'B'} prefixChar

the code designated by someProc.

     proc bindingActionProc {idx}  {
         alertnote "Command $idx triggered"
     }
     # Define a few commands

         set cmd$i "test::bindingActionProc $i"

     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

     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

     binding create {cozv F5} $cmd8
     binding create -tag Tcl {cozv F5} $cmd9
     binding create -tag Ruby {cozv F5} $cmd10

     binding create {v Help} $cmd11

     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

the tag (an empty string if the binding is global). Finally, there

will be two additional modifiers and key elements if the binding is composite and

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

• Glyph codes
• Examples

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

(:title The [binding] command:)

This file documents the new [binding] command introduced in version 8.1 of AlphaX. This is an experimental command proposed as a part of the bindings reform. It is open to discussion.

• Specifying a key combo

• Character codes vs. virtual keycodes
• Symbolic key names
• Composite bindings
• Examples

the old [Bind] command.

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

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 action 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} action

The command has two required arguments:

• the {modifiers key} argument represents the key combination as explained in the previous section
• the action argument is a token designating an action. This token is obtained when the action is defined using the [action create] command.

Here are the currently defined options:

• 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 -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 -prefix option lets you specify a prefix combination. It is used to build composite bindings à la emacs. See the Composite bindings section below.

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.

particular configuration of the parameters. If the binding exists, the

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

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

     binding list ?option value...?

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

-action, -glyph, -key, -modifiers, -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. 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 4 or 5 elements: the modifiers string (an empty string if there are no modifier specifications), the key code (decimal value), the token of the action, and the tag (an empty string if the binding is global). Additionnally, there will be a {modifiers key} element if the binding is composite and has been defined with a -prefix option. For instance, if a binding were created like this:

     binding create -tag Tcl {cv 112} action1234

the returned sublist would be

 
     {cv 112 action1234 Tcl}

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

 
     binding list -action action1234

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. So, if a binding has been defined for 'A' (ASCII 65), the value returned by [binding list] will be 97 which is the ASCII code for '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'} actionToken

The ctrl-opt-B Z binding would trigger the action designated by actionToken.

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:

 
     set theAction [action create -script prefixChar]
     binding create {oz 'B'} $theAction

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 action designated by actionToken.

Examples

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

 
     # Define a few actions
     for {set i 1} {$i < 12} {incr i} {
         set act$i [action create -script {alertnote "This is act$i"} -help "help string about act$i"]
     }

     # Bindings to letter A (resp opt-cmd-A, ctrl-cmd-A, and ctrl-opt-cmd-A)
     binding create {co 65} $act1
     binding create {cz 65} $act2
     binding create {coz 65} $act3

     # Bindings to letter L
     binding create {co 76} $act4
     binding create -tag Tcl {co 76} $act5
     binding create -tag Python {co 76} $act6
     binding create -tag Ruby {co 76} $act7

     # A virtual keycode binding attached to opt-F5
     binding create {cozv F5} $act8
     binding create -tag Tcl {cozv F5} $act9
     binding create -tag Ruby {cozv F5} $act10

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

     # 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 -action $act1

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

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

(add your comments here...)

This file documents the new [binding] command introduced in version 8.1 of AlphaX. This is an experimental command proposed as a part of the bindings reform. It is open to discussion.

• Introduction
• Synopsis
  • Parameter options
• Binding subcommands
  • The [create] subcommand
  • The [delete] subcommand
  • The [find] subcommand
  • The [list] subcommand
• 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 now associated with actions defined with the [action] command (see the ActionCommand page on this wiki): this is a characteristic they share with menu items which can also be associated with actions 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 [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 in a particular mode.

A key binding is uniquely determined by these parameters: the code is a required parameter, and by default, it is interpreted as a character code. The other parameters are optional. If the tag is empty or unspecified, the binding is global. If the modifiers are not specified, it is assumed that it is the Command key.

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.

Parameter options

The optional parameters described above are specified in the various subcommands of the [binding] command by the following switches:

• the -modifiers option lets you specify the modifier keys associated with a key binding. The value of this option is an additive value made of base-2 constants: see the Modifier key constants section on the wiki. The default value is 0.
• 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 -virtual option tells whether a keyboard shortcut is to be interpreted as a character code or a virtual key code (the values for this option are 0 and 1 respectively). The default value is 0.

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...? commandKey action

The [binding create] command has two required arguments:

• the commandKey argument is an integer value representing the key code
• the action argument is a token designating an action. This token was returned when the action was defined using the [action create] command.

The options have been described in the preceding section.

The [delete] subcommand

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

 
     binding delete ?option value...? commandKey

The options are the same as with the [binding create] command.

The [find] subcommand

This subcommand lets you find if a key binding already exists for a particular configuartion of the parameters. If the binding exists, the command returns the token of the action it is associated with, otherwise it raises an error. The syntax is:

 
    binding find ?option value...? commandKey

The options are the same as with the [binding create] command.

The [list] subcommand

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

 
 	binding list ?commandKey?

If the commandKey argument is specified only those bindings involving this key code will be returned. Each element of the list returned by the [binding list] command is a sublist describing a particular key binding. The sublist contains 4 or 5 elements: the key code, the modifiers constant, a boolean value telling if it is a virtual key, the token of the action, and the tag (if any).

Examples

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

 
     # Define a few actions
     for {set i 1} {$i < 10} {incr i} {
     	set act$i [action create -script {alertnote "This is act$i"} -help "help string about act$i"]
     }

     # Bindings to letter A (resp opt-cmd-A, ctrl-cmd-A, and ctrl-opt-cmd-A)
     binding create -modifiers 2 65 $act1
     binding create -modifiers 4 65 $act2
     binding create -modifiers 6 65 $act3

     # Bindings to letter L
     binding create -modifiers 2 76 $act4
     binding create -modifiers 2 -tag Tcl 76 $act5
     binding create -modifiers 2 -tag Python 76 $act6
     binding create -modifiers 2 -tag Ruby 76 $act7

     # A virtual keycode binding attached to opt-F5 (the keycode of F5 is 96)
     binding create -virtual 1 -modifiers 10 96 $act8

     # Get a list of all the bindings
     binding list

     # Get a list of all the bindings associated with letter L
     binding list 76

     # Find the action associated with the opt-cmd-L combination in Ruby mode
     binding find -modifiers 2 -tag Ruby 76

     # Delete the previous combination
     binding delete -modifiers 2 -tag Ruby 76

(add your comments here...)