(System Library)
| Description: | Draws a list box with scroll bar (if required) and indicates the selected item. |
| Returns: | Nothing |
Usage:  |
Steady State only. |
| Function Groups: | Graphics |
| Related to: | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | RadioButtons | SpinBox | SplitList | TextBox | ToolBar | VScrollbar |
| Format: |
System.Listbox(X1, Y1, X2, Y2, Data, Index, [Picked, Flat, DoubleClick, MaxLen, RightClick, PostIt, FocusID, Multi, PickList, ColWidths, ColLabels, ColDivider, EditSelected]) |
| Parameters: |
| X1 | ||||||||
| Required. Any numeric expression giving the X coordinate on the screen of one side of the Listbox, usually the left side. | ||||||||
| Y1 | ||||||||
| Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the Listbox, usually bottom. | ||||||||
| X2 | ||||||||
| Required. Any numeric expression giving the X coordinate on the screen of the side of the Listbox opposite to X1, usually the right side. | ||||||||
| Y2 | ||||||||
| Required. 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 | ||||||||
| Required. An array of data to display in the Listbox. | ||||||||
| Index | ||||||||
| Required. 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 | ||||||||
| 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 | ||||||||
| Obsolete. | ||||||||
| DoubleClick | ||||||||
| 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 | ||||||||
| 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 | ||||||||
| 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 | ||||||||
| An optional parameter that is any logical expression. If true (non-0), a tool tip will be displayed if the text in the list box has been truncated at its right edge. The default is true. | ||||||||
| FocusID | ||||||||
|
An optional parameter that is any numeric expression from 0 to 32767 for the focus number of this graphic. If this value is zero, the list box will not accept keyboard input, but mouse input will still be recognized. |
||||||||
| Multi | ||||||||
| 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 | ||||||||
| 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 | ||||||||
| An optional parameter that indicates the starting widths for multiple columns. | ||||||||
| ColLabels | ||||||||
| An optional parameter that provides an array of labels for the columns. | ||||||||
| ColDivider | ||||||||
An optional parameter that indicates the type of divider to appear between columns. No border appears if the list is a single column. ColDivider may have one of the following values: The default is "2".
|
| EditSelected | ||||||||
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:
|
| Comments: |
This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section. If your application predates version 11.2, use the backslash notation rather than dot: \System\ 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 deselected 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 selected item will be selected. All other items outside of this list will be deselected. 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 selected item will be set to the state of the last selected item. |
Examples:
System.Listbox(10, 10, 110, 210 { Outline of list box },
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.
