Droplist

(System Library)

Description: This module draws a droplist with (optional) title and/or bevel.

Returns: Nothing

Usage: Steady State

Format: \System\DropList(X1, Y1, X2, Y2, Data, Title, Index, FocusID, Trigger, NoEdit, Init, Variable [, DrawBevel, VertAlign, AlignTitle, Style])

Parameters: X1 { numeric } { required } { no default }
Any numeric expression giving the X coordinate on the screen of one side of the droplist.

Y1 { numeric } { required } { no default }
Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the (opened) droplist.

X2 { numeric } { required } { no default }
Any numeric expression giving the X coordinate on the screen of the side of the droplist opposite to X1.

Y2 { numeric } { required } { no default }
Any numeric expression giving the Y coordinate on the screen of the top or bottom of the (opened) droplist, whichever is the opposite to Y1.

Data { array } { required } { no default }
An array of data to be displayed in the droplist.

Title { text } { required } { no default }
Any text expression to be used as a title for the droplist.

Index { numeric } { required } { no default }
A variable whose value indicates the array index of the highlighted item in the list. Index can be set invalid to reset the droplist.

FocusID { numeric } { required } { no default }
Any numeric expression for the focus number of this graphic. If this value is 0, the droplist will display its current setting, but will not be able to be opened (i.e. its value cannot be changed) and will appear grayed out. The default value is 1.

If this parameter is invalid, keyboard input (such as the carriage return key) will be ignored.

Trigger { numeric } { required } { no default }
A parameter whose value is derived from WinComboCtrl. It can be set to "0" (internal buffer changed), "1" (selection made from list or Enter key pressed), or "2" (focus lost).

If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.

NoEdit { Boolean } { required } { default: true }
Any logical expression; if true (non-0) the text displayed in the droplist cannot be edited directly, if false (0) it can be edited in the same manner as an editfield.

Note: if an invalid variable (BASEVALUE) is provided, NoEdit will default to True. If any other type of invalid is provided (VALUE) then NoEdit will default to False.

Init { numeric } { required } { no default }
Any expression for the initial value displayed in the field if Index is set to invalid. If NoEdit is true, then Init must be an element of the data array.

Variable { variable name } { required } { no default }
The variable whose value is set by the droplist.

DrawBevel { numeric } { optional } { default: false }
An optional parameter that is any logical expression; if true (non-0) a bevel is drawn around the droplist, if false (0) no bevel is drawn. The default value is false.

VertAlign { numeric } { optional } { default: 0 }
An optional parameter that is any numeric expression that sets the vertical alignment of the editfield according to one of the following options:

VertAlign	Vertical Alignment
0	Top
1	Center
2	Bottom

Whether or not the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle { numeric } { optional } { default: true }
An optional parameter that is any logical expression; if true (non-0) the title is included in the calculation for vertical alignment, if false(0) it is added to the droplist after it (and its bevel if one exists) has been vertically aligned. The default is true.

Style { numeric } { optional } { default: true }
Comprised of the arithmetic sum of the following fields, to yield the desired effects.

Bits 2^0 and 2^1 define mutually exclusive styles of operation. They can be set to one of the following values:

Style	Definition
0	No droplist, rather a listbox with the selected item above
1	Droplist and editable selection
2	Droplist with non-editable selection

Bits 2^2 and 2^3 define input character handling. They can be set to one of the following values:

Style	Definition
0	Input is passed to script code as typed.
4	Input is converted to all uppercase.
8	Input is converted to all lowercase.

Bits 2^4 controls list sorting.

Style	Definition
16	The list is presented in sorted order to the user.

Bit 2^8 enables Windows visual styles.

Bit 2^9 defines and enables exact use of application-defined geometry. The default is to perform auto-geometry modification to give the best fit.

Style	Definition
512	Enable application-defined geometry.

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.

The height of the (unopened) droplist is constant, with X1 and X2 defining its width, and Y1 and Y2 defining its opened height, which may or may not include the added height of a title and bevel, depending on the alignment used and if they exist. Note that if the entire list can be displayed in a smaller area than indicated by Y1 and Y2, the dropped list height will be decreased accordingly. Droplist enforces a minimum dropped list size of four rows, unless the list is smaller in size.

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

Example:

Init [

If 1 Main;

[

Choices = New(4);

Index = 0;

Choices[0] = "Open";

Choices[1] = "Close";

Choices[2] = "On";

Choices[3] = "Off";

]

Main [

System\DropList(10, 210, 210, 390 { Boundaries of list },

Choices { Data displayed },

"Match String" { Title },

Index { Highlighted index },

1, 1 { Focus ID, trigger },

0 { Editable field },

"Cancel" { Starting value },

Val { Variable to set },

0 { No bevel },

0 { Align top of list });

]

This shows an editable droplist without a bevel, with the top of the droplist itself at Y = 210; the title "Pick a String" is above it (i.e. beyond the top of the defined area). The initial value in the field, and thus the initial value of Val will be "Cancel"; when the list is first opened, the first array entry (element 0) will be highlighted. The trigger variable is not used.