the User Defined Menu Shortcuts page on this wiki.

(:title Alpha Menu Shortcuts Support:)

• The user shortcuts API
• The menu shortcuts hook
• Partial menu lists

(:title Alpha Menu Shortcuts SUpport:)

the Alpha User Shortcuts page on this wiki.

(:title Alpha Menu Shortcuts Support:) This page gives information about user menu shortcuts support in the AlphaTcl packages. The information below is intended for developers who write a new menu for Alpha and want to offer the possibility of modifying the keyboard shortcuts associated with the items of this menu or its submenus. Users who just want to learn about how to set a menu shortcut should read the Alpha User Shortcuts? page on this wiki. Starting with version 8.2a1d5, AlphaX provides a per-package interface to let users assign new shortcuts to menu items. Each package can decide which of its menus or submenus are thus configureable, it can install its own interface or rely on another package's interface, it can restrict the list of configureable items. All these possibilities are detailed in the following sections.

The user shortcuts API

Installing support for configureable menu item shortcuts is very simple. It involves two tasks:

• the package must provide an item to expose this service in one of its menus or submenus. The item could be named "Menu Shortcuts", or "Assign Menu Shortcuts", or whatever is deemed appropriate. This item should trigger the [prefs::dialogs::menuShortcuts] proc which is explained below.
• the package should invoke the [menu::setUserShortcuts] proc in its activation script in order to automatically load user defined shortcuts the next time Alpha is launched, or, on the contrary, to remove the bindings when the package is deactivated.

This is all there is to it. The [prefs::dialogs::menuShortcuts] proc expects two or three arguments:

• an array associating menu names with menu tokens. The menu names are the names displayed in the interface: they do not have necessarily to be the real title or name of the menu (some menus anyway do not have a name or a title, but an icon instead). This is where one can decide which menus or submenus will be exposed since the package is free to build the array as it wishes: if you want to exclude a menu or a submenu, just don't put it in the array.
• a name to identify the package. This does not have necessarily to be the name used in the declaration of the package. This name is used to store the user defined shortcuts between sessions and is displayed in the title bar of the dialog in prettified form.
• additionnally an optional third argument can be passed to specify a mode: in that case all the bindings defined by the menu shortcuts will be mode-specific bindings rather than global bindings.

The [menu::setUserShortcuts] proc has a first argument with value on or off in order to respectively enable or disable the user defined shortcuts. The remaining arguments are exactly the same as with the [prefs::dialogs::menuShortcuts] proc: the same array, the same package name and the same optional mode. There are many examples of this mechanism in the AlphaTcl library which can serve as sample code.

The menu shortcuts hook

Some packages which bring extra functionalities to Alpha insert a small submenu in one of the basic submenus. In order not to clutter all the submenus with spurious commands to set menu shortcuts, it is also possible for a package to have its user-defined menu shortcuts managed by a "parent" package: for instance packages such as ''Window Utilities, Speech, Spelling, Redefine Colors'' would have their shortcuts managed by the AlphaTcl library itself. This means that the submenus inserted by these packages would be accessed via the same interface as the other basic menus: from the user's point of view, this will feel very natural since there is no reason to make a distinction between submenus. Similarly one can imagine a package adding extra functionalities to a major mode menu: such a package would like its submenu to be managed by the same interface as the rest of the menu. In order to achieve this, a package just has to register with the parent package using the [menu::shortcutsHook] proc. This proc is invoked during the activation or deactivation of the package in order to register or unregister respectively. Its arguments specify the package's name, the parent's name and a callback procedure which will be invoked by the parent package in order to get the names and the tokens of the submenus it has to manage. For instance here is how the Spellcheck package would register:

 
     menu::shortcutsHook register spellcheck AlphaTcl spell::shortcutMenuTokens

To unregister, the instruction is simply

 
     menu::shortcutsHook deregister spellcheck

The registered callback (spell::shortcutMenuTokens in the example above) is a proc which takes no argument and which returns a list with an even number of items of the form:

 
     menuName menuToken...

This is a list containing alternately a menu name (which is displayed in the interface dialog) and the corresponding menu token. This is the format expected by the [array get] Tcl command in order to load a list in an array. Note that there is no obligation to use this hook mechanism: many packages which insert a submenu in one of the basic menus still use a standalone interface as described in the previous section. This is the case of ManipCols, Notes, Favorites, Function Comments, Window Lines, etc. for instance.

Partial menu lists

There is another hook which lets a package expose only certain items of its menus or submenus to the menu shortcuts interface. This can be useful for menus which display changing data: this is typically the case of the Open Recent submenu or the Windows menu. There is no point to attach a menu shortcut to items which are constantly updated and modified. Only the persistent items in these menus should be exposed. In order to achieve this, the package must register a proc with the shortcutMenuItems hook. The hook is registered during activation and unregistered during deactivation. Here is how the Recent Files package registers:

 
     hook::register shortcutMenuItems recentmulti::listItemsForShortcuts "Open Recent"

This instruction simply registers a callback (named recentmulti::listItemsForShortcuts in the previous example) for the "Open Recent" submenu. When the callback is invoked, it receives three arguments: the menu name, the associated menu token and the package's name. It should return the list of items it wants to be exposed in the user shortcuts interface.