DropList

(System Library)

Description:	Draws a droplist with (optional) title or bevel or both.
Returns:	Nothing
Usage:	Steady State only.
Function Groups:	Graphics
Related to:	Bevel \| CheckBox \| ColorSelect \| DropTree \| Edit \| GridList \| HScrollbar \| Listbox \| RadioButtons \| SpinBox \| SplitList \| ToolBar \| VScrollbar
Format:	\System.DropList(X1, Y1, X2, Y2, Data, Title, Index, FocusID, Trigger, NoEdit, Init, Variable [, DrawBevel, VertAlign, AlignTitle, Style, BGColor, FGColor, FontParm, Title])
Parameters:

Required. Any numeric expression giving the X coordinate on the screen of one side of the droplist.

Required. Any numeric expression giving the Y coordinate on the screen of either the top or bottom of the (opened) droplist.

Required. Any numeric expression giving the X coordinate on the screen of the side of the droplist opposite to X1.

Required. 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

Required. An array of data to display in the droplist.

Title

Required. Any text expression to be used as a title for the droplist.

Index

Required. 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

Required. Any numeric expression from 0 to 32767 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.

Trigger

Required. If the droplist is editable, Trigger provides feedback. While editing, the value will be 0. When editing is complete (tab, enter or loss of focus) the value will change to non-zero; 1 if enter is pressed, 2 otherwise.
If this information is not required and the next parameter is used, a value of invalid or a constant may be substituted.

NoEdit

Required. 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.

Options of the Style parameter may conflict with this parameter, if configured. In this case, the Style parameter will be used and the NoEdit parameter will be ignored.

If the provided variable is declared but left INVALID (i.e. a C++ BASEVALUE class) then NoEdit will default to TRUE.
If the NoEdit parameter is set directly to INVALID (a C++ VALUE class) then NoEdit will default to FALSE.

Init

Required. 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

Required. The variable whose value is set by the droplist.

The maximum number of characters that a user can provide is 65535.

DrawBevel

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

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 the title is included when the vertical alignment is calculated is determined by the value of AlignTitle. The default value is 0.

AlignTitle

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

Comprised of a combination of bit values to yield the desired effects.
Bits 0 and 1 define mutually exclusive styles of operation. They can be set to one of the following values:

Bit Number	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 and 3 define input character handling. If neither is set, input is passed to script code as typed.

Bit Number	Definition
2	Input is converted to all uppercase.
3	Input is converted to all lowercase.

Bit 4 controls list sorting.

Bit Number	Definition
4	The list is presented in sorted order to the user.

Bit 8 enables Windows visual styles.

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

Bit Number	Definition
9	Enable application-defined geometry.

BGColor

Optional. Any numeric expression for the background color of the control. No default value.

FGColor

Optional. Any numeric expression for the foreground color of the control. No default value.

FontParm

Optional font value.

TitleBGColor

Optional. Background color under the title.

TitleFGColor

Optional. Foreground (text) color for the title.

BevelColor

Optional. Color of the bevel line.

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\

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.

Droplist may not be wrapped in a GUITransform.

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.