+---------------------------------+
|        @ ... GET - Lists        |
+---------------------------------+
@ <row, column> GET <var> | <field>
        [FUNCTION <expC1>]
        | [PICTURE <expC2>]
        FROM <array>
        [RANGE <expN1> [, <expN2>]]
        | POPUP <popup name>
        [DEFAULT <expr>]
        [SIZE <expN3>, <expN4>]
        [ENABLE | DISABLE]
        [MESSAGE <expC3>]
        [VALID <expL1>]
        [WHEN <expL2>]
        [COLOR SCHEME <expN5>
        | COLOR <color pair list>]

-----------------------------------
Creates a list.
-----------------------------------

A list contains items you can choose from.  To choose an item, select it
and press Enter or double click on the desired item.

On the screen, a list is a vertical list of items inside a box, often
with a scroll bar to the right.  The scroll bar lets you move quickly
through the items with the mouse and provides a visual indication of
your position in the list.  Another quick way to move around in the list
is to press the Home key to go to the first item, or the End key to go
to the last item.  This method works regardless of whether the list has
a scroll bar.

The items in the list are obtained from an array or a popup.  Include
FROM <array> to build the list from an array.  Include POPUP <popup
name> to build the list from a popup that was created with DEFINE POPUP.
You must include FROM or POPUP but not both.  Issue READ to activate the
list.

Clauses
-------

<row, column>
        Numeric coordinates (zero or greater) that specify upper left corner of
list.

GET <var> | <field>
        Memory variable, array element or database field where item choice is
stored.  Must be numeric or character.  If Escape pressed, <var> remains
unchanged.

Initial Option Selection
        Value of <var> determines which list option (if any) is initially
selected.  If <var> doesn't correspond to any of the options in the list
(the value is less than one or greater than the number of options), no
option is selected.

FUNCTION <expC1> | PICTURE <expC2>
        Permissible function codes are:

        &T      List terminates READ.  If PICTURE used, precede codes with @.

        &N      List doesn't terminate READ.

FROM <array>
        Builds list from an array.  The array can be one or two-dimensional.
If the array is one-dimensional, the first element of the array is the
first option in the list, the second array element is the second item
and so on.

        If the array is two-dimensional, the elements in the first column of
the array are used to build the list.  The first element in the array is
the first item in the list, the second element in the same array column
as the first element is the second item and so on.

RANGE <expN1> [, <expN2>]
        Designates different starting element in array.

POPUP <popup name>
        Creates list by using items from popup created with DEFINE POPUP.

DEFAULT <expr>
        Creates memory variable if one specified does not exist.

SIZE <expN3>, <expN4>
        <expN3> specifies length in rows; <expN4> specifies width in columns.

ENABLE | DISABLE
        Allows or prevents activation of list when READ is issued.

MESSAGE <expC3>
        Displays <expC3> when list item is selected.

VALID <expL1>
        Evaluated when a list option is chosen.  Typically, <expL1> is a UDF.

WHEN <expL2>
        Evaluated when you first select an item.  Often, <expL2> is a UDF.

COLOR SCHEME <expN5>
| COLOR <color pair list>
        Overrides current color scheme by specifying a different predefined
color scheme, or by specifying a list of color pairs.

        Color Pair Controls
        1       Disabled option
        2       Enabled option
        3       Border and scroll bar*
        4       Not used by lists
        5       Message
        6       Selected list item
        7       Not used by lists
        8       Not used by lists
        9       Enabled list
        10      Disabled list

        * Controls drawn in background color.  Bar drawn in dim of foreground
color.

+---------------------------------+
|             Examples            |
+---------------------------------+
***** List created from popup
CLEAR
SET TALK OFF
STORE 1 TO mchoice

DEFINE POPUP scrollopts FROM 0,0 PROMPT FILES LIKE *.DBF ;
        MARK CHR(16) MARGIN SCROLL

@ 2,2 GET mchoice POPUP scrollopts SIZE 8,20

READ    && Activate the list

***** Override color defaults
CLEAR
SET TALK OFF
STORE 1 TO mchoice

DEFINE POPUP scrollopts FROM 0,0 PROMPT FILES LIKE *.DBF ;
        MARK CHR(16) MARGIN SCROLL COLOR SCHEME 4

@ 2,2 GET mchoice POPUP scrollopts SIZE 8,20

READ    && Activate the list

*       Defines a list with the following color characteristics:
*               selected list item      bright white on a blue background (W+/B)
*               enabled                         yellow options on a blue background (GR+/B)
*               disabled                        white options on a blue background (W/B)
CLEAR
SET TALK OFF
STORE 1 TO mchoice

DEFINE POPUP scrollopts FROM 0,0 PROMPT FILES LIKE *.DBF ;
        MARK CHR(16) MARGIN SCROLL COLOR ,GR+/B,,,,W+/B,,,,W/B

@ 2,2 GET mchoice POPUP scrollopts SIZE 8,20

READ    && Activate the list

+---------------------------------+
|         Program Example         |
+---------------------------------+
SET TALK OFF