Updated March 2013; see History

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 information 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~~"

Notes

Disabling individual menu items may accomplished by marking them as disabled with a "!" at the start of the item text, i.e.: PopupMenu=!disabled item,VK_xF999; ... See History.

Context menus: Context menus may specify icons. See History, below, and the subtopic Icons.

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 to 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~~"

$RESETCFG also resets the text scale adjustment factor—i.e. includes $RESETSCALE. See History.

$CBSET{DEP}

$CBRST{DEP}

$CBUNDO

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

$COPY

Copy to Clipboard the contents of the tree

$EXPCSV and $EXPTSV

Export the contents of the tree to a delimited file

$PRINT

Print the contents of the tree to a delimited file

$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 -.

$SRCHCOL and $SRCHALL

Provide expanded Search options

History

2017 January, A-Shell 6.3.1542:  (1) Individual menu items may now be marked as disabled. (2) Sub-menus now supported. (3) Indexed popup menus now supported.

2013 July, A-Shell version 6.1.1357:  Added ability to include icons in context menus

2013 Feburary, A-Shell version 6.1.1338:  A-Shell now automatically adds "Paste Special" to the context menu when complex clipboard formats are available. Depending on the formats, the menu option will open a submenu with more specific paste options, such as picture, spreadsheet, etc. To customize the wording of the menu option, add or modify the 004,011 message in the SYSMSG.xxx file. All SYSMSG.xxx included in the release package have been updated with rough translations. Note that if you don't want this capability, you can disable it by setting the TXMF1_EDIT_PASTESP (&h00400000) flag in the TXC'MENUMASK1 field.

2010 July, A-Shell 5.1.1188:  Added $SCALE+ and SCALE-.

2010 June, A-Shell 5.1.1185:  Added $RESETSCALE.