Listbox

(System Library)

Description: This module draws a listbox with scrollbar (if required) and indicates the selected item.

Returns: Nothing

Usage: Steady State.

Format: \System\Listbox(X1, Y1, X2, Y2, Data, Index, [Picked, Flat, DoubleClick, MaxLen, RightClick, PostIt, FocusID, Multi, PickList, ColWidths, ColLabels, ColDivider, EditSelected])

Parameters: X1 { numeric } { required } { no default }

Any numeric expression giving the X coordinate on the screen of one side of the listbox; usually the left side.

Y1 { numeric } { required } { no default }

Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the listbox; usually bottom.

X2 { numeric } { required } { no default }

Any numeric expression giving the X coordinate on the screen of the side of the listbox opposite to X1; usually the right side.

Y2 { numeric } { required } { no default }

Any numeric expression giving the Y coordinate on the screen of the top or bottom of the listbox, whichever is the opposite of Y1; usually the bottom.

Data { array } { required } { no default }

An array of data to be displayed in the listbox.

Index { numeric } { required } { no default }

The index of the highlighted item (i.e. any variable whose value will be set to the index of the chosen item (highlight).) If Multi is true, this will be the index of the last chosen item.

Picked { numeric } { optional } { no default }

An optional parameter that may be a variable whose value is set to true (1) when an item is chosen in the listbox; the setting of Index by an external source will not trigger Picked. If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.

Flat { Boolean } { optional } { default: false }

An optional parameter that is any logical expression; if true (non-0) the border of the listbox will be a single black line, if false (0) it appear with a 3-D border. The default is false.

DoubleClick { numeric } { required } { no default }

An optional parameter that may be a variable whose value is set to true (1) when an item has been double clicked upon. If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.

MaxLen { numeric } { optional } { default (see note) }

An optional parameter that is any numeric expression giving the maximum length of the list; if omitted or invalid, the maximum list length is given by the size of the array Data.

RightClick { Boolean } { optional } { no default }

An optional parameter that may be a variable whose value is set to true (1) when an item is selected with the right mouse button. If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.

PostIt { Boolean } { optional } { default: true }

An optional parameter that is any logical expression; if true (non-0), a tool tip will be displayed if the text in the listbox has been truncated at its right edge. The default is true.

FocusID { numeric } { optional } { default: 1 }

An optional parameter that is any numeric expression for the focus number of this graphic. If this value is 0, the listbox will not accept keyboard input, although mouse input will still be recognized; if it is les than 0, the listbox will not accept any input and will appear grayed out. The default value is 1.

Multi { Boolean } { optional } { default: false }

An optional parameter that is any logical expression; if true (non-0), multiple items may be selected in the list. The default is false.

PickList { array } { optional } { no default }

An optional parameter that is a variable whose value is set to the list of items selected if Multi is true (1). If invalid, no items are selected. This variable may initially be set to a dynamically allocated array (one created with the New function) containing items to be highlighted/selected upon the startup of the listbox.

ColWidths { numeric } { optional } { no default }

An optional parameter that indicates the starting widths for multiple columns.

ColLabels { array of text } { optional } { no default }

An optional parameter that provides a list of labels for the columns.

ColDivider { numeric } { optional } { no default }

An optional parameter that indicates the type of divider to appear between columns. The default is "2"; no border appears if the list is a single column. ColDivider may have one of the following values:

ColDivider	Divider Type
0	No column divider shown;
1	Show a non-moveable column divider; or
2	Show a moveable column divider.

EditSelected { numeric } { optional } { no default }

An optional flag that indicates whether a selected item may be edited in the list. EditSelected will be set to 0 when the editing stops. EditSelected may have one of the following values:

EditSelected	Meaning
Invalid	no editing;
0	enable item editing; or
1	edit current selected item.

Comments: This module is a member of the System Library, and must therefore be prefaced by \System\, as shown in the "Format" section. If the application you are developing is a script application, the System variable must be declared in APPMOD.SRC and need not be prefaced by a backslash in the function call.

If Multi is true, multiple items in the list may be selected by using the <Shift> or <Ctrl> keys along with mouse input. If <Ctrl> is held while an item is clicked on by the mouse, it will become selected (or de-selected if it is already selected) and will be added to the list of chosen items. If <Shift> is held while an item is clicked on by the mouse, all items from the last selected item to the currently selected item will be selected; all other items outside of this list will be de-selected. If both <Ctrl> and <Shift> are held while an item is clicked on by the mouse, all items from the last selected item to the currently selected item will be set to the state of the last selected item.

For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Examples:

\System\Listbox(10, 10, 110, 210 { Outline of listbox },

List { Data to display },

Highlight { Index of highlight });

In this example, the listbox is displayed with only a single black line around it; notice that since none of the optional parameters are used, they have been omitted. Also, the listbox will display the full contents of the array because MaxLen has similarly been omitted.

\System\Listbox(20, 355, 295, 100 { Outline of listbox },

NameList { list of names to display },

ListIndex { Index of highlight },

0 { Picked parm not used },

0 { Drawn 3D },

Double { True when double clicked },

Invalid { MaxLen parm not req'd },

RtClick { True when rt clicked on },

1 { tool tips as req'd },

5 { Focus ID },

1 { Multiple selections },

FinalList { Var containing list of

selected items });

This example illustrates including all of the optional parameters, even those such as MaxLen that in this case are not used.