Prompt Menu Formatting

The menu formatting described in this topic applies to menus displayed by the Prompt For Text statement's picker button, the Prompt statement's Menu mode, any configurable button set to be a Menu and by any button which has a displayed menu disclosure. The container model is also used by the Prompt from Container statement's popupValues key.

The source of the menu is contained in the following named variables:

Prompt for Text List

Used by the Prompt for Text statement's picker control

Prompt Button 1 Menu

Prompt Button 2 Menu

Prompt Button 3 Menu

Prompt Button 4 Menu

Associated with the specified Prompt or Prompt for Text statement button.

The content of the source named variable either contains the menu items in a list or references a container which describes the menu.

If the source named variable starts with .[ all following text is treated as the name of a container to reference for the menu layout. If you want to use a text based menu definition and for some reason the first menu item starts with a .[ sequence, precede it with a \n sequence.

When a menu item is selected, the Prompt Menu Item Reference named variable is set to a value which indicates which menu item was selected. If a menu item is not selected, the Prompt Menu Item Reference named variable is set to -1. You differentiate which button caused the selection by examining the Prompt Chosen Button named variable. Possible values are 0 through 4 where 0 represents the Prompt for Text statement's picker control and 1 through 4 represents a button number.

Text Based Menu Definitions

Text based menus cannot have submenus. When a menu item is selected, the Prompt Menu Item Reference named variable is set to a zero based index into the list in the source named variable.

The default list delimiter \~ and newline characters (\n) can be used as list delimiters. All leading and trailing newline characters are removed prior to constructing the list. If a list item starts with a % character the next character is used as a special formatting code.

The following codes are currently supported:

%-

All text following the %- is ignored. A menu separator line will be displayed. Redundant separator lines are not displayed. The returned index always refers to the items used to construct the menu. For example assume the following menu definition:

Test1
%-
%-
Test2

The menu will display as:

Test1
------
Test2

If you click on Test2, named variable Prompt Menu Item Reference will be set to 3.

%+

The text following the %+ sequence will be the displayed name. The menu item will be displayed with a preceding ✓. The check mark is not part of the text.

%!

The text following the %! sequence will be the displayed name. If the menu item is selected, the Action Pending window will be dismissed immediately. Any format requirements specified for the statement will be ignored.

%?

The text following the %? sequence will be the displayed name. If the menu item is selected, the Action Pending window will be dismissed if there are no format requirements or the format requirements are satisfied. Note that the Prompt statement has no validation process.

%%

A single leading % will be removed and the remainder of the text will be the name.

%any other character

The name will be the entire text string including the leading %

If a menu item does not start with a special code the following holds:

Prompt for Text statement

The menu item's title is copied to the text field.

Prompt statement

The panel is dismissed.

Prompt for Fields statement

Prompt from Container statement

%? is assumed. ie. if validation succeeds, the panel will be dismissed.

Container Based Menu Definitions

If the source named variable contains .[menu a container named menu must exist and must be an array. If either of those conditions are not true, a menu will not be displayed. Menus defined in containers can contain submenus. Note that this model of menus is also used by the Prompt from Container statement. For this statement the source of the menu is the popupValues key.

When a menu item is selected, the Prompt Menu Item Reference named variable is set to a directed path to the selected item. When a menu item is represented in an object, you can include additional context items to assist in the processing of the selected item.

Each array item can be a string which is a menu item name; a null which is treated as a separator; or an object. The following items in an object are processed in the presented order:

hidden

This optional item can be a boolean value. When true the item will not be displayed. Menus created for use in Prompt from Container statements can also have this item as an array. The array contains criteria to be evaluated at runtime to determine if the menu item is hidden. The criteria formatting is described in the enable item in the Disabling Rows and the Value Column topic.

disabled

This optional item can a boolean value. When true the item will not be enabled. Menus created for use in Prompt from Container statements can also have this item as an array. The array contains criteria to be evaluated at runtime to determine if the menu item is disabled. The criteria formatting is described in the enable item in the Disabling Rows and the Value Column topic.

separator

This optional item is a boolean value. When true the item will display as a separator item.

name

If not hidden and not a separator, there must be a name item. It represents the displayed menu item name.

items

If an array item named items is present, the item is a submenu. Each element of the array is formatted as described in this table. ie. the same items apply for each submenu item. Note that items is ignored if disabled is true.

Note that when used with a Prompt from Container statement, items is not valid when valueIsPopup has a value of 1. ie. it is not valid with indexed menus.

selected

This optional boolean item is only parsed if items is not defined. If set to true, the menu item will be preceded by a checkmark.

exit

The numeric item is only parsed if items is not defined.

Semantics for Prompt for Text statements:

If the value is less than 0, the statement will terminate if all validation conditions are met. If the value is greater than zero, the statement will always terminate. If the value is 0, the text field will be set to the menu item's name.

Semantics for all container menus except for Prompt from Container per row menus:

When the value is greater than zero, the panel will be dismissed immediately. Any validation requirements specified for the statement will be ignored. When the value is less than or equal to zero, the panel will be dismissed if all validation conditions are met.

Semantics for Prompt from Container per row menus:

When not present or the value is zero, selecting the item will modify the row. When the value is greater than zero, the panel will be dismissed immediately. Any validation requirements specified for the statement will be ignored. When the value is less than zero, the panel will be dismissed if all validation conditions are met. If the panel is dismissed, the numeric value is returned in the Prompt Chosen Button named variable. Note that currently values of 1, 2, 3 and 4 are used to denote which panel button was used to exit. -1 is used to represent an exit caused by the panel checkbox. -1000 is used to reflect a Cancel with an Exit mode. It is a good idea to avoid these values. The Prompt Menu Item Reference named variable will always have the unused value of -1.

icon

An integer or string item representing an optional icon to be displayed on the menu item. String is permitted so that an actual colour can be included after the integer for clarity. for example: "icon" : "4 Green Circle".

0 or undefined implies no icon. These items and all container menu items can be inserted from the function menu in the Create Container from JSON statement's multi line editor. If you're really interested, the current set of icons are listed below.

any other item

These items are ignored.

Container Based Icon Item Values

Any other value is treated as no icon.