mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-08-30 20:01:27 +02:00
+ complete redesign from Jonas
This commit is contained in:
michael
parent
b4cdf24729
commit
2b7cd8c715
350
docs/mouse.tex
350
docs/mouse.tex
@ -1,156 +1,244 @@
|
||||
%
|
||||
% $Id$
|
||||
% This file is part of the FPC documentation.
|
||||
% Copyright (C) 1998, 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.
|
||||
%
|
||||
\chapter{The MOUSE unit}
|
||||
\label{ch:mouse}
|
||||
This chapter describes the \var{mouse} unit. It is implemented for \dos only.
|
||||
\chapter{The Mouse unit}
|
||||
|
||||
By default, the \var{Mouse} unit is compiled with the \var{MOUSECHECK}
|
||||
symbol defined.
|
||||
This ensures that all functions check if the mouse is installed or not, and
|
||||
to exit gracefully if the mouse isn't installed.
|
||||
The mouse unit provides basic Mouse handling under Dos (Go32v1 and Go32v2)
|
||||
|
||||
You may wish to undefine the symbol in the source code, and recompile the
|
||||
unit, to disable this behaviour.
|
||||
Some general remarks about the mouse unit:
|
||||
|
||||
The first section lists constants, types and variables introduced in the mouse unit
|
||||
and the second section lists all functions and procedures in alphabetical
|
||||
order.
|
||||
\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).
|
||||
|
||||
\section{Constants, Types and variables}
|
||||
The \var{MouseFound} variable is set by the \seef{CheckMouse} function.
|
||||
\begin{verbatim}
|
||||
Var
|
||||
MouseFound:Boolean;
|
||||
\end{verbatim}
|
||||
\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).
|
||||
|
||||
\section{Functionas and Procedures}
|
||||
\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.
|
||||
|
||||
\Functionl{Check\_Mouse}{CheckMouse}{Boolean}
|
||||
{\var{Check\_Mouse} checks if the mousedriver is present and sets the
|
||||
\var{MouseFound} variable to \var{True} if so.}
|
||||
{None.}{}
|
||||
\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{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}}
|
||||
|
||||
\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}}
|
||||
|
||||
|
||||
\Procedurel{Hide\_Mouse}{HideMouse}
|
||||
{\var{Hide\_Mouse} hides the mouse pointer.}{None.}{\seep{ShowMouse}}
|
||||
\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.}
|
||||
|
||||
\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}}
|
||||
|
||||
|
||||
\Function{IsRPressed}{Boolean}
|
||||
{ \var{IsRPressed} returns \var{True} if the right mouse button is pressed,
|
||||
\var{False} otherwise}{\seef{IsLPressed}}
|
||||
For an example, see \seep{GetMouseState}.
|
||||
|
||||
\Function{IsLPressed}{Boolean}
|
||||
{ \var{IsRPressed} returns \var{True} if the left mouse button is pressed,
|
||||
\var{False} otherwise}{\seef{IsRPressed}}
|
||||
\Function{MPressed}{Boolean}{
|
||||
\var{MPressed} returns \var{True} if the middle mouse button is pressed.
|
||||
|
||||
\procedure{Micky}{(Horizontal,Vertical: Longint)}
|
||||
{\var{Micky} sets the mouse speed in horizontal and vertical
|
||||
directions}
|
||||
{None}
|
||||
{}
|
||||
This is simply a wrapper for the GetMouseState procedure.
|
||||
}{None.}{\seep{GetMouseState}, \seef{LPressed}, \seef{RPressed}}
|
||||
|
||||
\procedurel{Mouse\_Ascii}{MouseAscii}{(Ascii:LongInt)}
|
||||
{\var{Mouse\_Ascii} sets the mouse ascii in text
|
||||
mode.}
|
||||
{None.}
|
||||
{\seep{MouseShape}}
|
||||
For an example, see \seep{GetMouseState}.
|
||||
|
||||
\Function{MouseButtons}{longint}
|
||||
{ \var{MouseButtons} returns which mouse buttons are pressed. The pressed
|
||||
buttones are bit encoded in bits 0-2}{None.}{\seef{MouseX}, \seef{MouseY}}
|
||||
\Function{RPressed}{Boolean}{
|
||||
\var{RPressed} returns \var{True} if the right mouse button is pressed.
|
||||
|
||||
\procedurel{Mouse\_Cur}{MouseCur}{(X,Y:Longint)}
|
||||
{\var{Mouse\_Cur} sets mouse pointer on \var{X,Y} where \var{X} is the
|
||||
horizontal coordinate, \var{Y} is the vertical coordinate. You The
|
||||
coordinates are those you would set in text mode, multiplied by 8.}
|
||||
{None}{\seep{ReadMouse}}
|
||||
This is simply a wrapper for the GetMouseState procedure.
|
||||
}{None.}{\seep{GetMouseState}, \seef{LPressed}, \seef{MPressed}}
|
||||
|
||||
\functionl{Mouse\_Press}{MousePress}{(var x,y: Longint; button: Longint)}{Longint}
|
||||
{\var{Mouse\_Press} returns which buttons were pressed after the last call to
|
||||
this function. It returns the same data as the \seep{ReadMouse}
|
||||
procedure}
|
||||
{None.}
|
||||
{\seep{ReadMouse}, \seef{MouseRelease}}
|
||||
For an example, see \seep{GetMouseState}.
|
||||
|
||||
\functionl{Mouse\_Release}{MouseRelease}{(var Row,Col : Longint;Button : Longint)}{integer}
|
||||
{\var{Mouse\_Release} returns which button was released after last the call to
|
||||
this function. It returns the position in \var{Row,Col} (text coordinates) and
|
||||
the button number in \var{Button} }
|
||||
{None.}
|
||||
{\seef{MousePress}, \seep{ReadMouse}}
|
||||
\procedure{SetMouseAscii}{(Ascii: Byte)}{
|
||||
\var{SetMouseAscii}
|
||||
sets the \var{Ascii} value of the character that depicts the mouse cursor in
|
||||
text mode.
|
||||
|
||||
\procedurel{Mouse\_Shape}{MouseShape}{(BackColor,ForColor,Ascii:LongInt)}
|
||||
{\var{Mouse\_Shape} changes the shape and color of the text mouse cursor.
|
||||
The colors are specified in \var{BackColor}, \var{ForColor}, and
|
||||
\var{Ascii} is (Guys ??)}
|
||||
{None.}
|
||||
{\seep{MouseAscii}}
|
||||
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}}
|
||||
|
||||
\Function{MouseX}{Longint}
|
||||
{\var{MouseX} returns the mouses X coordinate in textmode units.}{None.}
|
||||
{\seef{MouseY}, \seef{MouseButtons}}
|
||||
|
||||
\procedurel{Mouse\_XRange}{MouseXRange}{(Min,Max: Longint)}
|
||||
{\var{Mouse\_XRange} sets the mouses x range, i.e. the minimal (in
|
||||
\var{Min}) and maximal (in \var{Max}) values that the x-coordinate of the
|
||||
mouse pointer can take.}
|
||||
{None.}
|
||||
{\seep{MouseYRange}, \seep{MWindow}}
|
||||
|
||||
\Function{MouseY}{Longint}
|
||||
{\var{MouseY} returns the mouses X coordinate in textmode units.}{None.}
|
||||
{\seef{MouseY}, \seef{MouseButtons}}
|
||||
|
||||
\procedurel{Mouse\_YRange}{MouseYRange}{(Min,Max: Longint)}
|
||||
{\var{Mouse\_YRange} sets the mouses y range, i.e. the minimal (in
|
||||
\var{Min}) and maximal (in \var{Max}) values that the y-coordinate of the
|
||||
mouse pointer can take.}
|
||||
{None.}
|
||||
{\seep{MouseXRange}, \seep{MWindow}}
|
||||
|
||||
\procedure{MWindow}{(x1,y1,x2,y2: Longint)}
|
||||
{\var{MWindow} defines a rectangle (with corners at \var{(x1,y1)} and
|
||||
\var{(x2,y2)}) on the screen, outside which the mouse cannot be moved.}
|
||||
{None.}{\seep{MouseXRange}, \seep{MouseYRange}}
|
||||
\input {mouseex/mouse8.tex}
|
||||
|
||||
|
||||
\procedurel{Read\_Mouse}{ReadMouse}{(var X,Y:Longint;var Buttons:Longint)}
|
||||
{\var{Read\_Mouse} reads the mouse position in pixels and returns the
|
||||
horizontal position in \var{X} and the vertical position in \var{Y}.
|
||||
(you should divide by 8 to get the text position), and reads the
|
||||
button states. It is a bitwise combination of
|
||||
\begin{description}
|
||||
\item [1] \ for the left button
|
||||
\item [2] \ for the right button
|
||||
\item [7] \ for the middle button
|
||||
\end{description}
|
||||
}{None.}{\seep{MouseCur}}
|
||||
|
||||
\Procedurel{Show\_Mouse}{ShowMouse}
|
||||
{\var{Show\_Mouse} shows the mouse pointer both on text or graphics screens.}
|
||||
{None.}{\seep{HideMouse}}
|
||||
\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.
|
||||
|
||||
\procedurel{Unseen\_Mouse}{(x1,y1,x2,y2: Longint)}
|
||||
{ \var{Unseen\_Mouse} defines a rectangle (with corner points \var{(X1,Y1)}
|
||||
and \var{(X2,Y2)} on the screen in which the mouse will disappear if comes
|
||||
over it.}{None.}{}
|
||||
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}}
|
||||
|
||||
|
||||
\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}}
|
||||
|
||||
|
||||
\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}}
|
||||
|
||||
|
||||
\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.}{}
|
||||
|
||||
\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}}
|
||||
|
||||
\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}}
|
||||
|
||||
\input{mouseex/mouse2.tex}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user