+ Renamed from mouse to msmouse

docs/msmouse.tex

@@ -0,0 +1,368 @@
+\chapter{The MsMouse unit}
+The msmouse unit provides basic mouse handling under \dos (Go32v1 and Go32v2)
+Some general remarks about the msmouse 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 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}
+\latex{\lstinputlisting{mouseex/mouse5.pp}}
+\html{\input{mouseex/mouse5.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse3.pp}}
+\html{\input{mouseex/mouse3.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse1.pp}}
+\html{\input{mouseex/mouse1.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse8.pp}}
+\html{\input{mouseex/mouse8.tex}}
+\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}
+\latex{nputlisting{mouseex/mouse9.pp}}
+\html{\input{mouseex/mouse9.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse4.pp}}
+\html{\input{mouseex/mouse4.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse7.pp}}
+\html{\input{mouseex/mouse7.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse10.pp}}
+\html{\input{mouseex/mouse10.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse6.pp}}
+\html{\input{mouseex/mouse6.tex}}
+\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}
+\latex{\lstinputlisting{mouseex/mouse2.pp}}
+\html{\input{mouseex/mouse2.tex}}
+