Definition
Define a list box.
[enabled|disabled] [visible|invisible]
[[color] COLOR] [multiple selection]
list box LB_NAME
size WIDTH HEIGHT at [position] X Y in DB_NAME
[parameter is PAR_STRING]
[helpid is HELP_ID]
[sort {ascending|descending}]
[horizontal scroll bar]
[group is GROUP_NAME]
[font FONT_NAME]
[insert {TEXT_STRING|file ASCII_FILE_NAME} ] ...
enabled | disabled
Define the list box as selectable or not. If you define the list box as disabled, it is displayed grayed and cannot be selected. The default is enabled.
visible | invisible
A visible object is displayed when it is defined. An invisible object is not displayed until you specifically make it visible. The default is visible.
color COLOR
A color keyword, a string value representing a color keyword, or an integer value representing a color number corresponding to a color available on your system.
multiple selection
Allow this list box to let the user make multiple selections.
LB_NAME
The identifier for a list box.
size WIDTH HEIGHT
Integer values representing the dimensions of the list box in dialog units.
at position X Y
Integer values representing the position of the list box in dialog units.
in DB_NAME
The identifier for the dialog box or dialog region parent object.
parameter is PAR_STRING
A string value representing the parameter of the list box. The default parameter string is "".
helpid is HELP_ID
A string or integer value representing the identifier of the help panel you want displayed when the user requests help for this list box. This should match the help panel defined in the library specified by the help library declaration. The default HELP_ID is "".
sort ascending | descending
Sort the list box entries in ascending or descending order. If you do not include a sort specification, entries inserted into the list box will be added to the end.
horizontal scroll bar
Include a scroll bar along the bottom edge of the list box.
group is GROUP_NAME
An identifier for the group of dialog control objects to which the list box belongs.
font FONT_NAME
The name of the font in which you want the TEXT_STRING to appear. You may use either system or ESL fonts. (See the description of the font is Font Reference Definition.)
You cannot change the font of a control at runtime.
insert TEXT_STRING
A string value representing the text you want inserted into the list box.
insert file ASCII_FILE_NAME
A string value representing the name, including the extension, of an ASCII file you want inserted into the list box.
Description
A list box is a dialog control and must have a dialog box or dialog region as its parent.
Only the list box keywords, the identifier, the at [position] specification, the size specification, and in DB_NAME are required in the definition, in the order shown in the model.
A response is taken to a multiple selection list box whenever an entry is selected or deselected. Note that if an entry was previously selected, single- or double-clicking on the entry again will deselect that entry.
In a single-selection list box, selecting an already selected line does not trigger a response.
Note that the insert statement(s), if there are any, must come last in a list box definition.
The total size of all list boxes within a given dialog box/region cannot exceed 64K, with no more than 256 characters on any single line. To determine the approximate size of a list box, multiply the line length by the number of lines. For example, a list box containing 128 lines with a line length of 256 characters will create a list box of approximately 32.8K, plus additional overhead. In general, the greater the number of lines, the more overhead is required, leaving less space for the actual contents of each line.
We recommend that you do not read large amounts of data into a list box, as it defeats the purpose of quick access to items. Instead, you could use a series of smaller list boxes that you retrieve selectively; for example, alphabetically, or in groups of 200 lines. With such a scenario, the user could request more data by selecting a More Data push button. Alternately, if you must put 64K of data in a list box, you might want to simulate one by creating a textual region that includes a vertical scroll bar.
Example
invisible dialog box SaveFile
size 160 100 at position 200 200
dialog border
title bar "Save Output File"
system menu
list box Directories
size 60 50 at position 6 20
in SaveFile
sort ascending
insert "sources"
See Also
combination box Definition
dropdown list Definition
font is Font Reference Definition
for each selected line loop Action Statement
remove Action Statement
selected line from Object Inquiry Built-in Function
