/* $DOC$
   $TEMPLATE$
      Command
   $NAME$
      @...GET
   $CATEGORY$
      Command
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Creates a GET object and displays it to the screen
   $SYNTAX$
      @ <nRow>, <nCol> [SAY <cSay> [PICTURE <cSayPict>] COLOR <cSayColor> ]
      GET <xVar> [PICTURE <cGetPict>] [WHEN <lWhen>] [COLOR <cGetColor>]
      [VALID <lValid> / RANGE <xStart>, <xEnd>]
   $ARGUMENTS$
      <nRow>      The row coordinate.

      <nCol>      The column coordinate.

      <cSay>      Message to display.

      <cSayPict>  Character expression of PICTURE displayed.

      <cSayColor> Color to be Used for the SAY expression.

      <xVar>      An variable/field name.

      <cGetPict>  Character expression of PICTURE to get.

      <lWhen>     Logical expression to allow GET.

      <lValid>    Logical expression to validate GET input.

      <xStart>    Lower RANGE value.

      <xEnd>      Upper RANGE value.

      <cGetColor> Color string to be used for the GET expression.
   $DESCRIPTION$
      This command adds a GET object to the reserved array variable
      named `GetList` and displays it to the screen. The field or variable
      to be added to the GET object is specified in <xVar> and is displayed
      at row, column coordinate <nRow>, <nCol>.

      If the SAY clause is used <cSay> will be displayed starting at
      <nRow>, <nCol>, with the field variable <xVar> displayed at Row(),
      `Col() + 1`. If <cSayPicr>, the picture template for the SAY expression
      <cSay>, is used, all formatting rules contained will apply See the
      TRANSFORM I function for further information.

      If <cGetPict> is specified, the PICTURE clause of <xVar> will be
      used for the GET object and all formatting rules will apply. See
      the table below for GET formatting rules.

      If the WHEN clause is specified, when <lWhen> evaluates to a logical
      true (.T.) condition, the GET object will he activated otherwise the
      GET object will be skipped and no information will be obtained via
      the screen. The name of a user-defined function returning a logical
      true (.T.) or false ( F.) or a code block may be, specified in <lWhen>
      This clause not activated until a READ command or ReadModal()
      function call is issued.

      If the VALID clause is specified and <lValid> evaluates to it logical
      true (.T.) condition the current GET will be considered valid and
      the get operation will continue onto the next active GET object. If
      not, the cursor will remain on this GET object until aborted or
      until the condition in <lValid> evaluates to true (.T.). The name
      of a user-defined function returning a logical true (.T.) or false
      (.F.) or it code block may be specified in <lValid>. This clause is
      not activated until a READ command or ReadModal() function call is
      issued.

      If the RANGE clause is specified instead of the VALID clause, the
      two inclusive range values for <xVar> must be specified in <xStart>
      and <xEnd>. Id <xVar> is a date data type, <xStart> and <xEnd> must
      also be date data types; if <xVar> is a numeric data type <xStart>
      and <xEnd> must also be numeric data types. If a value fails the
      RANGE test, the message "OUT OF RANGE" will appear in the SCOREBOARD
      area (row = 0, col = 60). The RANGE message may be turned off it the
      `SET SCOREBOARD` command or Set() function appropriately toggled.

   $NOTES$

      GET functions/formatting rules:

      <table-noheader>
      @A          Allows only alphabetic characters.
      @B          Numbers will be left justified
      @C          All positive numbers will be followed by CR.
      @D          All dates will be in the SET DATE format.
      @E          Dates will be in British formal: numbers in European format.
      @K          Allows a suggested value to be seen within the GET
                  area but clears It if any non cursor key is pressed when
                  the cursor is in the first Position in the GET area.
      @R          Non template characters will be inserted.
      @S<nSize>   Allows horizontal scrolling of a field or variable that
                  is <nSize> characters wide.
      @X          All negative numbers will be followed by DB
      @Z          Displays zero values as blanks.
      @!          Forces uppercase lettering
      @(          Displays negative numbers in parentheses with leading spaces.
      @)          Displays negative numbers in parentheses without leading spaces.
      </table>

      GET templates/formatting rules:

      <table-noheader>
      A   Only alphabetic characters allowed.
      N   Only alphabetic and numeric characters allowed
      X   Any character allowed.
      L   Only T or F allowed For logical data.
      Y   Only Y or N allowed for logical data.
      9   Only digits, including signs, will be allowed.
      #   Only digits, signs. and spaces will he allowed.
      !   Alphabetic characters are converted to Uppercase.
      $   Dollar  will be displayed in place of leading
          spaces for numeric data types.
      *   Asterisk,, will Be displayed in place of leading spaces
          for numeric data types.
      .   Position of decimal point.
      ,   Position of comma.
      </table>

      Format PICTURE functions may he grouped together as well as used
      in conjunction with a PICTURE templates; however, a blank space must
      be included in the PICTURE string if there are both functions and
      templates.
   $EXAMPLES$
      LOCAL cVar := Space( 50 ), nId := 0
      LOCAL GetList := {}
      CLS
      @ 3, 1 SAY "Name" GET cVar PICTURE "@!S 30"
      @ 4, 1 SAY "Id"   GET nId  PICTURE "999.999"
      READ
      ? "The name you entered is", cVar
      ? "The id you entered is", nId
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $SEEALSO$
      @...SAY, READ, Transform()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Command
   $NAME$
      @...SAY
   $CATEGORY$
      Command
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Displays data at specified coordinates of the current device.
   $SYNTAX$
      @ <nRow>, <nCol> SAY <xValue> [ PICTURE <cPict> ] [COLOR <cColor>]
   $ARGUMENTS$
      <nRow>     Row coordinate

      <nCol>     Column coordinate

      <xValue>   Value to display

      <cPict>    PICTURE format

      <cColor>   Color string
   $DESCRIPTION$
      This command displays the contents of <xValue> at row column
      coordinates <nRow>, <nCol>. A PICTURE clause may be specified
      in <cPict>. If the current device is set to the printer, the output
      will go to the printer; the default is for all output to go to
      the screen.

      For a complete list of PICTURES templates and functions, see the
      `@...GET` command.
   $EXAMPLES$
      CLS
      @ 2, 1 SAY "Harbour"
      @ 3, 1 SAY "is" COLOR "b/r+"
      @ 4, 1 SAY "Power" PICTURE "@!"
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$

   $SEEALSO$
      @...GET, SET DEVICE, Transform()
   $END$
 */
