+ Empty version of API mouse unit documentation

docs/mouse.tex

@@ -1,368 +1,234 @@
-\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).
+%
+%   $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 Mouse unit
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\chapter{The MOUSE unit}
+\FPCexampledir{mousex}
+The \var{Mouse} unit implements a platform independent mouse handling 
+interface. It is implemented identically on all platforms supported by 
+\fpc{} and can be enhanced with custom drivers, should this be needed.
+
+\section{Constants, Types and Variables}
+\subsection{Constants}	
+The following constants can be used when mouse drivers need to report 
+errors:
 \begin{verbatim}
- LButton = 1; {left button}
- RButton = 2; {right button}
- MButton = 4; {middle button}
+const
+  { We have an errorcode base of 1030 }
+  errMouseBase                    = 1030;
+  errMouseInitError               = errMouseBase + 0;
+  errMouseNotImplemented          = errMouseBase + 1;
 \end{verbatim}
-The following variable exist: 
+The following constants describe which action a mouse event describes
 \begin{verbatim}
-  MouseFound: Boolean;
+const
+  MouseActionDown = $0001;  { Mouse down event }
+  MouseActionUp   = $0002;  { Mouse up event }
+  MouseActionMove = $0004;  { Mouse move event }
 \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;
+The following constants describe the used buttons in a mouse event:
+\begin{verbatim}
+  MouseLeftButton   = $01;  { Left mouse button }
+  MouseRightButton  = $02;  { Right mouse button }
+  MouseMiddleButton = $04;  { Middle mouse button }
+\end{verbatim}
+The mouse unit has a mechanism to buffer mouse events. The following
+constant defines the size of the event buffer:
+\begin{verbatim}
+MouseEventBufSize = 16;
+\end{verbatim}
+\subsection{Types}
+The \var{TMouseEvent} is the central type of the mouse unit, it is used
+to describe the mouse events:
+\begin{verbatim}
+PMouseEvent=^TMouseEvent;
+TMouseEvent=packed record { 8 bytes }
+  buttons : word;
+  x,y     : word;
+  Action  : word;
+end;
+\end{verbatim}
+The \var{Buttons} field describes which buttons were down when the event
+occurred. The \var{x,y} fields describe where the event occurred on the
+screen. The \var{Action} describes what action was going on when the event
+occurred. The \var{Buttons} and \var{Action} field can be examined using the
+above constants.
+
+The following record is used to implement a mouse driver in the
+\seep{SetMouseDriver} function:
+\begin{verbatim}
+TMouseDriver = Record 
+  UseDefaultQueue : Boolean;
+  InitDriver : Procedure;
+  DoneDriver : Procedure;
+  DetectMouse : Function : Byte;
+  ShowMouse : Procedure;
+  HideMouse : Procedure;
+  GetMouseX : Function : Word;
+  GetMouseY : Function : Word;
+  GetMouseButtons : Function : Word;
+  SetMouseXY : procedure (x,y:word);
+  GetMouseEvent : procedure (var MouseEvent:TMouseEvent);
+  PollMouseEvent : function (var MouseEvent: TMouseEvent):boolean;
+  PutMouseEvent : procedure (Const MouseEvent:TMouseEvent); 
+end;
+\end{verbatim}
+Its fields will be explained in the section on writing a custom driver.
 
-\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.
+\subsection{Variables}
+The following variables are used to keep the current position and state of
+the mouse.
+\begin{verbatim}
+MouseIntFlag : Byte;  { Mouse in int flag }
+MouseButtons : Byte;  { Mouse button state }
+MouseWhereX,
+MouseWhereY  : Word;  { Mouse position }
+\end{verbatim}
 
-\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;
+\section{Functions and procedures}
 
+\begin{function}{DetectMouse}
+\Declaration
+Function DetectMouse:byte;
 \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.
-
+ { Detect if a mouse is present, returns the amount of buttons or 0  if no mouse is found }
 \Errors
-None.
 \SeeAlso
-\seef{GetLastButtonPress}
 \end{function}
-For an example, see \seef{GetLastButtonPress}.
-\begin{procedure}{GetMouseState}
-\Declaration
-Procedure GetMouseState (Var x, y, buttons: Longint);
 
+\begin{procedure}{DoneMouse}
+\Declaration
+Procedure DoneMouse;
 \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.
-
+ { Deinitialize the mouse interface }
 \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 ;
 
+\begin{function}{GetMouseButtons}
+\Declaration
+Function GetMouseButtons:word;
 \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.
-
+ { Return the current button state of the mouse }
 \Errors
-None.
 \SeeAlso
-\seep{ShowMouse}, \seep{SetMouseHideWindow}
-\end{procedure}
-For an example, see \seep{ShowMouse}.
-\begin{procedure}{InitMouse}
-\Declaration
-Procedure InitMouse ;
+\end{function}
 
+\begin{procedure}{GetMouseDriver}
+\Declaration
+Procedure GetMouseDriver(Var Driver : TMouseDriver);
 \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;
 
+\begin{procedure}{GetMouseEvent}
+\Declaration
+Procedure GetMouseEvent(var MouseEvent:TMouseEvent);
 \Description
-
-\var{LPressed} returns \var{True} if the left mouse button is pressed.
-This is simply a wrapper for the GetMouseState procedure.
-
+ { Returns the last Mouseevent, and waits for one if not available }
 \Errors
-None.
 \SeeAlso
-\seep{GetMouseState}, \seef{MPressed}, \seef{RPressed}
-\end{function}
-For an example, see \seep{GetMouseState}.
-\begin{function}{MPressed}
-\Declaration
-Function MPressed  : Boolean;
+\end{procedure}
 
+\begin{function}{GetMouseX}
+\Declaration
+Function GetMouseX:word;
 \Description
-
-\var{MPressed} returns \var{True} if the middle mouse button is pressed.
-This is simply a wrapper for the GetMouseState procedure.
-
+ { Return the current X position of the mouse }
 \Errors
-None.
 \SeeAlso
-\seep{GetMouseState}, \seef{LPressed}, \seef{RPressed}
 \end{function}
-For an example, see \seep{GetMouseState}.
-\begin{function}{RPressed}
-\Declaration
-Function RPressed  : Boolean;
 
+\begin{function}{GetMouseY}
+\Declaration
+Function GetMouseY:word; 
 \Description
-
-\var{RPressed} returns \var{True} if the right mouse button is pressed.
-This is simply a wrapper for the GetMouseState procedure.
-
+{ Return the current Y position of the mouse }
 \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}
+\begin{procedure}{HideMouse}
 \Declaration
-Procedure SetMouseHideWindow (xmin,ymin,xmax,ymax: Longint);
-
+Procedure HideMouse;
 \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!
-
+ { Hide the mouse cursor }
 \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}
+\begin{procedure}{InitMouse}
 \Declaration
-Procedure SetMouseShape (ForeColor,BackColor,Ascii: Byte);
-
+Procedure InitMouse;
 \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.
-
+ { Initialize the mouse interface }
 \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);
 
+\begin{function}{PollMouseEvent}
+\Declaration
+Function PollMouseEvent(var MouseEvent: TMouseEvent):boolean; 
 \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.
-
+{ Checks if a Mouseevent is available, and returns it if one is found. If no   event is pending, it returns 0 }
 \Errors
-None.
 \SeeAlso
+\end{function}
 
-\end{procedure}
-\latex{\lstinputlisting{mouseex/mouse10.pp}}
-\html{\input{mouseex/mouse10.tex}}
-\begin{procedure}{SetMouseWindow}
+\begin{procedure}{PutMouseEvent}
 \Declaration
-Procedure SetMouseWindow (xmin,ymin,xmax,ymax: Longint);
-
+Procedure PutMouseEvent(const MouseEvent: TMouseEvent);
 \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.
-
+ { Adds the given MouseEvent to the input queue. Please note that depending on  the implementation this can hold only one value (NO FIFOs etc) }
 \Errors
-None.
 \SeeAlso
-\seep{SetMouseXRange}, \seep{SetMouseYRange}
 \end{procedure}
-For an example, see \seep{SetMouseXRange}.
-\begin{procedure}{SetMouseXRange}
-\Declaration
-Procedure SetMouseXRange (Min, Max: Longint);
 
+\begin{procedure}{SetMouseDriver}
+\Declaration
+Procedure SetMouseDriver(Const Driver : TMouseDriver);
 \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.
-
+ { Sets the mouse driver. }
 \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);
 
+\begin{procedure}{SetMouseXY}
+\Declaration
+Procedure SetMouseXY(x,y:word); 
 \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.
-
+{ Place the mouse cursor on x,y }
 \Errors
-None.
 \SeeAlso
-\seep{SetMouseXRange}, \seep{SetMouseWindow}
 \end{procedure}
-For an example, see \seep{SetMouseXRange}.
+
 \begin{procedure}{ShowMouse}
 \Declaration
-Procedure ShowMouse ;
-
+Procedure ShowMouse; 
 \Description
-
-\var{ShowMouse} makes the mouse cursor visible.
-At the start of your progam, the mouse cursor is invisible.
-
+{ Show the mouse cursor }
 \Errors
-None.
 \SeeAlso
-\seep{HideMouse},\seep{SetMouseHideWindow}
 \end{procedure}
-\latex{\lstinputlisting{mouseex/mouse2.pp}}
-\html{\input{mouseex/mouse2.tex}}
-