Defines a popup menu (aka "context menu") that will appear when the user right-clicks on a cell. You may define a single popup menu to be used by all columns, and/or you may define popup menus that are specific to individual columns. A PopupMenu definition consists of a series of pairs of text/cmd items with the following syntax:

PopupMenu = text1, cmd1; text2, cmd2;...; textN, cmdN

The <text> fields define what appears on that line of the popup menu, while the <cmd> fields define the key sequence that is transmitted if the user clicks on the option. See Virtual Key Symbolic Names. Also see Notes below for comments on certain built-in special menu commands.

To create a horizontal separator bar, set the <text> field to a string of dashes and leave the <cmd> field null (with no spaces between the dashes, the comma, and the semicolon.).

For example, consider this PopupMenu definition:

COLDEF = COLDEF + "0~0~X~S~PopupMenu=Retire,VK_xF101;Visit,VK_xF102;Pass Through,VK_xF103;-----,;Attack,VK_xF104~~"

This would create a popup menu, which, when the XTREE control was right-clicked, would display four choices (Retire, Visit, Pass Through, and Attack) with a horizontal separator between the last two items (in a particularly feeble ergonomic effort to prevent inadvertent war). If the user then clicked on one of the items in the popup menu, XTREE would exit, setting exitcode to -101, -102, -103, or -104 depending on the item. The effect would be exactly as if you had defined buttons which transmitted the same key codes. Here's what it might look like:

In addition to the exitcode, the xtr'targetrow / xtr'targetcol and/or xtr'xrow / xtr'xcol fields in the xtrctl parameter will be set to indicate the logical row and column where the right-click occurred.

The popup menu defined above would be available to all columns because it was associated with the pseudo column zero (cpos, cwidth both set to 0). To define a popup menu that is specific to a column, just associate the PopupMenu specification with a real column, as in these two examples:

COLDEF = COLDEF + "50~15~State/Province~S~PopupMenu="+-----,;Run for Governor,VK_xF105;Check State Tax Rates,VK_xF106;Find State Capitol,VK_xF107~~"

COLDEF = COLDEF + "70~12~Country~S~PopupMenu=Obtain Passport,VK_xF108;Recall Ambassador,VK_xF109~~"

The first of the two column definitions above creates a column titled "State/Province" which has its own popup menu items that are appended to the shared popup menu (i.e. the one defined previously for pseudo column zero). The special character "+" at the start of the PopupMenu definition string is what causes the items to be appended to the shared popup menu rather than replacing it. Here's what the menu would look like:

The second definition creates a column titled "Country" with a popup menu containing two items. Because the definition is for a real column and does not start with the special character "+", it replaces the shared popup menu entirely, resulting in something like this:

 

Updating Popup Menus: On re-entry into an existing XTREE, the PopupMenu definitions are reprocessed for opcodes XTROP_CREATE (0) and XTROP_REPLACE (1), but not for XTROP_SELECT (4). So to modify the popup menu(s) in response to some user input, you must exit from XTREE back to the application, modify your complete coldef definition string, then re-enter with xtr'opcode = XTROP_REPLACE. If you want the application to have the opportunity to update the popup menu, before displaying it, whenever the user right-clicks, use ClickExit to define a right-click exitcode. This will override the PopupMenu. Then use the ability to force the popup to display immediately on entrance, as described below.

Forcing Popup Menu to Appear Automatically: You can force a popup menu to appear immediately on entrance to XTREE by setting xtr'xnavmask = 64. The position of the mouse will determine which column the popup menu will be requested for. This is the one case where PopupMenu will override ClickExit.

Special menu commands: In addition to the standard kind of menu commands which are made up of literal or symbolic key sequences, certain commands are built-in and recognized by XTREE:

$RESETCFG

Resets the saved column configuration to the default state. This is useful to deal with the possibility of a user accidentally making a disastrous change to their configuration, such as resizing a column to zero width, thus making it disappear entirely. See Saving User Adjustments. For example:

COLDEF = "0~0~x~H~PopupMenu=Reset columns.$RESETCFG~~"

As of A-Shell build 1185, June 2010, $RESETCFG also resets the text scale adjustment factor (i.e. includes $RESETSCALE)

$CBSET{DEP}

$CBRST{DEP}

$CBUNDO

$RESETSCALE

Resets the overall text scale adjustment factor back to zero; equivalent to Control /.

$SCALE+ and $SCALE-

Causes the fonts to be increased (+) or decreased (-) by about ten percent; equivalent to Control + and Control -.

The above special context menu commands relate to extended Editable checkbox columns, which see for details.   

2010 July, 1188	Added $SCALE+ and SCALE-.
2010 June, 1185	Added $RESETSCALE.