/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 1999 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: ReadVar()
 *
 * See COPYING.txt for licensing terms.
 *
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      ReadVar()
   $CATEGORY$
      API
   $SUBCATEGORY$
      User interface
   $ONELINER$
      Return variable name of current GET or MENU
   $SYNTAX$
      ReadVar( [<cVarName>] ) --> cOldVarName
   $ARGUMENTS$
      <cVarName> is a new variable name to set.
   $RETURNS$
      ReadVar() return the old variable name. If no variable previously
      was set, ReadVar() return "".
   $DESCRIPTION$
      ReadVar() is set inside a READ or MENU TO command to hold the
      uppercase name of the GET / MENU TO variable, and re-set back to old
      value when those commands finished. You should not normally set a
      variable name but rather use it to retrieve the name of a GET
      variable when executing a VALID or WHEN clause, or during SET KEY
      execution and you are inside a READ or MENU TO.
   $EXAMPLES$
      // display a menu, press F1 to view the MENU TO variable name
      CLS
      @ 1, 10 PROMPT "blood sucking insect that infect beds   "
      @ 2, 10 PROMPT "germ; virus infection                   "
      @ 3, 10 PROMPT "defect; snag; (source of) malfunctioning"
      @ 4, 10 PROMPT "small hidden microphone                 "
      @ 6, 10 SAY "(Press F1 for a hint)"
      SET KEY 28 TO ShowVar
      MENU TO What_Is_Bug

      PROCEDURE ShowVar
         Alert( ReadVar() )     // WHAT_IS_BUG in red Alert() box
   $STATUS$
      R
   $COMPLIANCE$
      ReadVar() works exactly like CA-Cl*pper's ReadKey().

      Note however,
      that the <cVarName> parameter is not documented and used internally
      by CA-Cl*pper.
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      @...GET,@...PROMPT,MENU TO,READ,SET KEY,__AtPrompt(),__MenuTo()
   $END$
 */
