SplitList

(System Library)

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

Returns: Nothing

Usage: Steady State

Format: \System\SplitList(X1, Y1, X2, Y2, Title1, Title2, Data1, Data2, Index [, Picked, Flat, DoubleClick, MaxLen, Offset, FocusID, AlignTitle, Multi, PickList, SplitPos])

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

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

Y1 { numeric } { required } { no default: }

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

X2 { numeric } { required } { no default: }

Any numeric expression giving the X coordinate on the screen of the side of the listbox 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 listbox, whichever is the opposite to Y1.

Title1 { text } { required } { no default: }

Any text expression giving the title to be displayed above the first column of the splitlist.

Title2 { text } { required } { no default: }

Any text expression giving the title to be displayed above the second column of the splitlist.

Data1 { Array } { required } { no default: }

An array of data to be displayed in the first column of the splitlist. This array must be the same size as Data2.

Data2 { Array } { required } { no default: }

An array of data to be displayed in the second column of the splitlist. This array must be the same size as Data1.

Index { numeric } { required } { no default: }

Any variable whose value will be set to the index of the highlight.

Picked { numeric } { required } { no default: }

A variable whose value will be set true (1) when an item is chosen in the splitlist; the setting of Index by an external source will not trigger Picked.

Flat { Boolean } { required } { no default: }

Any logical expression; if true (non-0) the border of the splitlist will be a single black line, if false (0) it have the look of two indented windows.

DoubleClick { numeric } { optional} { no default: }

An optional parameter that is a variable whose value will be set to true (1) when an item has been double-clicked upon.

MaxLen { numeric } { optional } { default: see note }

An optional parameter that is any numeric expression giving the maximum length of the data lists; if omitted, the maximum list length is given by the size of the arrays Data1 and Data2.

Offset { numeric } { optional } { no default: }

An optional parameter that is any numeric expression giving the starting offset in the list; the element indicated by this index will be the one initially shown at the top of the list (unless too few elements follow this one to fill the display area).

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 splitlist will not accept keyboard input, although mouse input will still be recognized. The default value is 1.

AlignTitle { Boolean } { optional } { default: true }

An optional parameter that is any logical expression; if true (non-0) the title is drawn within the splitlist's boundaries, if false(0) the list fills its bounding area and the title is added at the top (i.e. it extends past the top boundary). The default is true.

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

SplitPos { numeric } { optional } { default: centered }

A n optional parameter that is a variable that will contain the pixel position of the split bar. If initially valid, the split bar will be in the middle of the SplitList.

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\SplitList(20, 325, 340, 50 { Outline of splitlist },

NameLabel { Column 1 title },

TypeLabel { Column 2 title },

NameTable { Column 1 data },

TypeTable { Column 2 data },

Index { Highlighted element },

0 { Picked not required },

0 { 3D look },

DClick { Set for double click },

Invalid { Use default max length },

0 { Start at top of list },

3 { Focus ID },

0 { Title extends past top });