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

     @ <nRow>, <nCol>
        [SAY <exp>
           [PICTURE <cSayPicture>]
           [COLOR <cColorString>]]
        GET <idVar>
           [PICTURE <cGetPicture>]
           [COLOR <cColorString>]
           [CAPTION<cCaption>]
           [MESSAGE <cMessage>]
           [WHEN <lPreExpression>]
           [RANGE* <dnLower>, <dnUpper>] |
           [VALID <lPostExpression>]
           [SEND <msg>]
           [GUISEND <guimsg>]

 Arguments

     <nRow> and <nCol> specify the row and column coordinates for the
     operation.  If the SAY clause is present, <nRow> and <nCol> specify the
     coordinates for the SAY, and the GET is displayed to the right of the
     SAY output.  If the SAY clause is not present, <nRow> and <nCol>
     directly specify the coordinates for the GET.  In either case, output
     which extends beyond the visible extent of the display is clipped and
     does not appear.

     SAY <exp> displays the value of <exp> at the specified coordinates.
     If you specify the PICTURE <cSayPicture> clause, <exp> is formatted
     according to the rules of SAY pictures.

     GET <idVar> specifies the name of the variable associated with the
     GET.  <idVar> may be of any storage class (if the storage class is
     ambiguous, FIELD is assumed).  If <idVar> contains an array value, you
     must supply one or more subscripts.  The current value of <idVar> is
     displayed at the GET coordinates.  The value must be character, date,
     numeric, or logical type.  Array, NIL, code block, and null string
     values are not permitted.

     PICTURE <cGetPicture> specifies the display format and editing rules
     for the GET.

     COLOR <cColorString> defines the color settings for the current Get
     object.  <cColorString> is a character expression containing one or more
     color settings.  You must specify literal color settings enclosed in
     quote marks.

     If you specify two color settings, the first determines the unselected
     color (the display color for the Get object) and the second determines
     the selected color (the color when the Get object has focus).  If you
     only specify one color, it determines both the unselected and selected
     colors for the Get object.

     On a combined @...SAY...GET command, two COLOR clauses are required to
     specify colors for both the SAY and the GET: one for the SAY, and one
     for the GET.

     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 right of the GET.  Use the Get object's capRow or capCol
     variable to change the screen position of the caption.  Note that if the
     SAY clause is used, the CAPTION clause is ignored.

     When present, the & character specifies that the character
     immediately following it in the caption is the GET'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 GET.  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 SET MESSAGE 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.

     RANGE* <dnLower>, <dnUpper> specifies a range of allowable
     values for input to the GET.  During a READ command, if you enter a new
     GET value that does not fall within the specified range, the cursor
     cannot leave the GET.

     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.

     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.

 Description

     The @...GET command creates a new Get object, displays its value, and
     adds it to the array referred to by the variable GetList.  If no
     variable called GetList has been declared or created in the current
     procedure, and no PRIVATE variable called GetList exists from a previous
     procedure, the system uses the predefined PUBLIC variable GetList.  A
     subsequent READ command activates the GETs contained in the GetList
     array and allows the user to edit their contents.

     Each Get object has an associated variable, <idVar>.  The variable may
     be of any storage class, including a database field, private, public,
     local, or static variable.  If <idVar> is followed by one or more
     subscripts, the specified array element is associated with the GET.
     When the Get object is created, the <idVar> name is stored in the Get
     object, along with a code block which allows the value of <idVar> to be
     retrieved or assigned during the READ.

     The READ command performs a full-screen edit of the GETs in the GetList
     array.  As the user moves the cursor into each GET, the value of the
     associated <idVar> is retrieved by evaluating the code block saved in
     the Get object.  The value is converted to textual form and placed in a
     buffer within the Get object.  This buffer is displayed on the screen,
     and the user is allowed to edit the text from the keyboard.  When the
     user moves the cursor out of the GET, the updated buffer is converted
     back to the appropriate data type and assigned to <idVar>.

     Automatic formatting and validation: During a READ, some formatting
     and edit validation is automatically performed for numeric, date, and
     logical values.  As the user is typing, an automatic data type test is
     performed on each key pressed, preventing the user from entering an
     invalid character.

     Prevalidation: The WHEN clause specifies a condition which must be
     satisfied before the cursor can enter the GET.  During a READ,
     <lPreExpression> is evaluated whenever the user attempts to move the
     cursor into the GET.  If it evaluates to true (.T.), the cursor can
     enter; otherwise, the GET is skipped.

     Postvalidation: You may perform postvalidation using either the
     VALID or RANGE* clauses.  VALID specifies a condition which must be
     satisfied before the cursor can leave the GET.  During a READ,
     <lPostExpression> is evaluated whenever the user attempts to move the
     cursor out of the GET.  If it evaluates to true (.T.), the cursor can
     leave; otherwise, the cursor remains in the GET.  RANGE* specifies a
     range of acceptable values for numeric or date values.  If the value
     entered by the user is not within the specified range, the cursor cannot
     leave the GET.