RAT_READ()

  Short:
  ------
  RAT_READ() Mouseable read

  Returns:
  --------
  Nil

  Syntax:
  -------
  RAT_READ(aGetlist,[nStart],[lWrap],[nRmKey],[bLmouse],[aLmKeys])

  Description:
  ------------
  Set up your gets as normal, with @SAY...GET
  statements.

  The only limitation is that you cannot use a
  user-defined READER block, as RAT_READ() installs a
  user-defined reader block for each get.

  After setting up your @SAY...GET statements, instead
  of issuing a READ, issue a RAT_READ(getlist,...).

  [nStart] is an optional starting get number, which
  defaults to 1.

  [lWrap] determines if going past top or bottom get
  exits the read. Default is True. By sending false, going past top
  will put you at bottom, and going past bottom will put you at top,
  with only CTRL-W exiting the read.

  [nRmKey] is an inkey value that tells RAT_READ() how
  it should interpret a right mouse button click. Default is ESCAPE.

  [bLmouse] (new in 3.5) is a codeblock that is evaluated when there
  is a mouse click and it is not meaningful to RAT_READ().
  It is evaluated as :  eval(bLMouse,mouserow, mousecolumn)

  [aLmKeys] is an array of hot mouse coordinate sub-arrays and their
  key equivalents. For instance, if you have the following for hot
  keys: @24,0 say "[F10=save] [ESC=Cancel]", and you wanted these as
  hot mouse areas, the array would be:
        {   {24,0,24,9,K_F10},  {24,11,24,22,K_ESC}   }
  Clicking the mouse within 24,0,24,9 would be interpreted as pressing
  the F10 key.
  The structure of each sub-array is {nTop,nLeft,nBottom,nRight,nKeyValue}

  Examples:
  ---------
   v1 := space(10)
   v2 := space(10)
   v3 := space(10)
   @10,10 get v1
   @11,10 get v2
   @12,10 get v3

   RAT_READ(getlist,2,.T.,27)

   // read, starting at get # 2, wrapping, and interpreting the right
   // mouse button as chr(27) (escape).

  Notes:
  -------
  This does not replace GETSYS.PRG, but rather parallels it.

  The Clipper GET system, contained in GetSys.Prg and accessed via
  READ contains several exported functions which obtain /handle
  information about the current GET and the current READ.

  In order to implement mouse-aware reads, a modification of
  GetSys.Prg was needed. However....

  I didn't want SuperLib to replace the Clipper Get system
  willy-nilly, as that would presume that you always wanted
  to use _only_ the SuperLib version. So I had to rename all
  of the exported functions in the SuperLib mouseable get
  system. The names are as follows:

   Clipper Get System    SuperLib GetSystem
   ------------------    ------------------
   ReadModal()           Rat_Read()
   GetReader()           RatReader()
   GetApplyKey()         RatApplyKey()
   GetDoSetKey()         RatDoSetKey()
   GetPostValidate()     RatPostValidate()
   GetPreValidate()      RatPreValidate()
   GetActive()           RatActive() ---or--- GetActive()
   ReadKill()            RatKill()
   ReadUpdated()         RatSetUpdated()
   Updated()             RatUpdated()

  So you can call either READ or READMODAL() which accesses the
  Clipper Get System, or call RAT_READ(), which access the
  SuperLib mouseable get system, and they will not tromp on
  one another.

  There still remained one problem, however. Some of the SuperLib
  functions access the above named exported functions, such as
  GetActive(), and of course user-defined get readers need to
  access GetPostValidate(), GetPreValidate(), GetApplyKey() and
  GetDoSetKey(), and possibly others.

  By calling R_ISRATREAD(), you can determine if the current
  read is a RAT_READ or not, and call the regular exported
  read/get functions, or call their equivalent RAT* functions
  as listed above.

  An exception is GETACTIVE(), which may be called while using
  either get system, as RAT_READ() calls GETACTIVE() to update
  the current get, and also saves and restores the active get
  in case there is a prior READ active.

  This R_ISRATREAD() function returns TRUE/FALSE for 'is the current
  read a RAT_READ or a READMODAL (normal) read'. Essentially it tells
  you which GetSystem you are in.

  Thus you can have both RAT_READ() mouse aware reads, and standard
  READMODAL() Clipper reads in the same system, and tell the
  difference between the two.

  User defined readers attached to GETS passed to RAT_READ can
  return a numeric value indicating which get to jump to.

  Source:
  -------
  S_RREAD.PRG

See Also : RAT_ELBHD(), RAT_EQMCOL(), RAT_EQMROW(), RAT_ERBHD(), RAT_EVENT(), 
           RAT_ISMOUSE(), RAT_LASTEV(), RAT_MENU2(), RAT_READ()