Dialog Box Items

A dialog box is made up of many different items, such as buttons, scrolling lists, and pieces of text.

In general, the format of a dialog box item definition is:

Type {"item name"} position_information {options} {do

endItem}

Most items do not require an item name unless it is necessary to disable, enable, hide, or show them dynamically, using DisableItem(), EnableItem(), HideItem() and ShowItem(), which take the item name as their argument. Item names must be unique, not just within a dialog box but also among all dialog boxes, toolboxes, and toolbars.

For items that require position and size information, that information has the format:

hpos, vpos {, width {, height}}

All positions and sizes are in character units based on the standard dialog box font. Positions and sizes are not required to be whole characters; 3.5, 0.25, and 15.9 are all valid values.

Value	Meaning
hpos	The horizontal position of the item relative to the left edge of the dialog box. Instead of a value, the keywordsameindicates the same horizontal position as the previous item. The keywordafterindicates that the left edge of the item is aligned with the right edge of the previous item.
vpos	The vertical position of the item relative to the top edge of the dialog box. Instead of a value, the keywordsameindicates the same vertical position as the previous item. The keywordafterindicates that the top of the item is aligned with the bottom of the previous item.
width	The horizontal size of the item. If thewidthis not specified, most items use a width large enough to hold their text. If the item uses an icon, you cannot set the width.
height	The vertical size of the item. If theheightis not specified, most items are one character high. If the item uses an icon, you cannot set the height.

Some options are common to several types of items:

Common Options	Description
Key:hotkey	A key sequence the user presses to activate the item instead of using the mouse. The hotkey has the formatalt_character, where character must be a letter or number. For example,Key: alt_Aindicates that holding the Alt key and pressing A activates the item. The specified key is underlined in the item's text. A hotkey only works if the key in question is part of the item's text and is case insensitive.
Disabled	The item is initially disabled. If this option is not specified, items are enabled when the dialog box is created. You can dynamically enable and disable items withEnableItem()andDisableItem().
Hidden	The item is initially hidden. If this option is not specified, items are visible when the dialog box is created. You can dynamically show and hide items withShowItem()andHideItem().
Help:help_specs	Help information displayed to the user in a popup help window and in the status bar. Ifhelp_specsis a single quoted string, it is displayed in both the popup help window and in the status bar. Ifhelp_specsis two strings separated by a comma, then the first is displayed in the popup help window and the second in the status bar. For example,Help: "Redraw", "Redraws the Map"displays the string "Redraw" in the popup help window and "Redraws the Map" in the status bar. Help strings can be string expressions.
Menu:array	Provides a context-sensitive menu when the user right-clicks on an item in a Scroll List, Tree View, or Grid View control. The value of the menu options is an array, each of whose elements corresponds to an item in the menu to be displayed and which is itself an options array with the options described below.
Prompt:expression	For some items, such as buttons, the "prompt" is the text of the item. For others, such as edit text items, it is text displayed to the left of the item used to identify it to the user. Theexpressioncan be a literal string or it can be a Caliper Script expression that varies while the user interacts with the dialog. The item is updated when the value of the expression changes.
Location:hpos,vpos{,width{,height}}	Position and size values. See example below for alternative ways to defining the location and size.
Variable:variable_spec	Many items have a user-supplied value. An edit text item, for example, has the text entered by the user. The Variable option specifies the variable that is assigned the user's value. This value is set whenever the user interacts with the dialog box. Thevariable_speccan be a variable, array element, or any expression that can appear on the left side of an assignment statement. If thevariable_specis assigned elsewhere in the dialog box, the item is updated to reflect its new value.
Variables:var_specs	Some items allow the specification of more than one variable. For these items, either theVariableor theVariablesoption is allowed, but not both. Thevar_specsconsist of as many variables as allowed by the item, separated by commas.
Resize:[[width] [, height]],[[left] [, right]],[[top] [, bottom]],	The way the position and size of dbox items change when the dbox is resized can be controlled by defining the following propertieswidth: The item's width will adjust proportionally as the width of the dbox changesheight: The item's height will adjust proportionally as the height of the dbox changestop:The item's vertical positionwill changeas the height of the dbox changesbottom:The item's vertical positionwill remain unchangedas the as the height of the dbox changesleft: The item's horizontal positionwill changeas the width of the dbox changesright:The item's horizontal positionwill remain unchangedas the width of the dbox changeswidthandheigthcan be used together, thus changing both the width and the height of the item as the dbox is resized.topandbottomare mutually exclusive, as well asleftandright.

The options for items in a context-sensitive menu, in the array for the Menu option, are:

Menu Item Option	Type	Contents
Title	String	The title of the menu item.
Macro	String	The name of a macro to run when the menu item is selected. The macro can be defined inside the dbox or be external to it. If this option is not specified then the program will attempt to run a macro by the same name as the Title option.
Object	Object	A UI object variable whose macro will be run when the menu item is selected.
Disabled	Boolean	True if the item should be disabled; default is False
Checked	Boolean	True if the item should have a check mark displayed to its left; default is False
Hotkey	String	A letter in the title string that will cause the item to be run if the user presses that key when the menu is open.
Help Text	String	The text to displayed in the status bar when the mouse cursor is positioned over the item.
Help Topic	String	The help topic to be displayed if the user presses F1 when the mouse cursor is positioned over the item.
Separator	Boolean	If true then a separator item will be included in the menu at this location. all other options are ignored.
Menu	Array	If this option is provided then this item will have a submenu whose contents are specified by the array provided.