/*
 * $Id: mouse2.txt 16297 2011-02-14 10:28:37Z vszakats $
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MINIT()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Initialize the mouse driver, vars and return status of mouse
 *  $SYNTAX$
 *     FT_MINIT() -> lMouseStatus
 *  $ARGUMENTS$
 *     NONE
 *  $RETURNS$
 *     An logical representing the mouse status (.F. == mouse not installed)
 *  $DESCRIPTION$
 *     Initializes the mouse drive, associated variables and returns mouse
 *     status. It checks to see if the mouse has been previously initialized
 *     and if so it does not reinitialize. The row and column limits of mouse
 *     movement is set to the maximum for the current video mode.
 *     Use FT_MSHOWCRS() to display the mouse cursor.
 *  $EXAMPLES$
 *     IF .NOT. FT_MINIT()
 *        ? "No mouse driver is installed"
 *     ENDIF
 *  $SEEALSO$
 *     FT_MRESET()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MRESET()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Reset mouse driver and return status of mouse
 *  $SYNTAX$
 *     FT_MRESET() -> nMouseStatus
 *  $ARGUMENTS$
 *     NONE
 *  $RETURNS$
 *     An integer representing the mouse status (0 == mouse not installed)
 *  $DESCRIPTION$
 *     Resets the mouse driver and returns mouse status. Use FT_MSHOWCRS()
 *     to display the mouse cursor. The mouse is set to allow it to cover the
 *     complete screen (as defined by MAXCOL() and MAXROW()). This is necessary
 *     because at least some versions of the mouse drivers do not operate
 *     according to the documentation when confronted with a 43 or 50 line
 *     screen.
 *
 *     Normally, FT_MINIT() should be used to initialize the mouse since it
 *     will not reinitialize if already done.
 *  $EXAMPLES$
 *     IF Empty( FT_MRESET() )
 *        ? "No mouse driver is installed"
 *     ENDIF
 *  $SEEALSO$
 *      FT_MINIT() FT_MSHOWCRS()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MCURSOR()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Set the mouse cursor
 *  $SYNTAX$
 *     FT_MCURSOR( [ <lState> ] ) -> lCursorState
 *  $ARGUMENTS$
 *     <lState> is a logical indicating whether to set the mouse cursor on.
 *              .T. - set mouse cursor on
 *              .F. - set mouse cursor off
 *              If omitted, no change is made to cursor state
 *  $RETURNS$
 *     A logical indicating the previous mouse cursor state.
 *  $DESCRIPTION$
 *     This function works like most Clipper state functions.  If no value
 *     is sent to FT_MCURSOR() it will return the state of the mouse cursor.
 *  $EXAMPLES$
 *     IF !( FT_MCURSOR() )
 *        FT_MCURSOR( .T. )
 *     ENDIF
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MSHOWCRS()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Increment internal cursor flag and display mouse cursor
 *  $SYNTAX$
 *     FT_MSHOWCRS() -> NIL
 *  $ARGUMENTS$
 *     NONE
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     Displays the mouse cursor. Make sure to turn the mouse cursor off
 *     when redrawing screens.  The mouse cursor dutifully saves the screen
 *     under it, so if you draw over the mouse cursor it will create a "hole"
 *     in your screen when you move the mouse cursor.
 *
 *     Note: A call to FT_MHIDECRS() decrements a mouse driver variable
 *     which indicates whether the cursor is shown. The cursor is visible
 *     only when the variable = 0. Thus multiple calls to FT_MHIDECRS()
 *     require an equal number of calls to FT_MSHOWCRS() before the cursor
 *     will again be visible. Once the variable is 0 calls to FT_MSHOWCRS()
 *     does not increment the variable above 0.
 *  $EXAMPLES$
 *     IF Empty( FT_MRESET() )
 *        FT_MSHOWCRS()
 *     ENDIF
 *  $SEEALSO$
 *      FT_MHIDECRS() FT_MCONOFF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MHIDECRS()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Decrement internal mouse cursor flag and hide mouse cursor
 *  $SYNTAX$
 *     FT_MHIDECRS() -> NIL
 *  $ARGUMENTS$
 *     NONE
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     Hides the mouse cursor. Make sure to turn the mouse cursor off when
 *     redrawing screens.  The mouse cursor dutifully saves the screen
 *     under it, so if you draw over the mouse cursor it will create a
 *     "hole" in your screen when you move the mouse cursor.
 *
 *     Note: A call to FT_MHIDECRS() decrements a mouse driver variable
 *     which indicates whether the cursor is shown. The cursor is visible
 *     only when the variable = 0. Thus multiple calls to FT_MHIDECRS()
 *     require an equal number of calls to FT_MSHOWCRS() before the cursor
 *     will again be visible. Once the variable is 0 calls to FT_MSHOWCRS()
 *     does not increment the varaible above 0.
 *  $EXAMPLES$
 *     FT_MHIDECRS()
 *     @ 10, 10 to 20, 20
 *     FT_MSHOWCRS()
 *  $SEEALSO$
 *     FT_MSHOWCRS() FT_MCONOFF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MGETPOS()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Get mouse cursor position and button status
 *  $SYNTAX$
 *     FT_MGETPOS( @<nX>, @<nY> ) -> nButtonStatus
 *  $ARGUMENTS$
 *     <nX> is a variable that will receive the mouse X position in virtual
 *     screen coordinates.  It must be passed by reference.
 *
 *     <nY> is a variable that will receive the mouse Y position in virtual
 *     screen coordinates.  It must be passed by reference.
 *  $RETURNS$
 *     an integer representing button status
 *
 *           - 0 for no button pressed
 *           - 1 for left pressed
 *           - 2 for right pressed
 *           - 3 for left and right pressed
 *           - 4 for middle pressed
 *           - 5 for left and middle pressed
 *           - 6 for right and middle pressed
 *           - 7 for all three buttons pressed
 *  $DESCRIPTION$
 *     Loads cursor position into x and y coordinates passed by reference and
 *     returns the button status. The coordinate system in text mode has
 *     eight virtual coordinates per character cell. Thus x=16 means that you
 *     are in the Row 2. The values returned by this routine when in text mode
 *     and with mouse driver versions 6 and above are multiples of 8. We have
 *     experience with drivers prior to that version
 *  $EXAMPLES$
 *     LOCAL nX, nY
 *     LOCAL nButton := FT_MGETPOS( @nX, @nY )
 *     ? "Mouse Row    :", nX
 *     ? "Mouse Column :", nY
 *     ? "Button Status:", nButton
 *  $SEEALSO$
 *     FT_MGETCOORD() FT_MSETPOS() FT_MDEFCRS() FT_MGETX() FT_MGETY()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MGETCOORD()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Get mouse cursor position (text coord.) and button status
 *  $SYNTAX$
 *     FT_MGETPOS( @<nX>, @<nY> ) -> nButtonStatus
 *  $ARGUMENTS$
 *     <nX> is a variable that will receive the mouse X position in text
 *     screen coordinates.  It must be passed by reference.
 *
 *     <nY> is a variable that will receive the mouse Y position in text
 *     screen coordinates.  It must be passed by reference.
 *  $RETURNS$
 *     an integer representing button status
 *
 *           - 0 for no button pressed
 *           - 1 for left pressed
 *           - 2 for right pressed
 *           - 3 for left and right pressed
 *           - 4 for middle pressed
 *           - 5 for left and middle pressed
 *           - 6 for right and middle pressed
 *           - 7 for all three buttons pressed
 *  $DESCRIPTION$
 *     Loads cursor position into x and y coordinates passed by reference and
 *     returns the button status.
 *  $EXAMPLES$
 *     LOCAL nX, nY
 *     LOCAL nButton := FT_MGETCOORD( @nX, @nY )
 *     ? "Mouse Row    :", nX
 *     ? "Mouse Column :", nY
 *     ? "Button Status:", nButton
 *  $SEEALSO$
 *     FT_MGETPOS() FT_MSETPOS() FT_MDEFCRS() FT_MGETX() FT_MGETY()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MGETX()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Get mouse cursor row position
 *  $SYNTAX$
 *     FT_MGETX() -> nRowPos
 *  $ARGUMENTS$
 *     NONE
 *  $RETURNS$
 *     <nRowPos> which is the row position of mouse in virtual screen
 *               coordinates.
 *  $DESCRIPTION$
 *     Retrieves mouse's row position in virtual screen coordinates. The
 *     values returned are multiples of 8 when in text mode and with at least
 *     Microsoft drivers 6 and above.
 *  $EXAMPLES$
 *     ? FT_MGETX()
 *  $SEEALSO$
 *      FT_MGETCOORD() FT_MDEFCRS() FT_MGETPOS() FT_MGETY()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MGETY()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Get mouse cursor column position
 *  $SYNTAX$
 *     FT_MGETY() -> nColPos
 *  $ARGUMENTS$
 *     NONE
 *  $RETURNS$
 *     <nColPos> Column position of mouse in virtual screen coordinates
 *  $DESCRIPTION$
 *     Retrieves mouse's column position in virtual screen coordinates. The
 *     values returned are multiples of 8 when in text mode and with at least
 *     Microsoft drivers 6 and above.
 *  $EXAMPLES$
 *     ? FT_MGETY()
 *  $SEEALSO$
 *     FT_MGETCOORD() FT_MDEFCRS() FT_MGETPOS() FT_MGETX()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MSETPOS()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Position the mouse cursor using virtual screen coordinates
 *  $SYNTAX$
 *     FT_MSETPOS( <nX>, <nY> ) -> NIL
 *  $ARGUMENTS$
 *     <nX> is the desired mouse row.
 *
 *     <nY> is the desired mouse column.
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     Positions mouse cursor on screen. The virtual coordinate system in text
 *     mode has eight virtual coordinates per character cell. Thus x=16 means
 *     that you are in the Row 2.
 *  $EXAMPLES$
 *     FT_MSETPOS( 10, 20 )     // position mouse cursor at row 10, col 20
 *                              // in virtual screen coordinates
 *  $SEEALSO$
 *     FT_MGETPOS() FT_MGETCOORD() FT_MSETCOORD() FT_MGETX() FT_MGETY()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MSETCOORD()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Position the mouse cursor using text screen coordinates
 *  $SYNTAX$
 *     FT_MSETPOS( <nX>, <nY> ) -> NIL
 *  $ARGUMENTS$
 *     <nX> is the desired mouse row.
 *
 *     <nY> is the desired mouse column.
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     Positions mouse cursor on screen using text (normal row and column)
 *     coordinates.
 *  $EXAMPLES$
 *     FT_MSETCOORD( 10, 20 )     // position mouse cursor at row 10, col 20
 *                              // in text screen coordinates
 *  $SEEALSO$
 *     FT_MGETPOS() FT_MGETCOORD() FT_MSETPOS() FT_MDEFCRS() FT_MGETX() FT_MGETY()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MXLIMIT()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Set vertical bounds of mouse using virtual screen coord.
 *  $SYNTAX$
 *     FT_MXLIMIT( <nX1>, <nX2> ) -> NIL
 *  $ARGUMENTS$
 *     <nX1> is the top row limit.
 *
 *     <nX2> is the bottom row limit.
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     Set maximum vertical bounds of mouse using virtual screen coordinates.
 *  $EXAMPLES$
 *     FT_MXLIMIT( 10, 20 )
 *  $SEEALSO$
 *      FT_MYLIMIT() FT_MINREGION()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MYLIMIT()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Set horiz. bounds of mouse using virtual screen coordinates
 *  $SYNTAX$
 *     FT_MYLIMIT( <nY1>, <nY2> ) -> NIL
 *  $ARGUMENTS$
 *     <nY1> is the left column limit.
 *
 *     <nY2> is the right column limit.
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     Set maximum horizontal bounds of mouse using virtual screen coordinates.
 *  $EXAMPLES$
 *     FT_MYLIMIT( 10, 20 )
 *  $SEEALSO$
 *      FT_MXLIMIT() FT_MINREGION()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MBUTPRS()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Retrieve button press status
 *  $SYNTAX$
 *     FT_MBUTPRS( <nButton> [, @nButPrs [, @nX [, @nY] ] ] ) -> nButStatus
 *  $ARGUMENTS$
 *     <nButton> is the mouse button number:
 *
 *                0 - Left   Button
 *                1 - Right  Button
 *                2 - Middle Button [if applicable]
 *
 *     <nButPrs> is the number of times the specified button was pressed
 *               since the last call to this routine. PASSED BY REFERENCE.
 *     <nX> is the X position of the cursor when the last press occurred.
 *               PASSED BY REFERENCE.
 *     <nY> is the Y position of the cursor when the last press occurred.
 *               PASSED BY REFERENCE.
 *
 *  $RETURNS$
 *     An integer representing the button status:
 *
 *                0 - no buttons pressed
 *                1 - left button pressed
 *                2 - right button pressed
 *                3 - left and right pressed
 *                4 - middle pressed
 *                5 - left and middle pressed
 *                6 - middle and right buttons pressed
 *                7 - all 3 buttons pressed
 *  $DESCRIPTION$
 *     Retrieves the mouse button status and the position of the cursor when
 *     a button was last pressed.
 *  $EXAMPLES$
 *     IF Empty( FT_MBUTPRS(1) )
 *        ? "No Item selected"
 *     ENDIF
 *  $SEEALSO$
 *      FT_MBUTREL() FT_MDBLCLK()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MBUTREL()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Get mouse button release information
 *  $SYNTAX$
 *     FT_MBUTREL( nButton [, @nButRel [, @nX [, @nY] ] ]) -> nBStat
 *  $ARGUMENTS$
 *     <nButton> is the mouse button number
 *               0 - Left   Button
 *               1 - Right  Button
 *               2 - Middle Button [if applicable]
 *
 *     <nButRel> is the number of times the specified button was released
 *               since the last call to this routine. PASSED BY REFERENCE.
 *
 *     <nX> is the X position of the cursor when the last release occurred.
 *               PASSED BY REFERENCE.
 *
 *     <nY> is the Y position of the cursor when the last release occurred.
 *               PASSED BY REFERENCE.
 *  $RETURNS$
 *     <nBStat>  - an integer representing button release status
 *                 0 - None
 *                 1 - Left
 *                 2 - Right
 *                 3 - Middle
 *  $DESCRIPTION$
 *     This function returns the release status of the mouse buttons and the
 *     coordinates of the last release.
 *  $EXAMPLES$
 *     IF FT_MBUTREL( 0 ) == 1
 *        ? "Left button released"
 *     ENDIF
 *  $SEEALSO$
 *     FT_MBUTPRS() FT_MDBLCLK()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_MDEFCRS()
 *  $CATEGORY$
 *     Keyboard/Mouse
 *  $ONELINER$
 *     Define the mouse cursor
 *  $SYNTAX$
 *     FT_MDEFCRS( <nCrsType>, <nScrMask>, <nCrsMask> ) -> NIL
 *  $ARGUMENTS$
 *     <nCrsType> is the cursor type. A value of 0 indicates the software cursor
 *                (the default) and a value of 1 indicates the hardware cursor.
 *
 *     <nScrMask> is the screen mask for the software cursor or the first scan
 *                line of the hardware cursor. See the description for more
 *                information.
 *
 *     <nCrsMask> is the cursor mask for the software cursor of the last scan
 *                line of the hardware cursor. See the description for more
 *                information.
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     In text mode the mouse cursor can either be a software generated or
 *     the actual hardware cursor. This routine allows one choose between them.
 *     The software cursor is the default and its effect on the character it
 *     covers is determined by the screen mask and the cursor mask. Both of
 *     these masks are 16 bit values (which in Clipper are passed as standard
 *     numerical values). The 16 bit masks are arranged in a manner identical
 *     to the way information is stored for each character cell on the screen.
 *     The low order 8 bits represent the actual character displayed while the
 *     high order bits represent the display atributes such as blinking,
 *     intensity and forground and background colors. The mask is represented in
 *     the diagram below:
 *
 *     Bit:     15    14      1211       10       87       0
 *     Function:blink backgroundintensityforegroundcharacter
 *
 *     Blinking and high intensity are on when the bit is 1. The background and
 *     foreground indicate which colors are used for each. The software mouse
 *     cursor uses these two values by taking the mask from the screen cell it
 *     is on and performing a logical AND on each bit with the screen mask
 *     value. The result is then logically XOR'ed with the cursor mask value.
 *     Thus to keep the character the same but invert the foreground and
 *     background colors the following values would be used:
 *
 *     Bit:     15    14      1211       10       87       0
 *     Function:blink backgroundintensityforegroundcharacter
 *     screen:    0      111        0       111    11111111  =30719
 *     cursor:    0      111        0       111    00000000  =30464
 *
 *     The hardware cursor is the text cursor provided by the video board. One
 *     specifies the range of scan lines which are on using <nScrMask> and
 *     <nCrsMask>. The range of values is dependant upon the type of monitor.
 *     The first scan line is 0.
 *  $END$
 */
