NORMAL VARIABLES :
 =====================================================================

 Normal variables are the most common in Gui4Cli. They are the ones
 you can declare with a simple statement like :

 myvar = 3                            - or
 myvar = 'This is my variable'        - or
 SetVar myvar 'This is my variable'

 You can thereafter refer to their contents by putting a $ sign in front :
 >  say '$myvar'
 >  should print out : This is my variable

 *** Important :  Normal variables are CASE SENSITIVE 
     (i.e. myvar is not the same as MyVar)

 Note that you can hit CONTROL-V to get a full listing of all variables
 currently declared by all guis loaded. Furthermore, you can "Set Debug
 On" to see when and how variables are set or read while the guis are
 executing commands.


 NORMAL VARIABLE TYPES:
 ======================================================================

 GUI Variables
 -------------------------------
 Normal variables are kept in lists. 
 Each GUI has such a list, where it keeps all it's variables.

 You can get/set the variables of your gui's list, by just declaring:
 >   MyVar = "Something"

 If you want to get/set another Gui's variables, you can do this:
 >   OtherGui.gc/MyVar = "SomethingElse"
 This will set variable "MyVar" of Gui "OtherGui.gc" to "SomethingElse"

 Similarly, to get the results, you would do:

 Say $MyVar               --> would print: "Something"
 Say $OtherGui.gc/MyVar   --> would print: "SomethingElse"


 LOCAL (Event) Variables
 -------------------------------
 Variables can also be attached to each and every EVENT.
 To do this however, you must declare the variables you want to use
 with the  LOCAL  command :

   xRoutine ExampleRoutine      ; an event such as a routine or whatever
   Local var1/var2/var3         ; declare 3 variables
   var1 = 'something'           ; use as normal variables..
   say '$va1[0][4]n'           ; but only in this event

 Local variables are only visible within the Event in which
 they are declared. They can not be seen or set from anywhere
 else. This is usefull for throw-away variables you want to
 use for temporary storage places etc..


 GLOBAL Variables :
 ------------------------------
 There is also a "GLOBAL" variable list, which is always present and
 which can be accessed from any gui, anytime, by putting a '*' character
 in front of the name.

 So, to set a Global variable, you would do :
 >   *MyGlobalVar = "Something"
 and to read it:
 >   Say $*MyGlobalVar

 Global variables are usefull since they are accessible from everywhere.
 I.e. you do not have to rely on a certain gui being loaded to have them
 available.


 The VARPATH command :
 ------------------------------
 If you are building a multi-gui application you can use the  VarPath 
 command, with which you can declare a "Variable Search Path" and in
 effect "merge" the variables of many guis.


 FULL VARIABLE NOTATION :
 ======================================================================

 Although for normal use you just declare the variable name as above, 
 normal variables may have the following full template :

      gui/name[+-start][+-length]

 and Global variables

      *name[+-start][+-length]

 In all the above, only the name is required. All others are optional.


 THE RULES OF THE GAME :
 -----------------------

 - As we said, the 'gui' part, is the name of the Gui that the variable 
   belongs to. If no 'gui' name is given the variable is automatically 
   assumed to belong to the gui it resides in.

 - [start]  is the character of the variable you want to start at.
 - [length] is how many characters to consider 

 - If you give a [start] which is more than the length of the variable
   you'll get "".

 - If you give a length that will pass the end of the variable, then 
   only the actual length of the variable will be considered. Variables
   will *not* be expanded to accommodate [start] or [length].

 - If the [start] is omited it means '0' i.e. from the start of the var. 

 - If the [length] is omited it means the rest of the variable.

 - If [start] is negative it means from the *end* of variable.

 - If [length] is negative it means "count from right to left"


 EXAMPLES :
 ------------------------

      var = '0123456789'
      res = $var[3][3]

   res will now be = '345'
   If these variables were in an other file called "mygui" and you 
   wanted to refer to them, you would do :

      mygui/var = '0123456789'
      res = $mygui/var[3][4]

   now res will equal '3456'
   or if 'var' was a global variable: 

      *var = '0123456789'
      res  = $*var[3][4]

   ok, up to now ?..

      res = $var[3]

   res is now '3456789' since we did not give a length.

      res = $var[3][20000000]

   res is still '3456789' since res will not be expanded.
   And what's more, it works both ways:

      var[3][2] = 'xx'
   or 
      var[3][2] = 'xxxxxxxxxxxxxxxxx'

   will both set var to: '012xx56789'
   More stuff :

      var[-1][1]       ; is the last character of a variable
      var[-3][3]       ; are the last 3 characters of a variable
      var[3][-3]       ; are the first 3 characters of a variable
      var[0][3]        ; are, again, the first 3 chars

   and so on...


 Variables in the brackets :
 ---------------------------
 - In the "Gui/Name[start][length]" notation, for internal, pain-in-the-ass 
   related reasons, the "Gui" and "Name" parts can *not* themselves be
   variables. (There are ways of circumventing this if needed - see below).

   However, you can use variables for [start] and [length] :

       var = "01234556789"
       c   = 0
       while $c < 10
           say '$var[$c][$c]n'
           ++c
       endwhile

   Important : Variable "c" as is used above, *must* be a simple direct 
   variable - i.e. it can not contain other variables.

 
 Variables within variables :
 ----------------------------
  See also  Variables within variables  if you need variable "Arrays"