fpc/docs/msmouse.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% The MSMouse unit
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{The MsMouse unit}
\FPCexampledir{mmouseex}

The msmouse unit provides basic mouse handling under \dos (Go32v1 and Go32v2)
Some general remarks about the msmouse unit:
\begin{itemize}
\item For maximum portability, it is advisable to use the \file{mouse} unit;
that unit is portable across platforms, and offers a similar interface.
Under no circumstances should the two units be used together.
\item The mouse driver does not know when the text screen scrolls. This results
in unerased mouse cursors on the screen when the screen scrolls while the
mouse cursor is visible. The solution is to hide the mouse cursor (using
HideMouse) when writing something to the screen and to show it again
afterwards (using ShowMouse).
\item All Functions/Procedures that return and/or accept coordinates of the mouse
cursor, always do so in pixels and zero based (so the upper left corner of
the screen is (0,0)). To get the (column, row) in standard text mode, divide
both x and y by 8 (and add 1 if it must be 1 based).
\item The real resolution of graphic modes and the one the mouse driver uses can
differ. For example, mode 13h (320*200 pixels) is handled by the mouse driver
as 640*200, so the X coordinates given to the
driver must be multiplied by 2 and divided by 2 when the return from the
driver in that mode.
\item By default the msmouse unit is compiled with the conditional define
MouseCheck. This causes every procedure/function of the unit to check the
MouseFound variable prior to doing anything. Of course this is not necessary,
so when proper checking is added to the calling program, this define may be
removed and the unit can be recompiled.
\item Several procedures/functions have longint sized parameters while only 
the lower 16 bits are used. This is because FPC is a 32 bit compiler and 
consequently 32 bit parameters result in faster code.
\end{itemize}
\section{Constants, types and variables}
The following constants are defined (to be used in e.g. the
\seef{GetLastButtonPress} call).
\begin{verbatim}
 LButton = 1; {left button}
 RButton = 2; {right button}
 MButton = 4; {middle button}
\end{verbatim}
The following variable exist: 
\begin{verbatim}
  MouseFound: Boolean;
\end{verbatim}
it is set to \var{True} or \var{False} in the unit's initialization code.
\section{Functions and procedures}
\begin{function}{GetLastButtonPress}
\Declaration
Function GetLastButtonPress (Button: Longint; Var x,y:Longint) : Longint;

\Description
 
\var{GetLastButtonPress}
Stores the position where \var{Button} was last pressed in \var{x} and
\var{y} and returns
the number of times this button has been pressed since the last call to this
function with \var{Button} as parameter. For \var{Button} the 
\var{LButton}, \var{RButton} and \var{MButton} constants can be used for resp. the left, 
right and middle button.
With certain mouse drivers, checking the middle button when using a
two-button mouse to gives and clears the stats of the right button.

\Errors
None.
\SeeAlso
\seef{GetLastButtonRelease}
\end{function}

\FPCexample{mouse5}

\begin{function}{GetLastButtonRelease}
\Declaration
Function GetLastButtonRelease (Button: Longint; Var x,y:Longint) : Longint;

\Description

\var{GetLastButtonRelease}
stores the position where \var{Button} was last released in \var{x} and 
\var{y} and returns
the number of times this button has been released since the last call to this
function with \var{Button} as parameter. For button the
\var{LButton}, \var{RButton} and \var{MButton} constants can be used for resp. 
the left, right and middle button.
With certain mouse drivers, checking the middle button when using a
two-button mouse to gives and clears the stats of the right button.

\Errors
None.
\SeeAlso
\seef{GetLastButtonPress}
\end{function}

For an example, see \seef{GetLastButtonPress}.

\begin{procedure}{GetMouseState}
\Declaration
Procedure GetMouseState (Var x, y, buttons: Longint);

\Description

\var{GetMouseState} Returns information on the current mouse position 
and which buttons are currently pressed.
\var{x} and \var{y} return the mouse cursor coordinates in pixels.
\var{Buttons} is a bitmask. Check the example program to see how to get the
necessary information from it.

\Errors
None.
\SeeAlso
\seef{LPressed}, \seef{MPressed}, \seef{RPressed},
\seep{SetMousePos}
\end{procedure}

\FPCexample{mouse3}

\begin{procedure}{HideMouse}
\Declaration
Procedure HideMouse ;

\Description

\var{HideMouse} makes the mouse cursor invisible.
Multiple calls to HideMouse will require just as many calls to ShowMouse to
make the mouse cursor visible again.

\Errors
None.
\SeeAlso
\seep{ShowMouse}, \seep{SetMouseHideWindow}
\end{procedure}
For an example, see \seep{ShowMouse}.
\begin{procedure}{InitMouse}
\Declaration
Procedure InitMouse ;

\Description

\var{InitMouse}
Initializes the mouse driver sets the variable \var{MouseFound} depending on
whether or not a mouse is found. This is Automatically called at the start of 
a program. Normally it should never be called, unless everything should be
reset to its default values.

\Errors
None.
\SeeAlso
\var{MouseFound} variable.
\end{procedure}

\FPCexample{mouse1}

\begin{function}{LPressed}
\Declaration
Function LPressed  : Boolean;

\Description

\var{LPressed} returns \var{True} if the left mouse button is pressed.
This is simply a wrapper for the GetMouseState procedure.

\Errors
None.
\SeeAlso
\seep{GetMouseState}, \seef{MPressed}, \seef{RPressed}
\end{function}

For an example, see \seep{GetMouseState}.

\begin{function}{MPressed}
\Declaration
Function MPressed  : Boolean;

\Description

\var{MPressed} returns \var{True} if the middle mouse button is pressed.
This is simply a wrapper for the GetMouseState procedure.

\Errors
None.
\SeeAlso
\seep{GetMouseState}, \seef{LPressed}, \seef{RPressed}
\end{function}

For an example, see \seep{GetMouseState}.

\begin{function}{RPressed}
\Declaration
Function RPressed  : Boolean;

\Description

\var{RPressed} returns \var{True} if the right mouse button is pressed.
This is simply a wrapper for the GetMouseState procedure.

\Errors
None.
\SeeAlso
\seep{GetMouseState}, \seef{LPressed}, \seef{MPressed}
\end{function}

For an example, see \seep{GetMouseState}.

\begin{procedure}{SetMouseAscii}
\Declaration
Procedure SetMouseAscii (Ascii: Byte);

\Description

\var{SetMouseAscii}
sets the \var{Ascii} value of the character that depicts the mouse cursor in 
text mode.
The difference between this one and \seep{SetMouseShape}, is that the foreground
and background colors stay the same and that the Ascii code entered is the
character that will get on screen; there's no XOR'ing.

\Errors
None
\SeeAlso
\seep{SetMouseShape}
\end{procedure}

\FPCexample{mouse8}

\begin{procedure}{SetMouseHideWindow}
\Declaration
Procedure SetMouseHideWindow (xmin,ymin,xmax,ymax: Longint);

\Description

\var{SetMouseHideWindow}
defines a rectangle on screen with top-left corner at (\var{xmin,ymin}) and
botto-right corner at (\var{xmax,ymax}),which causes the mouse cursor to be 
turned off when it is moved into it.
When the mouse is moved into the specified region, it is turned off until 
call \var{ShowMouse} is called again. However, once \seep{ShowMouse} is
called,  \var{SetMouseHideWindow} must be called again to redefine the hide window... 
This may be annoying, but it's the way it's implemented in the mouse driver.
While \var{xmin, ymin, xmax} and \var{ymax} are Longint parameters, 
only the lower 16 bits are used.

Warning: it seems Win98 SE doesn't (properly) support this function,
maybe this already the case with earlier versions too!

\Errors
None.
\SeeAlso
\seep{ShowMouse}, \seep{HideMouse}
\end{procedure}

\FPCexample{mouse9}

\begin{procedure}{SetMousePos}
\Declaration
Procedure SetMousePos (x,y:Longint);

\Description

\var{SetMosusePos} sets the position of the mouse cursor on the screen.
\var{x} is the horizontal position in pixels, \var{y} the vertical position
in pixels. The upper-left hand corner of the screen is the origin.
While \var{x} and \var{y} are longints, only the lower 16 bits are used.

\Errors
None.
\SeeAlso
\seep{GetMouseState}
\end{procedure}

\FPCexample{mouse4}

\begin{procedure}{SetMouseShape}
\Declaration
Procedure SetMouseShape (ForeColor,BackColor,Ascii: Byte);

\Description

\var{SetMouseShape}
defines how the mouse cursor looks in textmode
The character and its attributes that are on the mouse cursor's position on
screen are XOR'ed with resp. \var{ForeColor}, \var{BackColor} and
\var{Ascii}. Set them all to 0 for a "transparent" cursor.

\Errors
None.
\SeeAlso
\seep{SetMouseAscii}
\end{procedure}

\FPCexample{mouse7}

\begin{procedure}{SetMouseSpeed}
\Declaration
Procedure SetMouseSpeed (Horizontal, Vertical: Longint);

\Description

\var{SetMouseSpeed} sets the mouse speed in mickeys per 8 pixels.
A mickey is the smallest measurement unit handled by a mouse. With this
procedure one can set how many mickeys the mouse should move to move the
cursor 8 pixels horizontally of vertically. The default values are 8 for
horizontal and 16 for vertical movement.
While this procedure accepts longint parameters, only the low 16 bits are
actually used.

\Errors
None.
\SeeAlso

\end{procedure}

\FPCexample{mouse10}

\begin{procedure}{SetMouseWindow}
\Declaration
Procedure SetMouseWindow (xmin,ymin,xmax,ymax: Longint);

\Description

\var{SetMousWindow}
defines a rectangle on screen with top-left corner at (\var{xmin,ymin}) and
bottom-right corner at (\var{xmax,ymax}), out of which the mouse 
cursor can't move.
This procedure is simply a wrapper for the \seep{SetMouseXRange} and 
\seep{SetMouseYRange} procedures.
While \var{xmin, ymin, xmax} and \var{ymax} are Longint parameters, 
only the lower 16 bits are used.

\Errors
None.
\SeeAlso
\seep{SetMouseXRange}, \seep{SetMouseYRange}
\end{procedure}

For an example, see \seep{SetMouseXRange}.

\begin{procedure}{SetMouseXRange}
\Declaration
Procedure SetMouseXRange (Min, Max: Longint);

\Description
 
\var{SetMouseXRange}
sets the minimum (\var{Min}) and maximum (\var{Max}) horizontal coordinates in between which the
mouse cursor can move.
While \var{Min} and \var{Max} are Longint parameters, only the lower 16 bits 
are used.

\Errors
None.
\SeeAlso
\seep{SetMouseYRange}, \seep{SetMouseWindow}
\end{procedure}

\FPCexample{mouse6}

\begin{procedure}{SetMouseYRange}
\Declaration
Procedure SetMouseYRange (Min, Max: Longint);

\Description

\var{SetMouseYRange}
sets the minimum (\var{Min}) and maximum (\var{Max}) vertical coordinates in between which the
mouse cursor can move.
While \var{Min} and \var{Max} are Longint parameters, only the lower 16 bits 
are used.

\Errors
None.
\SeeAlso
\seep{SetMouseXRange}, \seep{SetMouseWindow}
\end{procedure}

For an example, see \seep{SetMouseXRange}.

\begin{procedure}{ShowMouse}
\Declaration
Procedure ShowMouse ;

\Description

\var{ShowMouse} makes the mouse cursor visible.
At the start of the program, the mouse cursor is invisible.

\Errors
None.
\SeeAlso
\seep{HideMouse},\seep{SetMouseHideWindow}
\end{procedure}

\FPCexample{mouse2}