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 User Defined Menu 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.
Installing support for configureable menu item shortcuts is very simple. It involves two tasks:
This is all there is to it.
The [prefs::dialogs::menuShortcuts] proc expects two or three arguments:
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.
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:
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.
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.