freepascal.compiler/docs/mouse.tex

\chapter{The Mouse unit}

The mouse unit provides basic Mouse handling under Dos (Go32v1 and Go32v2)

Some general remarks about the mouse unit:

\begin{itemize}
\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 coordinates you give to the
driver and divide the ones you get from it by 2.

\item By default the mouse 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/functinos 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}

\function{GetLastButtonPress}{(Button: Longint; Var x,y:Longint)}{Longint}{ 
\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.

For two-button mice, checking the status of the middle button seems to give
and clear the stats of the right button.
}{None.}{\seef{GetLastButtonRelease}}

\latex{\inputlisting{mouseex/mouse5.pp}}
\html{\input{mouseex/mouse5.tex}}

\function{GetLastButtonRelease}{(Button: Longint; Var x,y:Longint)}{Longint}{
\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.

For two-button mice, checking the stats of the middle button seems to give
and clear the stats of the right button.
}{None.}{\seef{GetLastButtonPress}}

For an example, see \seef{GetLastButtonPress}.

\procedure{GetMouseState}{(Var x, y, buttons: Longint)}{
\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.
}{None.}{\seef{LPressed}, \seef{MPressed}, \seef{RPressed},
\seep{SetMousePos}}


\latex{\inputlisting{mouseex/mouse3.pp}}
\html{\input{mouseex/mouse3.tex}}

\Procedure{HideMouse}{
\var{HideMouse} makes the mouse cursor invisible.

Multiple calls to HideMouse will require just as many calls to ShowMouse to
make the mouse cursor again visible.
}{None.}{\seep{ShowMouse}, \seep{SetMouseHideWindow}}

For an example, see \seep{ShowMouse}.

\Procedure{InitMouse}{
\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.
}{None.}{\var{MouseFound} variable.}

\latex{\inputlisting{mouseex/mouse1.pp}}
\html{\input{mouseex/mouse1.tex}}

\Function{LPressed}{Boolean}{

\var{LPressed} returns \var{True} if the left mouse button is pressed.

This is simply a wrapper for the GetMouseState procedure.
}{None.}{\seep{GetMouseState}, \seef{MPressed}, \seef{RPressed}}


For an example, see \seep{GetMouseState}.

\Function{MPressed}{Boolean}{
\var{MPressed} returns \var{True} if the middle mouse button is pressed.

This is simply a wrapper for the GetMouseState procedure.
}{None.}{\seep{GetMouseState}, \seef{LPressed}, \seef{RPressed}}

For an example, see \seep{GetMouseState}.

\Function{RPressed}{Boolean}{
\var{RPressed} returns \var{True} if the right mouse button is pressed.

This is simply a wrapper for the GetMouseState procedure.
}{None.}{\seep{GetMouseState}, \seef{LPressed}, \seef{MPressed}}

For an example, see \seep{GetMouseState}.

\procedure{SetMouseAscii}{(Ascii: Byte)}{
\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.
}{None}{\seep{SetMouseShape}}

\latex{\inputlisting{mouseex/mouse8.pp}}
\html{\input{mouseex/mouse8.tex}}



\procedure{SetMouseHideWindow}{(xmin,ymin,xmax,ymax: Longint)}{
\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, when 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.
}{None.}{\seep{ShowMouse}, \seep{HideMouse}}


\latex{nputlisting{mouseex/mouse1.pp}}
\html{\input{mouseex/mouse1.tex}}

\procedure{SetMousePos}{(x,y:Longint)}{
\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.
}{None.}{\seep{GetMouseState}}


\latex{\inputlisting{mouseex/mouse4.pp}}
\html{\input{mouseex/mouse4.tex}}

\procedure{SetMouseShape}{(ForeColor,BackColor,Ascii: Byte)}{
\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.
}{None.}{\seep{SetMouseAscii}}


\latex{\inputlisting{mouseex/mouse7.pp}}
\html{\input{mouseex/mouse7.tex}}

\procedure{SetMouseSpeed}{(Horizontal, Vertical: Longint)}{
\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.
}{None.}{}

\latex{\inputlisting{mouseex/mouse10.pp}}
\html{\input{mouseex/mouse10.tex}}

\procedure{SetMouseWindow}{(xmin,ymin,xmax,ymax: Longint)}{

\var{SetMousWindow}
defines a rectangle on screen with top-left corner at (\var{xmin,ymin}) and
botto-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.
}{None.}{\seep{SetMouseXRange}, \seep{SetMouseYRange}}

For an example, see \seep{SetMouseXRange}.

\procedure{SetMouseXRange}{(Min, Max: Longint)}{ 
\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.
}{None.}{\seep{SetMouseYRange}, \seep{SetMouseWindow}}

\latex{\inputlisting{mouseex/mouse6.pp}}
\html{\input{mouseex/mouse6.tex}}

\procedure{SetMouseYRange}{(Min, Max: Longint)}{
\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.
}{None.}{\seep{SetMouseXRange}, \seep{SetMouseWindow}}

For an example, see \seep{SetMouseXRange}.

\Procedure{ShowMouse}{
\var{ShowMouse} makes the mouse cursor visible.

At the start of your progam, the mouse is invisible.
}{None.}{\seep{HideMouse},\seep{SetMouseHideWindow}}

\latex{\inputlisting{mouseex/mouse2.pp}}
\html{\input{mouseex/mouse2.tex}}