Updated March 2018; 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 optional plus sign indicates that the following menu items should be added to a previously defined global PopupMenu, as discussed below.
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~~"
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: |
|
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:
Command |
Description |
|---|---|
$CBSET{DEP} |
These special context menu commands relate to extended Editable checkbox columns, which see for details. |
$CBRST{DEP} |
|
$CBUNDO |
|
$CBRSTX |
Same as $CBRST but sets XTR.xvalidate bit &h08; see History |
$CBSETX |
Same as $CBSET but sets XTR.xvalidate bit &h08; see History |
$CBUNDOX |
same as $CBUNDO but sets XTR.xvalidate bit &h10; see History |
$COPY |
Copy to Clipboard the contents of the tree |
$EXPCSV and $EXPTSV |
Export the contents of the tree to a delimited file |
$EXPCSV2XL{:inispec} |
|
Format the XTREE for printing and display in an APEX print preview window for possible printing. |
|
$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. |
$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 -. |
$SORT |
Triggers an internal multi-level Sort. |
$SRCHCOL and $SRCHALL |
Provide expanded Search options |
History
2018 March, A-Shell 6.5.1633: $CBSETX, $CBRSTX and $CBUNDOX added. These new variations of the checkbox set, reset, and undo commands resolve a problem with the standard ones involving ambiguity over the possible interpretations of the XTR.validate = 3 that they return.
2017 January, A-Shell 6.3.1542: (1) Individual menu items may now be marked as disabled. (2) Submenus 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 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.
