From AlphaWiki

Features: Bindings Quick Start

The purpose of this page is to provide a quick start document about the new mechanism of bindings and menu shortcut proposed in version 8.2a1d2 or greater of AlphaX. This is an experimental mechanism. It is open to discussion and available only in the 8.2a1d2 or greater development releases, as of this writing.

• Introduction
• Simple binding
• Composite binding
• Counted composite binding
• Disabling menu item bindings

Introduction

Keyboard shortcuts are handled in AlphaX via the concept of binding. A binding is an abstraction for the association of a key combination with some action to execute:

• key combinations can involve modifier keys (the shift, control, option, command keys). They can also be simple or composite: a composite keyboard shortcut is a sequence of two (and sometimes more) key presses, with or without modifer keys.
• the actions to execute are defined as Tcl procs or Tcl code snippets. They are executed by the Tcl interpreter.

The creation and manipulation of bindings is handled, in AlphaTcl scripts, by the [binding] command.

Menu items can also be associated with some action. Typically a menu item command is invoked when the menu item is selected with the mouse in a menu. But menu items often propose a keyboard equivalent. The keyboard equivalents must also be defined using the [binding] command. The fact that a key equivalent is displayed as a reminder in the menus is just a convenience. To keep things consistent and simple, AlphaX takes care of displaying the keyboard equivalents: the developer of Alpha packages does not have to worry about this. To have a keyboard equivalent drawn for a particular menu item, two conditions are required:

• a command must be attached to the menu item
• a binding must exist with exactly the same command

AlphaX automatically detects when these conditions are met and displays the key combination defined by the binding appropriately.

Simple binding

The syntax of the [binding] command is explained in details on the Binding Command page of this wiki. Here is a simple example which binds the Cmd-N combination to the [new] Tcl proc:

 
     binding create {c 'N'} "new"

A menu item can also be defined to trigger the [new] Tcl proc. This is done with the [menuItem set] command:

 
     menuItem set $menu $index -command "new"

where $menu represents the token of the menu and $index the index of the menu item. See the MenuItem Command page on this wiki. Once the command is attached to the menu item, AlphaX automatically displays the Cmd-N combination in the menu.

Composite binding

A composite binding requires a prefix combination. This prefix combination is bound to the [prefixChar] command which is a special command defined by Alpha. When it is invoked, Alpha expects a second combination to be entered and executes it if it is bound to some action. For instance, to create a ctrl-A B binding (which means press Control-A followed by B), one needs two instructions:

 
     binding create {z 'A'} prefixChar
     binding create -prefix {z 'A'} {"" 'B'} someTclProc

AlphaX is also able to display a composite binding in its menus: it suffices that a menu item be attached to the same Tcl proc (someTclProc in the example above).

Counted composite binding

A counted composite binding requires a prefix and a number to be entered before the binding like, for instance, ctrl-A 5 cmd-B. This is useful if the action triggered by cmd-B expects a number. The Embrace package defines this kind of commands. Defining a counted composite binding is very similar to the case of ordinary composite bindings: the only difference is that the prefix must be bound to the [numPrefixChar] command instead of the [prefixChar] command. See the NumPrefixChar Command? page on this wiki for a detailed explanation.

Disabling menu item bindings

There are two ways of disabling the automatic lookup of menu item equivalents when a menu is opened:

• for an entire menu with the -keyMatching option, by setting its value to 0 via the [menuRef set] command
• for a particular menu item with the -showKey option, by setting its value to 0 via the [menuItem set] command

Note that this affects the drawing of the keyboard equivalent but does not suppress the binding itself: the combination will still be executed when the user enters it via the keyboard. The only way to suppress a keyboard shortcut is to invoke the [binding delete] command.

(add your comments here...)