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{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}
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
 { Detect if a mouse is present, returns the amount of buttons or 0  if no mouse is found }
\Errors
\SeeAlso
\end{function}

\begin{procedure}{DoneMouse}
\Declaration
Procedure DoneMouse;
\Description
 { Deinitialize the mouse interface }
\Errors
\SeeAlso
\end{procedure}

\begin{function}{GetMouseButtons}
\Declaration
Function GetMouseButtons:word;
\Description
 { Return the current button state of the mouse }
\Errors
\SeeAlso
\end{function}

\begin{procedure}{GetMouseDriver}
\Declaration
Procedure GetMouseDriver(Var Driver : TMouseDriver);
\Description
\Errors
\SeeAlso
\end{procedure}

\begin{procedure}{GetMouseEvent}
\Declaration
Procedure GetMouseEvent(var MouseEvent:TMouseEvent);
\Description
 { Returns the last Mouseevent, and waits for one if not available }
\Errors
\SeeAlso
\end{procedure}

\begin{function}{GetMouseX}
\Declaration
Function GetMouseX:word;
\Description
 { Return the current X position of the mouse }
\Errors
\SeeAlso
\end{function}

\begin{function}{GetMouseY}
\Declaration
Function GetMouseY:word; 
\Description
{ Return the current Y position of the mouse }
\Errors
\SeeAlso
\end{function}

\begin{procedure}{HideMouse}
\Declaration
Procedure HideMouse;
\Description
 { Hide the mouse cursor }
\Errors
\SeeAlso
\end{procedure}

\begin{procedure}{InitMouse}
\Declaration
Procedure InitMouse;
\Description
 { Initialize the mouse interface }
\Errors
\SeeAlso
\end{procedure}

\begin{function}{PollMouseEvent}
\Declaration
Function PollMouseEvent(var MouseEvent: TMouseEvent):boolean; 
\Description
{ Checks if a Mouseevent is available, and returns it if one is found. If no   event is pending, it returns 0 }
\Errors
\SeeAlso
\end{function}

\begin{procedure}{PutMouseEvent}
\Declaration
Procedure PutMouseEvent(const MouseEvent: TMouseEvent);
\Description
 { 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
\SeeAlso
\end{procedure}

\begin{procedure}{SetMouseDriver}
\Declaration
Procedure SetMouseDriver(Const Driver : TMouseDriver);
\Description
 { Sets the mouse driver. }
\Errors
\SeeAlso
\end{procedure}

\begin{procedure}{SetMouseXY}
\Declaration
Procedure SetMouseXY(x,y:word); 
\Description
{ Place the mouse cursor on x,y }
\Errors
\SeeAlso
\end{procedure}

\begin{procedure}{ShowMouse}
\Declaration
Procedure ShowMouse; 
\Description
{ Show the mouse cursor }
\Errors
\SeeAlso
\end{procedure}