@...STANDARD
 Create a GET object and display it.
------------------------------------------------------------------------------

 Syntax:

     @ <nRow>, <nCol>
        [SAY <exp>
           [PICTURE <cSayPicture>]
           [COLOR <cColorString>]]
        GET <idVar>
           [PICTURE <cGetPicture>]
           [COLOR <cColorString>]
           [WHEN <lPreCondition>]
           [VALID <lPostCondition>]
           [USING STANDARD]
           [LIST <aList> | DBLIST <aDBList> | USERLIST <bUserList>]
           [MASTERVAR <xVar>]
           [MASTERAREA <cArea>]
           [HIDDEN]
           [MESSAGE <cSayMessage>]
           [SEND <xMessage>]

 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 the PICTURE <cSayPicture> clause is specified, <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, one
     or more subscripts must be supplied.  The current value of <idVar> is
     displayed at the GET coordinates.  The value must be character, date,
     numeric, or logical type.  Array, NIL, and code block values are not
     allowed.

     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.  Literal color settings must be
     specified enclosed in quote marks.

     If three color settings are present, the first determines the
     unselected color (the display color for the Get object), the second
     determines the selected color (the color when the Get object has
     focus) and the third is used for the failed WHEN color.  If only one
     color is specified, it determines both the unselected and selected
     colors for the Get object.

     On a combined @...SAY...GET command where colors are specified for
     both the SAY and the GET clause, two COLOR clauses are required;
     one for the SAY, one for the GET.

     WHEN <lPreCondition> specifies an expression that must be satisfied
     before the cursor will be allowed to enter the GET during a READ.

     VALID <lPostCondition> specifies an expression that must be
     satisfied before the cursor will be allowed to leave the GET during a
     READ.

     HIDDEN is flag used to indicate the data is to be hidden when the
     <lPreCondition> evaluates to FALSE.  (see the WHEN clause explanation).

     MESSAGE <cSayMessage> attaches the <cSayMessage> to the get so it
     may be displayed whenever the GET is infocus and the SET MESSAGE TO has
     been set to a number greater than 0.

     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.

     SEND <xMessage> is used to send (:) a message to the get object.

     LIST <aList> is an array of choices to be used as a popup.  The popup
     expects all array elements to be formatted to the same width and type as
     the get data element it is LISTed for.

     DBLIST <aDBlist> is an array which describes a database, expression,
     etc. to display in a popup.  Six elements are used (all six must be
     present with optional ones skipped as NIL

     eg.  { "employee",,, { || field->name } }

         1 - character name of DBF or codeblock which returns a character
             name of DBF
         2 - OPTIONAL: character name of index or codeblock which returns
             a character name of index
         3 - OPTIONAL: codeblock seek expression
             NOTE: Can only be used if option 2 is present.
         4 - codeblock representing the return expression
         5 - OPTIONAL: codeblock representing the display expression
             NOTE: Defaults to number 4.
         6 - OPTIONAL: codeblock used to convert the data on SEEKs.  The
             codeblock receives a copy of the data and must return a
             converted expression.  EXAMPLE: the index is on the UPPER()
             value of the data so the codeblock would look like
             { | x | UPPER( x ) }.
             NOTE: Can only be used if option 2 is present.

     USERLIST <bUserList> is a custom user defined process.


 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 predefined PUBLIC variable GetList is used.  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, specified by <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 type test is
     performed on each key pressed, preventing the user from entering an
     invalid character.

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

     Post-validation: Post-validation may be performed using either the
     VALID or RANGE* clauses.  VALID specifies an condition which must be
     satisfied before the cursor is allowed to leave the GET.  During a
     READ, <lPostCondition> is evaluated whenever the user attempts to move
     the cursor out of the GET.  If it evaluates to true (.T.), the cursor
     is allowed to leave; otherwise, the cursor remains in the GET.  RANGE*
     specifies a range of acceptable values for numeric or date values.  If
     the new value entered by the user is not within the specified range,
     the cursor is not allowed to leave the GET.

     PICTURE: When the PICTURE clause is specified for a GET, the
     character string specified by <cGetPicture> is used to control
     formatting and edit validation.  The picture string controls the
     display format in a fashion similar to a SAY picture.  It also controls
     the way in which the user is allowed to edit the buffer.  A picture
     string consists of two distinct parts, either or both of which may be
     present:  a function string and a template string.

     .  Function string: A PICTURE function string specifies formatting
        or validation rules which apply to the GET's display value as a
        whole, rather than to particular character positions within it.  The
        function string consists of the @ character, followed by one or more
        additional characters, each of which has a particular meaning (see
        table below).  If a function string is present, the @ character must
        be the left-most character of the picture string, and the function
        string must not contain spaces.  A function string may be specified
        alone or with a template string.  If both are present, the function
        string must precede the template string, and the two must be
        separated by a single space.

     .  Template string: A PICTURE template string specifies formatting
        or validation rules on a character by character basis.  The template
        string consists of a series of characters, some of which have
        special meanings (see table below).  Each position in the template
        string corresponds to a position in the displayed GET value.
        Characters in the template string which do not have assigned
        meanings are copied verbatim into the displayed GET value.  If the
        @R picture function is used, these characters are inserted between
        characters of the display value, and are automatically removed when
        the display value is reassigned to <idVar>; otherwise, they
        overwrite the corresponding characters of the display value and also
        affect the value assigned to <idVar>.  A template string may be
        specified alone or with a function string.  If both are present, the
        function string must precede the template string, and the two must
        be separated by a single space.

     Exit with Esc: If the user exits a GET by pressing Esc, the GET
     variable is restored to the value it had on entry to the GET, and the
     READ is terminated.  No post-validation is performed.  This behavior
     can be enabled or suppressed with the SET ESCAPE command.

     SET KEY procedures: The SET KEY command allows you to specify a
     procedure to be executed whenever a specified key is pressed during a
     READ.  After a SET KEY procedure terminates, the GET is reactivated
     with the cursor restored to its previous position.

     Lifetime of a Get object: Get objects, like arrays, exist as long
     as there are active references to them somewhere in the current
     program.  Normally, only the array in the GetList variable maintains a
     reference to the Get object; the GET is released when GetList is
     released or reassigned.  The CLEAR and CLEAR GETS commands assign an
     empty array to GetList, as does the READ command unless the SAVE clause
     is specified.

     Assignment: Each GET is associated with a variable, specified by
     <idVar> in the @...GET command.  At various times during the editing
     process, <idVar> may be assigned the current value of the Get object's
     buffer.  This occurs in the following instances:

     .  After the user presses an exit key and before the validation
        expression is executed

     .  After the user presses a SET KEY

     Likewise, the current Get object's buffer is refreshed from <idVar> and
     re-displayed at various intervals:

     .  After a SET KEY procedure terminates

     .  After a WHEN expression is evaluated

     .  After a VALID expression is evaluated

     This allows you to explicitly assign <idVar> within any of these
     operations.  See the note below for more information.

     GET coordinates and display: When a Get object is created using the
     @...GET command, the row and column coordinates at which the GET is
     initially displayed are stored into the Get object.  When the @...GET
     command is executed, the new GET displays at <nRow> and <nCol>, unless
     the SAY clause is specified.  If it is, the GET is positioned such that
     there is one display column between the last character of the SAY
     output and the first character of the GET (or of the DELIMITERS, see
     below).

     If SET DELIMITERS is ON when the @...GET command is executed, the
     current DELIMITER characters are displayed on either side of the
     initial GET display, and the column coordinate of the GET is adjusted
     accordingly.  Note that the delimiters are not attributes of the GET
     object, but simply display as the SAY clause does.

     When a GET is displayed, the width of the displayed value is determined
     by the length of the value in <idVar> or, if the PICTURE clause is
     specified, by the number of positions specified by <cGetPicture>.  If
     the @S function is specified as a part of <cGetPicture>, the width of
     the displayed value is controlled by the @S argument.

 Notes:

     .  WHEN and VALID: The expressions specified in the WHEN and VALID
        clauses may be of arbitrary complexity and may include calls to
        user-defined functions.  This is useful for attaching automatic
        actions to the activation or deactivation of a GET.

     .  Assigning <idVar>: Because of the automatic refresh and display
        properties of a Get object while it is being READ, you can make an
        explicit assignment to the Get object's <idVar> within a WHEN or
        VALID expression.  The variable can be directly assigned by name in
        the validation expression or, for private, public, local, or static
        variables, by passing a reference to <idVar> to a function; the
        function can then assign <idVar> by assigning the corresponding
        formal parameter.  If <idVar> is a field, it is globally visible and
        can be assigned by name in a function called by the validation
        expression.

     .  GET specific help: Help text associated with a Get object can be
        displayed using a SET KEY procedure.  Within the SET KEY procedure,
        use the READVAR() function to determine the <idVar> associated with
        the current Get object.  Then use this information to display the
        appropriate help text.  Remember that when a  Clipper compiled
        program loads, the F1 KEY is automatically SET TO a procedure or
        user-defined function named Help.

     .  SET DEVICE TO PRINTER: The display of a Get object with the
        @...GET command is not directed to the printer or file if SET DEVICE
        is TO PRINTER.

 Examples:

     .  The following example demonstrates use of the VALID clause to
        validate input into a GET:

        LOCAL nNumber := 0
        @ 10, 10 SAY "Enter a number:" GET nNumber VALID nNumber > 0

     .  This example shows how the WHEN clause can be used to prohibit entry
        into GETs based on the value of another GET.  In this example,
        entering Y in the Insured field indicates the client has insurance
        and the user is allowed to enter insurance information.  If the
        client does not have insurance, the cursor moves to the Accident
        field:

        @ 10, 10 GET Insured PICTURE "Y"
        @ 11, 10 GET InsNumber WHEN Insured
        @ 12, 10 GET InsCompany WHEN Insured
        @ 13, 10 GET Accident PICTURE "Y"
        READ

     .  The following is an example of a GET in a secondary work area:

        USE Invoice NEW
        APPEND BLANK
        USE Inventory NEW
        @ 1, 1 GET Invoice->CustNo
        READ

     .  This example demonstrates the @K function to suggest a default input
        value, but deletes it if the first key pressed is not a cursor key
        or Return:

        LOCAL cFile := "Accounts"
        @ 1, 1 SAY "Enter file" GET cFile PICTURE "@K"
        READ

 Files:  Library is CUACLIP.LIB, header is CUACLIP.CH.