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

 get                 Create and display a get field
------------------------------------------------------------------------------
 Syntax
   @ uRow, uCol get xVar [picture cPicture|function cFunction] ;
                         [valid   lValid] ;
                         [filter  uFilter] ;
                         [id      uId]

 Arguments
   uRow is the row for the get field.

   uCol is the starting column for the get field.

   xVar is a variable receiving input.

   cPicture is a template string that contains function and/or
      template symbols to specify the display format and editing rules.

   cFunction contains function symbol(s) to format the display.

   lValid is a logical expression specifying the condition that must be
      satisfied before the cursor can leave the get during a read.

   uFilter is an uint expression that validates keypresses.

   uId is a numeric identifier associated with the get field.

 Description
   The get command converts the contents of xVar into a character string,
   displays it and puts an entry in the read table.

   Global, static, local or field variables may be used in a get command.
   If a variable used in a get command is a local variable, then you must
   be sure the read command is activated within the scope of the local
   variable. If a get is issued for a local variable, a warning message
   is generated by the compiler. You are warned because the subsequent read
   command must be issued within the scope of the local variable.

   The display can be formatted through templates using the picture and/or
   function clauses, that include a combination of function and template
   strings, like in the following two equivalent examples:

              function string -----+ +-------- separator space
              function marker ---+ | |    +--- template string
                                 |+-+|+--------+
   @ 0, 0 get eDiscount picture "@BZ_ 999,999.00"

   @ 0, 0 get eDiscount picture "999,999.00" function "BZ_"
                                 +--------+            +-+
                                     |                  |
                            template string            function string

   A function string specifies formatting rules that apply to the get's
   appearance as a whole, rather than to particular character positions
   within the display. The function string consists of the @ character,
   followed by one or more additional characters, each of which has a
   particular meaning (see the Picture format table).

   A template string specifies formatting rules on a character by
   character basis. The template string consists of a series of
   characters, some of which have special meanings (see the Picture format
   table). Each position in the template string corresponds to a
   position in the displayed string.

   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. If a
   function string is present, the @ character must be the leftmost
   character of the picture string, and the function string must not
   contain spaces.

   The get and say commands display strings using the same format
   rules, except:

    - If the string exceeds one line, then get wraps it to the next row.
      The column position of the next row will be the starting position of
      the previous row. say always starts the next row at column position 0.

    - The get command bypasses the device selected in the set device to
      command.

    - get displays characters with attributes set from the enhanced display
      string of the set color to command. say displays characters with
      attributes set from the standard display string of the set color to
      command.

    - Templates can be used in the picture string. Functions can be used in
      picture and function strings, where functions in a picture string
      are indicated by a leading '@' character.

    - Characters entered into a get field can be filtered.

   The valid clause of the get command initiates evaluation of a logical
   expression after a get. If the expression evaluates to .f., the get
   will be reentered and cannot be exited until the function evaluates to
   .t. or until the Esc key is pressed. A function call in the valid
   expression can be used for auxiliary processing for each get.

   The filter clause of the get command filters each key as it is input.
   The filter clause specifies a uint expression that is evaluated for every
   key pressed. The uint expression may be a function. Filters increase
   control over get input. The filter can be used to:

     - program special keys
     - trap defined keys by stuffing the keyboard
     - implement context-sensitive help
     - implement user-defined templates

   If a filter function is specified with the get, e.g.,

   @ x,y get cVar filter FilterFunction() // function name must end with ()

   then the function must return a key to the read. A filter function
   returning 0 tells the read to ignore the key and to get another keystroke.

   The id clause of the get command allows valid and filter functions to
   identify the get which evoked them. The id number given to a get is
   returned by using the getid() function. If a specific id clause is not
   included, an id number is assigned by numbering all gets sequentially
   from the last clear gets command, beginning with 1.

 Example
   #define EXAMPLE_IO
   #include example.hdr

   vardef static
      char(5) cSayPic := "@!"
   enddef
   
   func char PictGet
   vardef
      char cPict
   enddef
   cPict := replicate( "!", 15 )
   return( cPict )
   endfunc
   
   func logical GetPreFunc
   param value uint nID
   // Called before entering to a get field
   vardef
      logical lOK
   enddef
   lOK := .t.
   @ 19, 0 ?? "Entered into field", nID
   return( lOK )
   endfunc
   
   func logical GetPostFunc
   // Called before exiting from a get field
   vardef
      logical lOK
   enddef
   @ 21, 0 ?? "Left field        ", getid()
   lOK := .t.
   return( lOK )
   endfunc
   
   func uint KeyFilter
   // Called after all keypresses within a get field
   vardef
      uint nKeyBack
   enddef
   @ 20, 0 ?? "Moving in field   ", getid()
   nKeyBack := lastkey()
   return( nKeyBack )
   endfunc
   
   proc Test_get
   vardef
      char(15) cText1, cText2
   enddef
   clear()
   cText1 := ""
   cText2 := ""
   @ 10, 25 say "Text1" picture cSayPic get cText1 picture PictGet() ;
      filter KeyFilter() valid GetPostFunc() id 1
   @ 11, 25 say "Text2" picture cSayPic get cText2 picture PictGet() ;
      filter KeyFilter() valid GetPostFunc() id 2
   activategetpreblock( GetPreFunc )
   read
   @ 22, 0 ?? cText1, cText2
   wait
   endproc

   proc main
   Test_get()
   endproc