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

@...SAY...GET


Syntax:     @ <expN1>, <expN2> [SAY <exp> [PICTURE <expC1>]] [GET
            <variable> [PICTURE <expC2>] [RANGE <expN3>, <expN4>]/
            [VALID <expL>]]

Purpose:    To display and input data at specified row and column
            positions.

Arguments:  <expN1> is the row coordinate.

            <expN2> is the column coordinate.

Options:    Say: The SAY clause displays the result of an <exp> of
            any type (including a memo field) at the specified
            coordinates on the current DEVICE.  Clipper supports two
            devices: PRINT and SCREEN.  If DEVICE is SET TO PRINT,
            output is directed to the printer.  Otherwise it is directed
            to the SCREEN.  To direct @...SAYs to a file, SET DEVICE TO
            PRINT and then SET PRINTER TO <output filename>.  Output
            destined for the printer is then redirected to the specified
            text file.

            @...SAYs to the printer behave a little differently than to
            the screen.  If you address a printer row and column
            position less than the last position printed since an EJECT
            or SETPRC(), Clipper performs an EJECT and resets the
            internal PROW() and PCOL() values.  Your printing logic
            must, therefore, proceed sequentially from left to right
            down the page.

            SAYs display in standard color (see SET COLOR).

            Get: The GET clause displays a <variable> (a field or
            memory variable) at a specified screen coordinate and adds
            it to the list of pending GETs.  A subsequent READ invokes a
            full-screen edit mode allowing you to edit the contents of
            the pending GETs with a full complement of editing and
            navigation keys.  For a complete list of keys, see READ.

            Clipper supports GETting fields from other work areas if
            fields are referenced using the alias.  For example:

            @ 10, 10 GET alias->fieldname

            GETs display in enhanced color unless there is an unselected
            COLOR SETting.  If this is the case, the current GET
            displays in the enhanced color and all other active GETs
            display in the unselected color.  Note that in Clipper,
            color is a mode.  This means that each time a GET is
            painted, the color is the current enhanced COLOR SETting.

            Note that GETs are not directed to the printer or a file
            with SET DEVICE TO PRINT.

            Picture: The PICTURE clause defines the mask for entry
            into a GET and formats the output of a SAY.  Clipper
            provides two mechanisms to control formatting:  functions
            and templates.  Functions apply to the entire SAY or GET
            while templates mask characters position by position.

            Functions: A PICTURE function is a symbol preceded by an
            "@."  If a template symbol follows the function, it must be
            preceded with a space.  Note that more than one function can
            be applied within the same PICTURE.  The following table
            summarizes the available functions:


            Table: PICTURE Function Symbols
            ---------------------------------------------------------------
            Func  Type     Action
            ---------------------------------------------------------------
            A     C        Allows only alphabetic characters into a GET
            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 no
                           matter the current DATE SETting,
                           numerics in European format (comma and period
                           reversed)
            K     All      Clears GET if first key is not a cursor key
            R     C        Non-template characters are inserted
            S<n>  C        Allows the horizontal scrolling within a GET
            X     N        Displays DB after negative numbers
            Z     N        Displays zero as blanks
            (     N        Encloses negative numbers in parentheses with
                           leading spaces
            )     N        Encloses negative numbers in parentheses
                           without leading spaces
            !     C        Converts alphabetic characters to upper case
            ---------------------------------------------------------------

            Templates: Template symbols follow functions in the
            PICTURE string if they are specified.  Each position in the
            output or input stream is mapped to the symbol in the same
            position in the template.  Clipper provides a number of
            template symbols as follows:

            Table: PICTURE Template Symbols
            ---------------------------------------------------------------
            Template    Action
            ---------------------------------------------------------------
               A        Displays only alphabetic characters
               N        Displays only alphabetic and numeric characters
               X        Displays any character
               9        Displays digits for any data type including sign
                        for numerics
               #        Displays digits, signs, and spaces for any data
                        type
               L        Displays logicals as "T" or "F"
               Y        Allows only "Y" or  "N"
               !        Converts an alphabetic character to upper case
               $        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
               .        Specifies a decimal point position
               ,        Specifies a comma position
            ---------------------------------------------------------------

            Other characters specified in the template overwrite the
            character at the same position in the source stream and
            output.  If, however, you use the "R" function, non-template
            symbols specified are inserted into the display but not
            output if the PICTURE applies to a GET.

            Range: The RANGE clause limits entry into date and
            numeric type variables by specifying the lower (<expN3>) and
            upper (<expN4>) bounds of acceptable input (the lower must
            precede the upper).  If the value is not within the RANGE,
            an indicating message displays in the SCOREBOARD area and
            control returns to the GET.  Note that the RANGE check is
            performed unless you press Esc to terminate the GET.  In
            this case, there is no RANGE check and the <variable> is
            restored to its original value.

            Valid: The VALID clause allows you to validate an entry
            into a GET with <expL>.  Like RANGE, the VALID expression
            evaluates whenever you attempt to terminate the associated
            GET unless you press Esc and ESCAPE is ON.  If <expL>
            returns false (.F.), control returns to the GET and you
            cannot leave the GET until <expL> returns true (.T.) or you
            press Esc.

            Note that the expression may contain or be a user-defined
            function.  This is useful for lookups and other types of
            post-processing functions.  One of the unique capabilities
            of Clipper is that within a user-defined function called by
            VALID, you can change the contents of the current GET.  You
            do this by simply STOREing or REPLACEing a new value into
            the current GET variable.  When control returns to the GET,
            Clipper updates the screen with the new value of the
            variable.

            Note: If VALID and RANGE are both specified, you will
            cause a compiler error.  If the VALID clause follows the
            RANGE clause, the compiler error is ignored at runtime.

Usage:      Help: You can create a help system that operates within
            a screen consisting of @...SAY...GETs by first SETting KEY
            TO a specific help procedure.  Then within the procedure,
            use READVAR() to determine the current GET and display the
            appropriate help screen.  Note that within a SET KEY
            procedure, you can change the contents of the current GET in
            the same way you would from within a VALID.

Library:    CLIPPER.LIB


----------------------------------- Examples -------------------------------

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

   number = 0
   @ 10, 10 SAY "Enter a number greater than zero:";
      GET number;
      VALID number > 0


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

   SELECT 1
   USE Invoice
   APPEND BLANK

   SELECT 2
   USE Inventory

   @ 1, 1 GET Invoice->Cust_No
   READ


   This is an example of the "@E" function :

   net_income = 7125.50
   @ 1,1 SAY net_income PICTURE "@E 9,999.99"

   Result:

   7.125,50


   This example demonstrates "@)" function:

   net_loss = -125.50
   @ 1, 1 SAY net_loss PICTURE "@)"

   Result:

   (125.50)


   This example demonstrates the "@K" function to suggest an input
   value, but clears it immediately if the key pressed is not a cursor
   key or Return:

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


   This example demonstrates the "@S<n>" function which allows scrolling
   of the long character variable within a horizontal window:

   long = "This is much too long."
   @ 1,1 GET long PICTURE "@S10"
   READ