Contextual Menus in Alpha
Starting with version 8.2a1d5, AlphaX provides a new mechanism for defining contextual menu modules. This page will be of interest to developers who want to define contextual menus for Alpha.
A contextual menu is a popup menu which appears when the user executes a mouse click while pressing the control key: this operation is usually referred to as a control-click. As the name suggests, the contents of this popup menu depends on the context: in Alpha, this means that the items displayed in the menu may vary depending on the mode of the current window. The Contextual Menu package must be activated in order to enable contextual menus in Alpha.
Many packages contribute to the contents of the contextual menu: they provide modules which take the form of either a simple item or a submenu. The user has a complete control about which modules should be displayed in the contextual menu.
The mechanism which allows a package to define a module has been modified and simplified to take advantage of the new menu syntax introduced in AlphaX 8.2. This page explains the main principles.
The previous mechanism was not very intuitive. In order to create a contextual menu named MyModule, you had to declare a preference named MyModuleMenu or MyModuleItem using the [newPref] command: this was a bit disconcerting because a contextual menu does not have anything to do with preferences. The new proposed model relies, behind the scenes, on the same mechanism but hides all the hacky details from the user: it is wrapped in the new simple [contextualMenu::declare] proc explained below.
Another difference with the previous system is that contextual submenus now have a menu token and can take advantage of the new [menuItem] and [menuRef] commands introduced in Alpha 8.2a1 (see the MenuItemCommand and MenuRefCommand pages on this wiki).
The contextual menu itself also has a menu token called "contextual" which gives you access to its contents. AlphaTcl makes use of this token to rebuild the contextual menu each time the user invokes it by a control-click.
Creating a new contextual item requires two simple tasks:
Creating a new contextual submenu requires three simple tasks:
The syntax of the [contextualMenu::declare] proc is
contextualMenu::declare kind name proc onOff mode
where the arguments have the following meaning:
The value returned by the [contextualMenu::declare] proc is a menu token in the case of a submenu, or an empty string in the case of an item.
Here is some sample code to illustrate the mechanism.
The following instruction is enough to create a Calculator item in the contextual menu. The [Calc::calculatorWindow] proc will be automatically invoked when the item is chosen by the user.
contextualMenu::declare item "calculator" Calc::calculatorWindow 0
The last argument is equal to 0: this means that this item will not be present in the contextual menu by default. The user can change this by selecting the Customize command at the bottom of the contextual menu. This brings up a dialog in which the user can select which elements should be present in the contextual menu. If the checkbox located in front of the Calculator item is checked then it will appear in the contextual menu.
The following instruction, taken from the Mac Menu package, will create a Mac Window submenu in the contextual menu.
set cmToken [contextualMenu::declare submenu "macWindow" mac::cmWindowProc 0]
The cmToken variable contains the token of the newly created submenu. The Mac Menu package can use it to populate the submenu.
The [mac::cmWindowProc] proc declared in the instruction above will be invoked with two arguments: the first one is the menu token (which is the same as the value of the cmToken variable) and the second one is the name of an item.
Some packages may want to populate the menu dynamically just before the user attempts to open it. The following instructions show how this can be done:
set cmToken [contextualMenu::declare submenu "windowPath" contextualMenu::path 1] menuRef set $cmToken -updateProc contextualMenu::updatePath
The first instruction is not different from the previous example. The second one attaches an update proc to the submenu. This proc is invoked automatically when the user opens the submenu. It is called with only one argument which is the menu token.
Finally here is an example of a mode-specific contextual module:
contextualMenu::declare submenu "htmlAttributes" html::CMTagArgsProc 1 HTML
The contextual menu will contain an Html Attributes submenu exclusively when the current window is in HTML mode.