Click above to get retro games delivered to your door ever month!

 @...GET LISTBOX
 Create a new list box Get object and display it to the screen
------------------------------------------------------------------------------
 Syntax

     @ <nTop>, <nLeft>, <nBottom>, <nRight>
        GET <nVar|cVar>
        LISTBOX <aList>
           [CAPTION<cCaption>]
           [MESSAGE <cMessage>]
           [WHEN <lPreExpression>]
           [VALID <lPostExpression>]
           [COLOR <cColorString>]
           [FOCUS <fblock>]
           [STATE <bBlock>]
           [DROPDOWN]
           [SCROLLBAR]
           [SEND <msg>]
           [GUISEND <guimsg>]
           [BITMAP <cBitmap>]

 Arguments

     <nTop>, <nLeft>, <nBottom> and <nRight> specify the
     screen position for the list box and its caption.  Output which extends
     beyond the visible extent of the display is clipped and does not appear.

     GET <nVar|cVar> specifies the name of the variable associated with
     the GET.  Its value indicates which item (if any) in the list is
     selected.  A numeric value refers to the position in the list of the
     selected item.  A value of 0 indicates no selected item.  A character
     string value refers to the data or text contained within the selected
     item.  A character string that does not refer to any item in the list
     indicates no selected item.

     LISTBOX <aList> specifies an array that contains the items in the
     list.  The array may be either a single- or two-dimensional array.  Use
     a single-dimension array when the data being displayed is the same as
     the data being saved; otherwise, use a two-dimensional array.  In this
     case, the data in the first element of each subarray is displayed and
     the data in the second element is used for determining which item is
     selected.

     CAPTION <cCaption> specifies a character string that concisely
     describes the GET on the screen.  Caption differs from the SAY argument
     in two ways.  The first is that the caption is displayed each time the
     GET is shown on the screen.  The other difference is that the caption,
     along with its screen position, is maintained within the Get object.
     This allows the GET to receive input when the mouse's left button is
     clicked and its cursor is on the caption.  By default, the caption
     appears to the left of the GET.  Use the Get object's capRow or capCol
     variable to change the screen position of the caption.

     When present, the & character specifies that the character
     immediately following it in the caption is the list box's accelerator
     key. The accelerator key provides a quick and convenient mechanism for
     the user to move input focus from one data input control to the list
     box.  The user performs the selection by pressing the Alt key in
     combination with an accelerator key.  The case of an accelerator key is
     ignored.

     MESSAGE <cMessage> specifies a character string that is displayed on
     the Get system's status bar line when the GET has input focus.
     Typically, it describes the anticipated contents or user response of the
     GET.  Refer to the READ command for details pertaining to the Get
     system's status bar.

     WHEN <lPreExpression> specifies an expression that must be satisfied
     before the cursor can enter the GET during a READ.  The expression can
     optionally be a code block.  The Get object is passed as a parameter to
     the code block.

     VALID <lPostExpression> specifies an expression that must be
     satisfied before the cursor can leave the GET during a READ.  The
     expression can optionally be a code block.  The Get object is passed as
     a parameter to the code block.

     COLOR <cColorString> defines the color settings for the list box.
     <cColorString> is a character expression containing exactly seven color
     settings if there is no drop-down list box, and eight if there is a
     drop-down list box.

     ListBox Color Attributes
     ------------------------------------------------------------------------
     Position     Applies To                             Default Value from
     in colorSpec                                        System Color Setting
     ------------------------------------------------------------------------
     1            List box items that are not selected     Unselected
                  when the list does not have input focus
     2            The selected list box item when the      Unselected
                  List does not have input focus
     3            List box items that are not selected     Unselected
                  when the list has input focus
     4            The selected list box item when the      Enhanced
                  list has input focus
     5            The list box's border                    Border
     6            The list box's caption                   Standard
     7            The list box caption's accelerator key   Background
     8            The list box's drop-down button          Standard
     ------------------------------------------------------------------------

     Note:  In graphic mode, colorSpec position 8 has no affect and is
     ignored.

     FOCUS <fblock> specifies a code block that is evaluated each time
     the list box receives focus.  The code block takes no implicit
     arguments.  Use the PushButton:hasFocus instance variable to determine
     if the push button has focus.

     STATE <bBlock> specifies a code block that is evaluated immediately
     after the list box object's selection changes.  The code block takes no
     implicit arguments.  Use the ListBox:buffer instance variable to
     determine the current selection.

     DROPDOWN indicates that the list box will be a drop-down list box.
     Drop-down list boxes are displayed differently on the screen than
     regular list boxes.  A regular list box is always displayed regardless
     of whether it has input focus.  A drop-down list box's display behavior
     is determined by whether it is closed or open.  By default, a drop-down
     list box is closed.  In this case, only the caption, the selected item,
     and the open button are displayed.

     When open, the actual list box is displayed in addition to the caption,
     selected item, and open button.

     Drop-down list boxes are useful in situations where screen space is
     limited.

     SCROLLBAR indicates that the list box will be created with a scroll
     bar whether or not it is needed.  Normally a scroll bar is not needed if
     the data being displayed fits inside the list box.

     SEND <msg> sends the specified message to the Get object.  <msg> is
     sent before the GET is displayed.  Any message can be sent, including
     method calls and instance variable assignments.  Method calls must
     include parentheses even if no arguments are passed.

     GUISEND <guimsg> can be used to send a message (such as the
     display() method) to a GUI object.  The GUI objects available in
     CA-Clipper are check boxes, list boxes, push buttons, and radio button
     groups.  To send a message to a non-GUI object, such as standard GETs
     and TBrowses, use the SEND clause.

     BITMAP <cBitmap> defines the bitmap that will be used as the down
     arrow on a drop-down list box.  Drive and directory names are not
     allowed; the file name extension is required.  A bitmap file can be
     stored as a file on disk or in a bitmap library.  If stored as a file,
     the file must reside in the same directory as the application.  If
     stored in a bitmap library, the library must reside in the same
     directory as the application and it also must have the same name as the
     application with a .bml extension.

     CA-Clipper will search for the file name first and, if it is not found,
     search in the bitmap library second.  If no file is found either on disk
     or in the library, no bitmap will be displayed.

 Examples

     .  This example demonstrates how to add a list box to a data
        entry screen.  It utilizes the position-oriented method of selection:

        nColor := 1     //default to the first item.
        @ 5, 20, 8, 28 GET nColor LISTBOX { "Red", Green", "Blue" }

     .  This example demonstrates a list box that has a caption and a
        message.  It utilizes the data-oriented method of selection:

        cColor := "Red" //default to red.
        @ 5, 20, 8, 28 GET cColor LISTBOX { "Red", Green", "Blue" };
                CAPTION "&Color" ;
                MESSAGE "Select the background color"

     .  This example demonstrates a list box that utilizes a two-
        dimensional array.

        cState := "NY"

        @ 5, 20, 10, 30 GET cState LISTBOX { { "Alabama", "AL" }, ;
                                     { "Alaska", AK" }   , ;
                                     { "Arizona", "AZ" }, ;
                                     { etc...          } } ;
                CAPTION "&State" ;
                MESSAGE "Select the client's state"

 Files   Library is CLIPPER.LIB.