From AlphaWiki

Interface: Contextual Menus in Alpha

The purpose of this page is to provide a description of the new proposed mechanism to create contextual menu modules in AlphaX. This is an experimental mechanism. It is open to discussion and available only in the 8.2a1d5 or greater development releases, as of this writing.

• Creating a contextual module
  • Case of a single item
  • Case of a submenu
• Module declaration
• Examples
  • Creating a single item
  • Creating a submenu
    • Static submenu
    • Dynamic submenu
    • Mode-specific submenu

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 contextual module

Case of a single item

Creating a new contextual item requires two simple tasks:

• declaring the contextual item using the [contextualMenu::declare] proc
• defining the command invoked when this item is chosen

Case of a submenu

Creating a new contextual submenu requires three simple tasks:

• declaring the contextual module using the [contextualMenu::declare] proc
• building the submenu or defining an update proc which will be invoked dynamically when the submenu is opened
• defining the command invoked when an item is chosen in this submenu

Module declaration

The syntax of the [contextualMenu::declare] proc is

 
     contextualMenu::declare kind name proc onOff mode

where the arguments have the following meaning:

• the kind argument is either "submenu" or "item".
• the name argument is the name of the module. This name is displayed in the contextual menu in prettified form. For instance, the name could be windowPath and the displayed item visible in the contextual menu would be Window Path.
• the proc argument designates a Tcl proc attached to the module. In the case of an item, it is a command which will be invoked when this item is selected. In the case of a submenu, it is a menu proc similar to the procs associated with ordinary menus: its first argument is the menu token, and the second one is the item name.
• the onOff argument is optional. It is equal to 0 or 1 and indicates whether the contextual module should be included by default. The user can change this later using the Customize item located at the bottom of the contextual menu.
• the mode argument is optional. It specifies that the module should be made available only when the current window is in this mode.
• the token argument is optional. In the case of a submenu, it lets you pass the token of an already defined menu. If it is omitted, then the [contextualMenu::declare] proc takes care of creating the submenu itself and returns its token. This argument is ignored in the case of a simple item.

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.

Examples

Here is some sample code to illustrate the mechanism.

Creating a single item

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.

Creating a submenu

Static submenu

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.

Dynamic submenu

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.

Mode-specific submenu

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.