Scroll Lists

A scroll list is a sub-window of the dialog box in which the user views and selects from a list of values. If there are more values than fit in the window, the scroll list displays a scroll bar that allows the user to view them all. The format of a scroll list item definition is:

Scroll List {"item name"} hpos, vpos {, width {, height}} {options} {do

endItem}

If the do ... endItem section of the scroll list definition is included, the statements are executed whenever the user changes the selection in the scroll list or double-clicks on a selection in the scroll list (see the Variables option below). The statements are not executed when the user views items using the scroll bar. If the width is not specified, the scroll list is twenty characters wide. If the height is not specified, the scroll list is four lines high.

Scroll List Options	Description
Key: hotkey	The key sequence the user can press to move the keyboard focus to the scroll list item instead of using the mouse. The hotkey has the format alt_character, where character must be a letter or number. For example, Key: alt_A indicates that holding the Alt key and pressing A activates the item. The specified key is underlined in the item's text. A hotkey only works if the key in question is part of the item's text and is case insensitive.
Disabled	The scroll list is initially disabled.
Hidden	The scroll list is initially hidden.
Help: help_specs	Help information displayed in a popup window and the status bar. Help strings can be string expressions.
Menu: array	Provides a context-sensitive menu when the user right-clicks on an item in the control. The value of the menu options is an array, each of whose elements corresponds to an item in the menu to be displayed and which is itself an options array; for more information, see Dialog Box Items.
Prompt: expression	The text that appears to the left of the scroll list. If omitted, there is no text next to the scroll list.
List: array	An array of items displayed in the scroll list. The array can contain strings, integers, real numbers, and sample objects, or can be a formatting array, described below.
Multiple	Allows the user to select more than one item in the scroll list. If Multiple is not specified, the user can select only one item in the scroll list at a time.
Variables: variables	The first variable indicates the user's selection. If Multiple is not specified, this is an index into the List array. If Multiple is specified, the first variable is set to an array of indices into the List array. If only one variable is specified, use the option Variable instead of Variables.
	The second variable indicates whether the user clicked or double-clicked on the scroll list. If no second variable is specified, a double-click causes the statements in the do ... endItem section to be executed once. If a second variable is specified, a double-click causes the statements to be executed once with the variable set to zero, and then again with the variable set to one. A single click causes the statements to be executed once with the variable set to zero. In general, a double-click should be treated as though the user clicked once and then pressed the default button.
	The third variable indicates which column the user clicked in when List is specified using the multi-column format, or 0 if the user did not click inside any of the columns.

For example:

Scroll List 0, 0, 30, 6 List: names Variables: name_index

Normally, the array specified with the List option is an array of strings, integers, real numbers, or sample objects. For certain applications, however, it may be necessary for a scrolling list to contain multiple columns of values. A formatting array is used to describe a multi-column scrolling list. In a formatting array, each element is an array of column values, where each column value is an array of four elements of the form:

{position, format_string, value_to_display, format_options}

The position is a distance in character widths from the left side of the scroll list. The value_to_display is a string, integer, real number, or sample object. The format_string depends on the type of the value, but all format strings begin with an alignment character.

Alignment Character	Meaning
L	The position is the left edge of the displayed value.
R	The position is the right edge of the displayed value.
C	The position is the middle of the displayed value.

Type of Value	Format String
Integer	An alignment character followed by a numeric format, like that passed to Format()
Real Number	An alignment character followed by a numeric format, like that passed to Format()
String	An alignment character by itself
Sample Object	An alignment character followed by the number of characters in which to display the object. Most sample objects expand to fill the space provided for them.

The format_options are an options array that applies only if the type of value is String, Integer or Real, not Sample Object. It is not required. It can contain the following options for displaying the item:

Format Option	Type	Contents
Color	Color	The color for drawing the item.
Bold	Boolean	If True then draw in bold; default is False
Italic	Boolean	If True then draw in italic; default is False

For example, a column value of {15, "R$*,.00", 1234.5} results in $1,234.50 displayed with its right edge fifteen characters from the left side of the scroll list. A complete formatting array looks like this:

dim fmt_arr[3]

fmt_arr[1] = {{8, "L", "Boston"}, {15, "R*.##", 10,{{"Bold, "True"}}}}

fmt_arr[2] = {{8, "L", "Troy"}, {15, "R*.##", 6.5}}

fmt_arr[3] = {{8, "L", "Redlands}, {15, "R*.##", 2.75}}