MOUSEHOTAT()

  Short:
  ------
  MOUSEHOTAT() Checks for mouse click from array of hot coordinates

  Returns:
  --------
  <nReturn> => either number of element containing hot coordinates, or,
               if element (an array) contains > 4 elements, the value in
               the fifth element.

  Syntax:
  -------
  MOUSEHOTAT(nMouseRow, nMouseCol, aHotSpots)

  Description:
  ------------
  Checks an array of arrays for hot coordinates against <nMouseRow>
  and <nMouseCol> to see if the mouse clicked on one of the hot spots.
  The hot spot array is of the form:
         {  {nTop,nLeft,nBottom,nRight,[nValue] },...}
  Where each subarray is an array containing Top, Left, Bottom, Right
  coordinates for an area of the screen which is mouse hot. If a match
  is gotten and the subarray is four elements long, the number of the
  subarray is returned. If the subarray is 5 elements long, the value
  in the fifth element is returned.

  Examples:
  ---------
  #include "INKEY.CH"
  @10,10 say "<OK>
  @11,10 say "<Cancel>"
  aHotAreas  := {  {10,10,10,13}, {11,10,11,18} }
  nLastKey   := RAT_EVENT(0,.f.,.f.,@nMouseRow, @nMouseCol)
  nHotMouse  := MOUSEHOTAT(nMouseRow, nMouseCol, aHotAreas)
  DO CASE
  CASE nHotMouse==1    // <OK>
  CASE nHotMouse==2    // <Cancel>
  ENDCASE

  // OR ALTERNATELY....Here I'll map the hot areas to the same return
  // values as the hot keys the buttons represent...F10 and ESCAPE
  // this is useful as you'll often have a button or hot area also
  // assigned to a hot key.

  @10,10 say "<F10 Save  >
  @11,10 say "<ESC Cancel>"
  aHotAreas   := {  {10,10,10,21,K_F10}, {11,10,11,21,K_ESC} }
  nLastKey    := RAT_EVENT(0,.f.,.f.,@nMouseRow, @nMouseCol)
  nHotMouse   := MOUSEHOTAT(nMouseRow, nMouseCol, aHotAreas)
  DO CASE
  CASE nHotMouse==K_F10 .or. nLastKey==K_F10    // <F10 Save  >
  CASE nHotMouse==K_ESC .or. nLastKey==K_ESC   // <ESC Cancel>
  ENDCASE

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