SP_RAT_READ

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()

SP_RAT_MENU2

RAT_MENU2()

  Short:
  ------
  RAT_MENU2() Mouseable MENU TO emulation

  Returns:
  --------
  <nSelected> => selected menu option, 0 for none

  Syntax:
  -------
  RAT_MENU2(aOptions,[nStart],[lImmediate],[bMouse])

  Description:
  ------------
  You must pass an array of arrays, with each element
  being an array in the form {nRow,nColumn,cPrompt} which
  correspond to      [ @nRow,nCol PROMPT cPrompt. ]

  [nStart] is an optional starting prompt, with the
  default being 1

  [lImmediate] refers to the action taken when a first
  letter or a mouse click changes options. The default is to have
  immediate action - select and return. By passing False, it
  becomes a 2 step  process, requiring click-click or
  firstletter-firstletter to select and return.

  [bMouse] is an optional codeblock for mouse clicks. If the
  mouse click does not satisfy RAT_MENU2(), and there is a
  [bMouse] codeblock, it will be evaluated as follows:

               eval(bMouse,mouserow, mousecol)

  Examples:
  ---------
   local aOptions := { ;
                      {23,2 ,  'Add'},;
                      {23,9 ,  'Open'},;
                      {23,17 , 'Delete'},;
                      {23,27 , 'Change Date'},;
                      {23,42 , 'Output list'},;
                      {23,57 , 'Purge '},;
                      {23,74 , 'Quit'}}

   nSelected := RAT_MENU2(aOptions,4,.f.,{|r,c| checkmouse(r,c) })

  Source:
  -------
  S_RMENU2.PRG

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

SP_RAT_LASTEV

RAT_LASTEV()

  Short:
  ------
  RAT_LASTEV() Returns the last event recorded by RAT_EVENT()

  Returns:
  --------
  <nEvent> => last recorded RAT_EVENT() event

  Syntax:
  -------
  RAT_LASTEV()

  Description:
  ------------
  Every once in a while, some other function will be responsible
  for doing the RAT_EVENT() call, but your function still wants
  to know what the last event was. This function can be used to
  retrieve that value.

  Examples:
  ---------
   RAT_LASTEV()

  Source:
  -------
  S_MOOSE.PRG

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

 

SP_RAT_ISMOUSE

RAT_ISMOUSE()

  Short:
  ------
  RAT_ISMOUSE() Determines mouse usage by RAT_EVENT()

  Returns:
  --------
  <lIsMouse> => is there a mouse

  Syntax:
  -------
  RAT_ISMOUSE([lIsMouse])

  Description:
  ------------
  Determines mouse usage by RAT_EVENT(). Default is
  determined by a call to the ASM function RAT_EXIST(). However,
  you may want to shut down mouse usage even if a mouse is
  present. If so, call this function with False, to override.

  [lIsMouse]  S_MOOSE.PRG contains a static variable
  called 'lIsMouse'. This is determined initially by a call to
  RAT_EXIST(), but may be overridden by calling RAT_ISMOUSE(.f.).

  Examples:
  ---------
   RAT_ISMOUSE(.f.).

  Source:
  -------
  S_MOOSE.PRG

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

SP_RAT_EVENT

RAT_EVENT()

  Short:
  ------
  RAT_EVENT() Event handler - inkey() with mouse awareness

  Returns:
  --------
  <nEvent> => Event value - either inkey() value or
  mouse value

  Syntax:
  -------
  RAT_EVENT([nTimeout],[lClearkb])

  Description:
  ------------
  Event handler - inkey() with mouse awareness

  <nTimeout>   is the   # seconds to wait before
  timeout. Zero (0) means indefinately . If you don't pass
  anything, default is 0. Slight difference from inkey() there.

  Returns values are:

     If keystroke                                   inkey() value
     If left mouse button has been depressed        K_MOUSELEFT
     If right mouse button has been depressed       500
     If timeout                                      0

  [lClearkb]   optional clear keyboard True (default)
  or False. If a keystroke is gotten, and this is True, clear the
  keyboard with:
                     while inkey()#0
                     end

  Examples:
  ---------
   e := 0

   while  e#27
      e := rat_event(30)
      do case
      case e == 0
        ? "Timed out after 30 seconds"
      case e < 400
        ? "Key press with inkey() value of :",e
      case e == 400
        ? "Left mouse button pressed at :"
        ?? "row-> ",rat_eqmrow(),  "col-> ",rat_eqmcol()
      case e == 500
        ? "Right mouse button pressed at :"
        ?? "row-> ",rat_eqmrow(),  "col-> ",rat_eqmcol()
      endcase
   end

  Source:
  -------
  S_MOOSE.PRG

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

SP_RAT_ERBHD

RAT_ERBHD()

  Short:
  ------
  RAT_ERBHD() Determines if right mouse button is held down

  Returns:
  --------
  <lHeldDown> => is RMB held down

  Syntax:
  -------
  RAT_ERBHD([nSeconds])

  Description:
  ------------
  Determines if right mouse button is held down by
  calling the ASM function RAT_RBHD() for [nSeconds]. Default for
  [nSeconds] is .1 seconds. If the right mouse button is held down
  during that time frame, True is returned, else False is returned.

  [nSeconds]   is optional seconds to test for. Default
  is .1 seconds.

  This is different from the .ASM function RAT_RBHD().
  RAT_ERBHD(<n>) watches the mouse for <n> seconds, and if the
  mouse remains depressed for the full time, then it is considered
  to be HELD DOWN.  RAT_RBHD() on the other hand, only checks for
  the mouse button being depressed RIGHT NOW. RAT_ERBHD() calls
  RAT_RBHD() repetitively.

  Examples:
  ---------
   if rat_erbhd()

     ?"While you were out:"

     ?"Right button was depressed and held down at"

     ??rat_eqmrow(),rat_eqmcol()

   endif

  Source:
  -------
  S_MOOSE.PRG

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

SP_RAT_EQMROW

RAT_EQMROW()

  Short:
  ------
  RAT_EQMROW() Returns mouse row at last press

  Returns:
  --------
  <nRow> => mouse row at last button press (left or
  right)

  Syntax:
  -------
  RAT_EQMROW()

  Description:
  ------------
  Returns mouse row at last press (LEFT OR RIGHT).
  S_MOOSE.PRG has two static variables, 'mouserow' and 'mousecol'.
  These are set each time RAT_EVENT() determines that the mouse
  has been depressed.

  Examples:
  ---------
   e := 0

   while e#27
      e := rat_event(30)
      do case
      case e == 0
        ? "Timed out after 30 seconds"
      case e < 400
        ? "Key press with inkey() value of :",e
      case e == 400
        ? "Left mouse button pressed at :"
        ?? "row-> ",rat_eqmrow()
        ?? "col-> ",rat_eqmcol()
      case e == 500
        ? "Right mouse button pressed at :"
        ?? "row-> ",rat_eqmrow()
        ?? "col-> ",rat_eqmcol()
      endcase
   end

  Source:
  -------
  S_MOOSE.PRG

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