@...LISTBOX
Create a GET object as a list, and display it.
------------------------------------------------------------------------------

 Syntax:

     @ <nRow>, <nCol> LISTBOX <var> TO <nMaxRow>, <nMaxCol>
                      WITH <aList>
                      [MESSAGE <cSayMessage>]
                      [MASTERVAR <xVar>]
                      [MASTERAREA <cAlias>]
                      [COLOR <cColorString>]
                      [ACTION <lAction>]
                      [WHEN <lPreCondition>]


 Arguments:

     <nRow> is the screen row of the top of the list.

     <nCol> is the screen column of the left side of the list.

     <var> is the variable into which the selection will be written.

     <nMaxRow> is the bottom row of the list (defaults to the length
     of the list).

     <nMaxCol> is the rightmost column of the list (defaults to the
     length of the longest list item).

     WITH <aList> is the single-dimensional array of items to be
     listed.  The array items may be of character, numeric, date
     or logical data type.

     MESSAGE <cSayMessage> is an optional character string to be
     displayed in the screen's message area.

     MASTERVAR <xVar> is an optional variable expression used to represent
     the original source of the get variable.  This can be used in conjunction
     with the OrigChanged() function which checks all current gets against
     their origin.

     MASTERAREA <cArea> is an optional database area/alias in which the
     <xVar> resides.  This defaults to the current work area.

     COLOR <cColorString> is the optional color string to be used
     for the list.  This string may have up to 7 color specifications
     as follows:

                1 - Border & background colour - GET unselected
                2 - Border & background colour - GET selected
                3 - Border & background colour - GET unavailable
                4 - Unselected data items - GET selected
                5 - Selected data items - GET selected
                6 - Unselected data items - GET unselected
                7 - Selected data items - GET unselected.

        Example: cListClr := "N/W*, B/W*, N/W*, W+/W, W+/R, N/W*, W/N"

        Default: "W/N, W+/N, W/N, W/N, N/W, W/N, W/N"

     ACTION <lAction> specifies an action expression to be executed
     when a list item is selected.  This expression must return a logical
     value.  If the expression returns .T., the READ proceeds normally.
     If it returns .F., the READ is terminated.

     WHEN <lPreCondition> specifies an expression that must be satisfied
     (evaluate to .T.) before the list will be activated.


 Description:

     @...LISTBOX creates and displays a GET object for selecting an
     item from a fixed list.  The selection list is passed in the
     form of a single-dimensional array.  If the array is empty, the
     GET system simply skips List Box, although it is still displayed.

     The List Box is activated by issuing a READ command, or by calling
     the READMODAL function.


 Active Keys:

        The following keys are used with the List Box:

            Up & Down arrows - Move up & down one line of the list
            PgUp & PgDn      - Up & down one page of the list
            Home             - Top of the list
            End              - Bottom of the list
            Enter            - Select the current item
            Esc              - Cancel the READ.


 Example:

 The following creates a list, displays it, and reads the selection:

 #include "CUACLIP.CH"
 #include "Inkey.ch"
 #include "Directry.ch"


 FUNCTION ListDemo

 LOCAL aDir,          ; // Directory info array
       aFiles,        ; // Files array for the List Box
       cFile,         ; // The file selected
       GetList,       ; // Getlist array
       i                // Loop counter

 GetList := {}
 aDir    := DIRECTORY( "*.*" )
 aFiles  := ARRAY( LEN( aDir ))
 cFile   := ""

 //
 // Load the files array...
 //
 FOR i := 1 TO LEN( aDir )
     aFiles[i] := PADR( aDir[ i, F_NAME ], 15 )
 NEXT

 @ 4,10 SAY "File List:" COLOR "W+/B"

 @ 5,10 LISTBOX cFile TO 15,35 WITH aFiles ;
        WHEN !EMPTY( aFiles ) ;
        COLOR "N/W, B/W, N/W, W+/W, W+/R, N/W, W/N"

 READ

 IF !__KillRead()
     ALERT( "You selected " + ALLTRIM( cFile ) )
 ENDIF

 RETURN ( NIL )


 Files:  Library is CUACLIP.LIB.