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

@..GGET is a replacement for the standard @..GET command. It adds
numerous optional clauses that greatly enhance the power and
functionality of your GETs. IMPORTANT: If you intend to use the
@..GGET command, you must #include the GRUMPR.CH header file at the
top of your program. Failure to do so will result in a compile error.

   @ <row>, <col> GGET <var> [PICTURE <pic>] [COLOR <color>]       ;
            [RANGE <lo>, <hi>] [VALID <valid>] [MESSAGE <message>] ;
            [ARRAY <array> [NOEDIT] ] [CALCULATOR] [WHEN <when>]   ;
            [STEP] [PROPER] [PASSWORD <char>] [LIST <list>]

Optional clauses PICTURE, COLOR, RANGE, VALID, and WHEN are fully
documented in the Clipper documentation, and will therefore not be
discussed here.

a. MESSAGE - this clause allows you to specify a message for each GET.
   The <message> will appear in accordance with the SET MESSAGE TO
   setting, and will automatically be centered.

b. CALCULATOR - this enables calculator-style data entry, i.e., from
   right to left.  This bears an uncanny resemblance to the Grumpfish
   CALC_PIC() function, except that now it can be performed on a series
   of GETs.  NOTE: this only supports backspace and numeric entry
   (including decimal point, naturally).

c. ARRAY - allows you to have a list of options displayed for selection
   upon entering a GET.  To use this clause, you must pass the name of
   an <array> that contains the possible options.  When the user selects
   an element from the array, its value will be pasted into the GET.

   If you use ARRAY, you may also specify the NOEDIT clause.  Doing so
   will prevent the user from editing the GET after they have selected
   an array element.

   Two caveats:

   i.  all elements of <array> must be character strings. However, this
       restriction should not present undue hardship given the
       circumstances.

   ii. Don't bother specifying a WHEN clause along with ARRAY, because
       ARRAY will override your WHEN clause.

d. STEP - this enables step entry for numerics and dates. Press "+" to
   increment value, "-" to decrement value.  Note that this obviously
   precludes the entry of negative numbers. Logic is included to limit
   entry to any applicable range specified in the VALID or RANGE clause.

e. PROPER - this enables proper-case entry for character data (first
   character in word upper-case, rest lower)... similar to the Grumpfish
   UP_N_DOWN() function, except not nearly as kludgy).  Whenever any of
   the following characters are detected -- space, period, comma,
   hyphen, apostrophe -- the next character will be forced to upper-case.

f. PASSWORD - this clause is for hidden password entry.  The optional
   <char> parameter is a single character (enclosed in quotes) that will
   be displayed as the user types in the password.  If you do not
   specify <char>, asterisks will be used. NOTE: when using this clause,
   only backspace and character entry are supported.

g. LIST - this clause allows you to specify a list of valid choices for
   the user.  The user can toggle through the choices with either the
   Spacebar (forward) or Backspace (backward).  The choices must be
   within quotes, and delimited by semi-colons, as demonstrated below:

   @ 20,0 gget x list "Blue Jays;Red Sox;Tigers;Orioles;Yankees"

   NOTE: you cannot use the VALID or RANGE clause in conjunction with
   the LIST clause.  Neither would make sense because LIST is self-
   validating.

Once again, in order to use any of these extensions, you must #include
the GRUMPR.CH header file at the top of your program.

Modified READ Command

If you are using the @..GGET command, you may also wish to use timed
reads or complete GET validation.  The syntax is:

     READ TIMEOUT <seconds> [EXITEVENT <event>] ;
          [WARNING <warnsecs>] [WARNEVENT <warnevent>] [VALIDATION]

<seconds> is the number of seconds to wait for a keypress.  If no
keypress is detected within this time, one of two things will
happen:

   (a) your EXITEVENT will be processed if you specified one; or

   (b) an ESC keypress will be stuffed into the keyboard buffer to
       exit the READ.

You may optionally specify a WARNING period.  If you do, a warning
message will appear at the bottom of the screen, indicating that
the program will time-out in the number of seconds between the
TIMEOUT and WARNING periods.  For example, if you specify WARNING 110
and TIMEOUT 120, the warning will occur after 110 seconds of keyboard
inactivity and the timeout will occur 10 seconds later (unless the user
wises up by pressing a key).  In similar fashion to the EXITEVENT
clause, you may override the default warning behavior with the WARNEVENT
clause.

Examples:

READ TIMEOUT 30        // stuff ESC into buffer after 30 seconds
                       // of keyboard inactivity

//----- issue warning after 50 seconds of keyboard inactivity
//----- use default warning message... after 10 more seconds
//----- of inactivity, invoke the planetarium screen saver
READ TIMEOUT 60 WARNING 50 EXITEVENT BlankScr3(-1)

Validation of All GETs

If you use the VALIDATION clause, the user will not be allowed to exit
the READ unless all GETs are found to be valid.  Note that if you are
using lookup functions for validation, such as HELPBROW(), there is no
way to prevent the calls to such functions when using the READ
VALIDATION clause.  That's just the nature of this beast.


Other GET-related functions

GGETALIAS()    Returns alias associated with a specified GET
GGETCOL()      Returns/changes column position of a specified GET
GGETCOLOR()    Returns/changes color setting of a specified GET
GGETNAME()     Returns name of a specified GET
GGETNO()       Returns number of a specified GET
GGETPIC()      Returns/changes PICTURE clause for a specified GET
GGETROW()      Returns/changes row position of a specified GET
GKILLGET()     Remove a GET from the currently active GET list
GREGET()       Redisplay all active GETs