freepascal.compiler/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 you write 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 you want to have it 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 you will have to multiply the X coordinates you give to the
driver and divide the ones you get from it by 2 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 if you are sure you are not calling any mouse unit procedures when no
mouse is found, you can recompile the mouse unit without this conditional
define.
\item
You will notice that 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} you can use the 
\var{LButton}, \var{RButton} and \var{MButton} constants 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 you can use the
\var{LButton}, \var{RButton} and \var{MButton} constants 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 you can 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 your program. 
You should never have to call it, unless you want to reset everything 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 you enter is the
character that you 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 you
call \var{ShowMouse} again. However, once you've called \seep{ShowMouse}, you'll have to
call \var{SetMouseHideWindow} 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 you 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 your progam, the mouse cursor is invisible.

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

\FPCexample{mouse2}