InMouse()
 Get a mouse event.
------------------------------------------------------------------------------

 Syntax:

     InMouse( [<nSeconds>] ) --> <aMouseEvent>

 Arguments:

     <nSeconds> is an optional numeric expression specifying the number of
     seconds InMouse() waits for a button click.  The value can be specified
     in increments as small as one-tenth of a second.  Specifying zero halts
     the program until a mouse button is pressed.  If <nSeconds> is omitted,
     InMouse() does not wait for a button click.

 Returns:

     InMouse() returns an array.  The array, <aMouseEvent>, is a 4 element
     array which will be filled with the particulars of a mouse click when it
     occurs.  The table below shows the manifest constants found in Mouse.ch to be used to access each of the elements.
     If no mouse event occurs within the time specified an array of zero
     length is returned.

 Description:

     InMouse() is a mouse function that extracts the next event pending in
     the mouse buffer and returns an array which represents the event.  If
     the <nSeconds> argument is specified and there are no pending events in
     the buffer, program execution pauses until an event appears in the mouse
     buffer, or <nSeconds> has elapsed.  The time InMouse() waits is
     based on the operating system clock and is not related to the micro-
     processor speed.  If <nSeconds> is zero, program execution pauses until
     an event is placed into the buffer.

     InMouse() is a basic primitive of the Clipper system for fetching mouse
     events from the mouse buffer.  It is used for polling the mouse or
     pausing program execution to wait for a button click.

     The elements of the array returned by InMouse() can be accessed using
     the following manifest constants found in MOUSE.CH.
     --------------------------------------------------------------------------
     Constant           Value   Element representation
     --------------------------------------------------------------------------
     MOUSE_VALUE         1      The value corresponds to the button pressed.
                                The values are represented by manifest contants
                                defined in MOUSE.CH in a table that
                                follows.
     MOUSE_ROW           2      The row the click occured on.
     MOUSE_COL           3      The row the click occured on.
     MOUSE_CLICK_TIME    4      The time when the click occured.
     MOUSE_TYPE          5      The type of mouse click(SINGLE or DOUBLE).
                                The values are represented by manifest contants
                                defined in MOUSE.CH in a table that
                                follows.
     --------------------------------------------------------------------------

     MOUSE_VALUE:  The following constants represent the button pressed
     found in element one of the returned array of InMouse().
     --------------------------------------------------------------------------
     Constant           Value   Element representation
     --------------------------------------------------------------------------
     MOUSE_LEFT          1      The left button was pressed.
     MOUSE_RIGHT         2      The right button was pressed.
     MOUSE_BOTH          3      Both the left and right buttons were pressed.
     MOUSE_MIDDLE        4      The middle button was pressed.
     --------------------------------------------------------------------------

     MOUSE_TYPE:  The following constants represent the CLICK type found
     in element five of the returned array of InMouse().
     --------------------------------------------------------------------------
     Constant           Value   Element representation
     --------------------------------------------------------------------------
     MOUSE_SINGLE_CLICK  1      A single click.
     MOUSE_DOUBLE_CLICK  2      A double click.  A DOUBLE click occurs when
                                two clicks of the SAME button occur within
                                a timeout period.
     --------------------------------------------------------------------------

 Example:

     // Beginning of File.
     #include "mouse.ch"

     LOCAL nKey,aEvent,cMessage

     // Wait for user input.
     DO WHILE ((nKey := INKEY()) == 0) .AND. (LEN(aEvent := InMouse()) == 0))
     ENDDO

     DO CASE
         CASE nKey != 0
            @ 0,0 SAY "A Key Was Pressed: " + STR(nKey)

         OTHERWISE
            cMessage := "A Mouse Button Was Pressed:"
            DO CASE
               CASE aEvent[MOUSE_TYPE] == MOUSE_SINGLE_CLICK
                  cMessage += " SINGLE "
               CASE aEvent[MOUSE_TYPE] == MOUSE_DOUBLE_CLICK
                  cMessage += " DOUBLE "
            ENDCASE

            DO CASE
               CASE aEvent[MOUSE_VALUE] == MOUSE_BOTH
                  cMessage += " Both buttons "
               CASE aEvent[MOUSE_VALUE] == MOUSE_LEFT
                  cMessage += " Left button "
               CASE aEvent[MOUSE_VALUE] == MOUSE_RIGHT
                  cMessage += " Right button "
               CASE aEvent[MOUSE_VALUE] == MOUSE_MIDDLE
                  cMessage += " Middle button"
            ENDCASE

            cMessage += " at row " + STR(aEvent[MOUSE_ROW],2) +;
               ", at col " + STR(aEvent[MOUSE_COL],2)

            @ 0,0 SAY cMessage
     ENDCASE
     QUIT
     // End of File.


 Files:  Library is MOUSE.LIB and MOUSE.CH.