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 keyword same indicates the same horizontal position as the previous item. The keyword after indicates 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 keyword same indicates the same vertical position as the previous item. The keyword after indicates that the top of the item is aligned with the bottom of the previous item.
width	The horizontal size of the item. If the width is 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 the height is 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 format alt_character, where character must be a letter or number. For example, Key: alt_A indicates 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 with EnableItem() and DisableItem().
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 with ShowItem() and HideItem().
Help: help_specs	Help information displayed to the user in a popup help window and in the status bar. If help_specs is a single quoted string, it is displayed in both the popup help window and in the status bar. If help_specs is 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. The expression can 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. The variable_spec can be a variable, array element, or any expression that can appear on the left side of an assignment statement. If the variable_spec is 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 the Variable or the Variables option is allowed, but not both. The var_specs consist 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 properties width: The item's width will adjust proportionally as the width of the dbox changes height: The item's height will adjust proportionally as the height of the dbox changes top: The item's vertical position will change as the height of the dbox changes bottom: The item's vertical position will remain unchanged as the as the height of the dbox changes left: The item's horizontal position will change as the width of the dbox changes right: The item's horizontal position will remain unchanged as the width of the dbox changes width and heigth can be used together, thus changing both the width and the height of the item as the dbox is resized. top and bottom are mutually exclusive, as well as left and right.

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.