From 1716bdce7356a65fefd926c211d15451bdebcc96 Mon Sep 17 00:00:00 2001
From: Chen Kedem <niki@synel.co.il>
Date: Mon, 27 Dec 1999 06:38:23 +0000
Subject: [PATCH] 19991227-08:30 GMT+2 Chen Kedem <niki@actcom.co.il>   *
 source/rtl/readvar.prg     + doc for READVAR()   * source/rtl/setfunc.prg    
 + doc for __SetFunction()

---
 harbour/ChangeLog              |  6 +++
 harbour/source/rtl/readvar.prg | 58 +++++++++++++++++++++++++++++
 harbour/source/rtl/setfunc.prg | 68 ++++++++++++++++++++++++++++++++++
 3 files changed, 132 insertions(+)

diff --git a/harbour/ChangeLog b/harbour/ChangeLog
index 1a3eec9bb9..2bb1a76959 100644
--- a/harbour/ChangeLog
+++ b/harbour/ChangeLog
@@ -1,3 +1,9 @@
+19991227-08:30 GMT+2 Chen Kedem <niki@actcom.co.il>
+  * source/rtl/readvar.prg
+    + doc for READVAR()
+  * source/rtl/setfunc.prg
+    + doc for __SetFunction()
+
 19991227-00:36 GMT+1 Antonio Linares <alinares@fivetech.com>
    * Updated tests/bld_b32w.bat
 
diff --git a/harbour/source/rtl/readvar.prg b/harbour/source/rtl/readvar.prg
index dd50b654ce..be3988d758 100644
--- a/harbour/source/rtl/readvar.prg
+++ b/harbour/source/rtl/readvar.prg
@@ -33,8 +33,66 @@
  *
  */
 
+/*
+ * The following parts are Copyright of the individual authors.
+ * www - http://www.harbour-project.org
+ *
+ * Copyright 1999 Chen Kedem <niki@actcom.co.il>
+ *    READVAR() documentation
+ *
+ * See doc/license.txt for licensing terms.
+ *
+ */
+
 #include "common.ch"
 
+/*  $DOC$
+ *  $FUNCNAME$
+ *      READVAR()
+ *  $CATEGORY$
+ *      Data input and output
+ *  $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
+ *  $TESTS$
+ *  $STATUS$
+ *  $COMPLIANCE$
+ *      READVAR() works exactly like CA-Clipper's READKEY(), note however,
+ *      that the <cVarName> parameter is not documented and used internally
+ *      by CA-Clipper.
+ *  $PLATFORMS$
+ *  $FILES$
+ *  $SEEALSO$
+ *      @...GET, @..PROMPT, MENU TO, READ, SET KEY, __AtPrompt(), __MenuTo()
+ *  $END$
+ */
+
 FUNCTION ReadVar( cVarName )
    STATIC s_cVarName := ""
 
diff --git a/harbour/source/rtl/setfunc.prg b/harbour/source/rtl/setfunc.prg
index 693d63c26e..867258cf3a 100644
--- a/harbour/source/rtl/setfunc.prg
+++ b/harbour/source/rtl/setfunc.prg
@@ -33,8 +33,76 @@
  *
  */
 
+/*
+ * The following parts are Copyright of the individual authors.
+ * www - http://www.harbour-project.org
+ *
+ * Copyright 1999 Chen Kedem <niki@actcom.co.il>
+ *    __SetFunction() documentation
+ *
+ * See doc/license.txt for licensing terms.
+ *
+ */
+
 #include "inkey.ch"
 
+/*  $DOC$
+ *  $FUNCNAME$
+ *      __SetFunction()  (SET FUNCTION command)
+ *  $CATEGORY$
+ *      Environment
+ *  $ONELINER$
+ *      Assign a character string to a function key
+ *  $SYNTAX$
+ *      __SetFunction( <nFunctionKey>, [<cString>] ) --> NIL
+ *
+ *      or
+ *
+ *      SET FUNCTION <nFunctionKey> TO [<cString>]
+ *  $ARGUMENTS$
+ *      <nFunctionKey> is a number in the range 1..40 that represent the
+ *      function key to be assigned.
+ *
+ *      <cString> is a character string to set. If <cString> is not
+ *      specified, the function key is going to be set to NIL releasing by
+ *      that any previous __SetFunction() or SETKEY() for that function.
+ *  $RETURNS$
+ *      __SetFunction() always return NIL.
+ *  $DESCRIPTION$
+ *      __SetFunction() assign a character string with a function key, when
+ *      this function key is pressed, the keyboard is stuffed with this
+ *      character string. __SetFunction() has the effect of clearing any
+ *      SETKEY() previously set to the same function number and vice versa.
+ *
+ *      nFunctionKey    Key to be set
+ *      ------------    -------------
+ *         1 .. 12      F1 .. F12
+ *        13 .. 20      Shift-F3 .. Shift-F10
+ *        21 .. 30      Ctrl-F1 .. Ctrl-F10
+ *        31 .. 40      Alt-F1 .. Alt-F10
+ *
+ *      SET FUNCTION command is preprocessed into __SetFunction() function
+ *      during compile time.
+ *  $EXAMPLES$
+ *      // Set F1 with a string
+ *      CLS
+ *      __SetFunction( 1, "I Am Lazy" + CHR( 13 ) )
+ *      cTest := SPACE( 20 )
+ *      @ 10, 0 SAY "type something or F1 for lazy mode " GET cTest
+ *      READ
+ *      ? cTest
+ *  $TESTS$
+ *  $STATUS$
+ *  $COMPLIANCE$
+ *      Harbour use 11 and 12 to represent F11 and F12, while CA-Clipper use
+ *      11 and 12 to represent Shift-F1 and Shift-F2.
+ *  $PLATFORMS$
+ *  $FILES$
+ *  $SEEALSO$
+ *      INKEY(), SETKEY(), __Keyboard()
+ *  $END$
+ */
+
 PROCEDURE __SetFunction( nFunctionKey, cString )
 
    /* NOTE: CA-Cl*pper will not handle F11 and F12 here. */