fpc/docs/mouse.tex

%
%   $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{mouseex}
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.
It is intended to be used only in text-based screens, for instance in 
conjunction with the keyboard and video unit. No support for graphical
screens is implemented, and there are (currently) no plans to implement
this.

\section{Constants, Types and Variables}
\subsection{Constants}	
The following constants can be used when mouse drivers need to report 
errors:
\begin{verbatim}
const
  { We have an errorcode base of 1030 }
  errMouseBase                    = 1030;
  errMouseInitError               = errMouseBase + 0;
  errMouseNotImplemented          = errMouseBase + 1;
\end{verbatim}
The following constants describe which action a mouse event describes
\begin{verbatim}
const
  MouseActionDown = $0001;  { Mouse down event }
  MouseActionUp   = $0002;  { Mouse up event }
  MouseActionMove = $0004;  { Mouse move event }
\end{verbatim}
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.

\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}

\section{Functions and procedures}

\begin{function}{DetectMouse}
\Declaration
Function DetectMouse:byte;
\Description
\var{DetectMouse} detects whether a mouse is attached to the system or not.
If there is no mouse, then zero is returned. If a mouse is attached, then
the number of mouse buttons is returned.

This function should be called after the mouse driver was initialized.
\Errors
None.
\SeeAlso
\seep{InitMouse},\seep{DoneMouse},
\end{function}

\FPCexample{ex1}

\begin{procedure}{DoneMouse}
\Declaration
Procedure DoneMouse;
\Description
\var{DoneMouse} De-initializes the mouse driver. It cleans up any memory
allocated when the mouse was initialized, or removes possible mouse hooks
from memory. The mouse functions will not work after \var{DoneMouse} was
called. If \var{DoneMouse} is called a second time, it will exit at once.
\var{InitMouse} should be called before \var{DoneMouse} can be called again.
\Errors
None.
\SeeAlso
\seef{DetectMouse}, \seep{InitMouse}
\end{procedure}

For an example, see most other mouse functions.

\begin{function}{GetMouseButtons}
\Declaration
Function GetMouseButtons:word;
\Description
\var{GetMouseButtons} returns the current button state of the mouse, i.e.
it returns a or-ed combination of the following constants:
\begin{description}
\item[MouseLeftButton] When the left mouse button is held down.
\item[MouseRightButton] When the right mouse button is held down.
\item[MouseMiddleButton] When the middle mouse button is held down.
\end{description}
\Errors
None.
\SeeAlso
\seep{GetMouseEvent}, \seef{GetMouseX}, \seef{GetMouseY}
\end{function}

\FPCexample{ex2}

\begin{procedure}{GetMouseDriver}
\Declaration
Procedure GetMouseDriver(Var Driver : TMouseDriver);
\Description
\var{GetMouseDriver} returns the currently set mouse driver. It can be used
to retrieve the current mouse driver, and override certain callbacks.

A more detailed explanation about getting and setting mouse drivers can be found in
\sees{mousedrv}.

\Errors
None.
\SeeAlso
\seep{SetMouseDriver}
\end{procedure}

For an example, see the section on writing a custom mouse driver,
\sees{mousedrv}

\begin{procedure}{GetMouseEvent}
\Declaration
Procedure GetMouseEvent(var MouseEvent:TMouseEvent);
\Description
\var{GetMouseEvent} returns the next mouse event (a movement, button press or
button release), and waits for one if none is available in the queue.

Some mouse drivers can implement a mouse event queue which can hold multiple
events till they are fetched.; Others don't, and in that case, a one-event
queue is implemented for use with \seef{PollMouseEvent}.
\Errors
None.
\SeeAlso
\seef{GetMouseButtons}, \seef{GetMouseX}, \seef{GetMouseY}
\end{procedure}

\begin{function}{GetMouseX}
\Declaration
Function GetMouseX:word;
\Description
\var{GetMouseX} returns the current \var{X} position of the mouse. \var{X} is
measured in characters, starting at 0 for the left side of the screen.
\Errors
None.
\SeeAlso
\seef{GetMouseButtons},\seep{GetMouseEvent}, \seef{GetMouseY}
\end{function}

\FPCexample{ex4}

\begin{function}{GetMouseY}
\Declaration
Function GetMouseY:word; 
\Description
\var{GetMouseY} returns the current \var{Y} position of the mouse. \var{Y} is
measured in characters, starting at 0 for the top of the screen.
\Errors
None.
\SeeAlso
\seef{GetMouseButtons},\seep{GetMouseEvent}, \seef{GetMouseX}
\end{function}

For an example, see \seef{GetMouseX}

\begin{procedure}{HideMouse}
\Declaration
Procedure HideMouse;
\Description
\var{HideMouse} hides the mouse cursor. This may or may not be implemented
on all systems, and depends on the driver.
\Errors
None.
\SeeAlso
\seep{ShowMouse}
\end{procedure}

\FPCexample{ex5}

\begin{procedure}{InitMouse}
\Declaration
Procedure InitMouse;
\Description
\var{InitMouse} Initializes the mouse driver. This will allocate any data
structures needed for the mouse to function. All mouse functions can be
used after a call to \var{InitMouse}.

A call to \var{InitMouse} must always be followed by a call to \seep{DoneMouse}
at program exit. Failing to do so may leave the mouse in an unusable state,
or may result in memory leaks.
\Errors
None.
\SeeAlso
\seep{DoneMouse}, \seef{DetectMouse}
\end{procedure}

For an example, see most other functions.

\begin{function}{PollMouseEvent}
\Declaration
Function PollMouseEvent(var MouseEvent: TMouseEvent):boolean; 
\Description
\var{PollMouseEvent} checks whether a mouse event is available, and 
returns it in \var{MouseEvent} if one is found. The function result is
\var{True} in that case. If no mouse event is pending, the function result
is \var{False}, and the contents of \var{MouseEvent} is undefined.

Note that after a call to \var{PollMouseEvent}, the event should still 
be removed from the mouse event queue with a call to \var{GetMouseEvent}.
\Errors
None.
\SeeAlso
\seep{GetMouseEvent}, \seep{PutMouseEvent}
\end{function}

\begin{procedure}{PutMouseEvent}
\Declaration
Procedure PutMouseEvent(const MouseEvent: TMouseEvent);
\Description
\var{PutMouseEvent} adds \var{MouseEvent} to the input queue. The next
call to \seep{GetMouseEvent} or \var{PollMouseEvent} will then return
\var{MouseEvent}. 

Please note that depending on the implementation the mouse event queue
can hold only one value.
\Errors
None.
\SeeAlso
\seep{GetMouseEvent}, \seef{PollMouseEvent}
\end{procedure}

\begin{procedure}{SetMouseDriver}
\Declaration
Procedure SetMouseDriver(Const Driver : TMouseDriver);
\Description
\var{SetMouseDriver} sets the mouse driver to \var{Driver}. This function
should be called before \seep{InitMouse} is called, or after \var{DoneMouse}
is called. If it is called after the mouse has been initialized, it does
nothing.

For more information on setting the mouse driver, \sees{mousedrv}.
\Errors

\SeeAlso
\seep{InitMouse}, \seep{DoneMouse}, \seep{GetMouseDriver}
\end{procedure}

For an example, see \sees{mousedrv}

\begin{procedure}{SetMouseXY}
\Declaration
Procedure SetMouseXY(x,y:word); 
\Description
\var{SetMouseXY} places the mouse cursor on \var{X,Y}. X and Y are zero
based character coordinates: \var{0,0} is the top-left corner of the screen,
and the position is in character cells (i.e. not in pixels).
\Errors
None.
\SeeAlso
\seef{GetMouseX}, \seef{GetMouseY}
\end{procedure}

\FPCexample{ex7}

\begin{procedure}{ShowMouse}
\Declaration
Procedure ShowMouse; 
\Description
\var{ShowMouse} shows the mouse cursor if it was previously hidden. The
capability to hide or show the mouse cursor depends on the driver.
\Errors
None.
\SeeAlso
\seep{HideMouse}
\end{procedure}

For an example, see \seep{HideMouse}

\section{Writing a custom mouse driver}
\label{se:mousedrv}
The \file{mouse} has support for adding a custom mouse driver. This can be
used to add support for mouses not supported by the standard \fpc{} driver,
but also to enhance an existing driver for instance to log mouse events or
to implement a record and playback function. 

The following unit shows how a mouse driver can be enhanced by adding some
logging capabilities to the driver.
\FPCexample{logmouse}