+ complete redesign from Jonas

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.
-
-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.
-
-You may wish to undefine the symbol in the source code, and recompile the
-unit, to disable this behaviour.
-
-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.
-
-\section{Constants, Types and variables}
-The \var{MouseFound} variable is set by the \seef{CheckMouse} function.
-\begin{verbatim}
-Var
-  MouseFound:Boolean;
-\end{verbatim}
-
-\section{Functionas and Procedures}
-
-\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.}{}
-
-
-\Procedurel{Hide\_Mouse}{HideMouse}
-{\var{Hide\_Mouse} hides the mouse pointer.}{None.}{\seep{ShowMouse}}
-
-
-\Function{IsRPressed}{Boolean}
-{ \var{IsRPressed} returns \var{True} if the right mouse button is pressed,
-\var{False} otherwise}{\seef{IsLPressed}}
-
-\Function{IsLPressed}{Boolean}
-{ \var{IsRPressed} returns \var{True} if the left mouse button is pressed,
-\var{False} otherwise}{\seef{IsRPressed}}
-
-\procedure{Micky}{(Horizontal,Vertical: Longint)}
-{\var{Micky} sets the mouse speed in horizontal and vertical
-directions}
-{None}
-{}
-
-\procedurel{Mouse\_Ascii}{MouseAscii}{(Ascii:LongInt)}
-{\var{Mouse\_Ascii} sets the mouse ascii in text
-mode.}
-{None.}
-{\seep{MouseShape}}
-
-\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}}
-
-\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}}
-
-\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}}
-
-\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}}
-
-\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}}
-
-\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}}
-
-
-\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}}
-
-\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.}{}
+\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{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}}
+
+
+\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}}
+
+
+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}}
+
+\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}}
+
+
+\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}