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 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.
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 is a boolean value. When true the item will not be displayed.
- 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.
- 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. When not present or the value is zero, selecting the menu item never exits the Action Pending Window. When the value is greater than zero, the Action Pending window will be dismissed immediately. Any validation requirements specified for the statement will be ignored. When the value is less than zero, 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. exit is effectively ignored by the Prompt statement as all menu items exit.
