@...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
     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.

     Note:  You may specify either a VALID or RANGE clause, but not both.

     PICTURE: When you specify the PICTURE clause for a GET, the
     character string specified by <cGetPicture> controls formatting and edit
     validation.  The picture string controls the display format like a SAY
     picture.  It also controls the way the user can edit the buffer.  A
     picture string consists of two distinct parts, a function string and a
     template string, either or both of which may be present.

     .  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 the following table).  The function string must be the first
        element of a PICTURE clause and cannot 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.

        GET PICTURE Format Functions
        ---------------------------------------------------------------------
        Function     Type Action
        ---------------------------------------------------------------------
        A            C    Allows only alphabetic characters.
        B            N    Displays numbers left-justified.
        C            N    Displays CR after positive numbers.
        D            D,N  Displays dates in SET DATE format.
        E            D,N  Displays dates with day and month inverted
                          independent of the current DATE SETting, numerics
                          with comma and period reverse (European style).
        K            ALL  Deletes default text if first key is not a cursor
                          key.
        R            C    Nontemplate characters are inserted in the display
                          but not saved in the variable.
        S<n>         C    Allows horizontal scrolling within a GET.  <n> is
                          an integer that specifies the width of the region.
        X            N    Displays DB after negative numbers.
        Z            N    Displays zero as blanks.
        (            N    Displays negative numbers in parentheses with
                          leading spaces.
        )            N    Displays negative numbers in parentheses without
                          leading spaces.
        !            C    Converts alphabetic character to uppercase.
        ---------------------------------------------------------------------

     .  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 the following table).  Each position in
        the template string corresponds to a position in the displayed GET
        value.  Characters in the template string that do not have assigned
        meanings are copied verbatim into the displayed GET value.  If you
        use the @R picture function, 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>.  You may specify a template string alone
        or with a function string.  If you use both, the function string must
        precede the template string, and the two must be separated by a
        single space.

        GET PICTURE Template Symbols
        ---------------------------------------------------------------------
        Template     Action
        ---------------------------------------------------------------------
        A            Allows only alphabetic characters
        N            Allows only alphabetic and numeric characters
        X            Allows any character
        9            Allows digits for any data type including sign for
                     numerics
        #            Allows digits, signs and spaces for any data type
        L            Allows only T, F, Y or N
        Y            Allows only Y or N
        !            Converts an alphabetic character to uppercase
        $            Displays a dollar sign in place of a leading space in a
                     numeric
        *            Displays an asterisk in place of a leading space in a
                     numeric
        .            Displays a decimal point
        ,            Displays a comma
        ---------------------------------------------------------------------

     SCOREBOARD: If a new value is rejected because it fails the RANGE*
     test or because it is a malformed date value, a message appears on the
     screen.  The message displays in the SCOREBOARD area, which you can
     enable or disable using the SET SCOREBOARD command.

     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 postvalidation is performed.  You can enable or
     suppress this behavior with the SET ESCAPE command.

     SET KEY procedures: The SET KEY command lets you specify a procedure
     to be executed whenever a specific 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 you specify the SAVE clause.

     Assignment: Each GET is associated with a variable, <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

     Also, the current Get object's buffer is refreshed from <idVar> and
     redisplayed at various intervals:

     .  After a SET KEY procedure terminates

     .  After a WHEN expression is evaluated

     .  After a VALID expression is evaluated

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

     GET coordinates and display: When you create a Get object using the
     @...GET command, the row and column coordinates at which the GET is
     initially displayed are stored in the Get object.  When the @...GET
     command executes, the new GET displays at <nRow> and <nCol>, unless you
     specify the SAY clause which positions the GET so 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 executes, the current
     DELIMITER characters display 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.

     If INTENSITY is ON, GETs initially display in the current unselected
     color (or the enhanced color, if no unselected color has been
     specified).  During a READ, the active GET displays in the enhanced
     color, while the remaining GETs display in the unselected color.  With
     INTENSITY OFF, all GETs display in the standard color.

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

 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.  You can directly assign the variable 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.

        When including a GET in a called function, do not include an <idVar>
        with the same name as a field <idVar>.  Field references have
        precedence over public variables so the public <idVar> will be
        ignored.

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

     .  SET DEVICE TO PRINTER: SET DEVICE TO PRINTER does not direct
        display of a Get object under the @...GET command to the printer or
        file.

 Examples

     .  This  example uses 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 demonstrates passing a code block with the VALID
        clause.  The parameter oGet is the current Get object.  Udf() changes
        the value of the GET:

        LOCAL GetList := {}, cVar := SPACE(10)
        CLS
        @ 10, 10 GET cVar  VALID { |oGet| Udf1( oGet ) }
        READ
        .
        .
        .
        * Udf( <oGet> ) --> .T.

        FUNCTION Udf1( oGet )

        IF "test" $ oGet:BUFFER          // Compare buffer contents
        oGet:varPut( "new value " )      // Change contents
        ENDIF

        RETURN .T.

     .  This example uses the WHEN clause 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

     .  This 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 uses 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

     .  This is an example of a nested READ using a GetList and
        lexical scoping:

        #include "inkey.ch"
        //
        // Local to this function only
        LOCAL GetList := {}
        LOCAL cName   := SPACE( 10 )
        //
        CLS
        SETKEY( K_F2, { || MiscInfo() } )   // Hot key to special READ
        //
        // Get object added to getlist
        // works on local getlist
        @ 10, 10 SAY "Name" GET cName
        READ
        //
        RETURN NIL

        /***
        *  MiscInfo() ---> NIL
        */FUNCTION MiscInfo()
        //
        LOCAL GetList    := {}               // Local to this
        LOCAL cExtraInfo := SPACE( 30 )      // function only
        //
        // Get object added to getlist
        // works on local getlist
        @ 12, 10 SAY "Note: " GET cExtraInfo
        READ
        //
        RETURN NIL

 Files   Library is CLIPPER.LIB.

See Also: ?|?? @…SAY CLEAR COL() PCOL() PROW() READ