fpc/docs/gpm.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. 
%
\chapter{The GPM unit}
\FPCexampledir{gpmex}
\section{Introduction}
The \file{GPM} unit implements an interface to file{libgpm}, the console
program for mouse handling. This unit was created by Peter Vreman, and 
is only available on \linux.

When this unit is used, your program is linked to the C libraries, so
you must take care of the C library version. Also, it will only work with
version 1.17 or higher of the \file{libgpm} library.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Constants, types and variables
\section{Constants, types and variables}
\subsection{constants}
The following constants are used to denote filenames used by the library:
\begin{verbatim}
_PATH_VARRUN = '/var/run/';
_PATH_DEV    = '/dev/';
GPM_NODE_DIR = _PATH_VARRUN;
GPM_NODE_DIR_MODE = 0775;
GPM_NODE_PID  = '/var/run/gpm.pid';
GPM_NODE_DEV  = '/dev/gpmctl';
GPM_NODE_CTL  = GPM_NODE_DEV;
GPM_NODE_FIFO = '/dev/gpmdata';
\end{verbatim}
The following constants denote the buttons on the mouse:
\begin{verbatim}
GPM_B_LEFT   = 4;
GPM_B_MIDDLE = 2;
GPM_B_RIGHT  = 1;
\end{verbatim}
The following constants define events:
\begin{verbatim}
GPM_MOVE = 1;      
GPM_DRAG = 2;
GPM_DOWN = 4;
GPM_UP = 8;
GPM_SINGLE = 16;
GPM_DOUBLE = 32;
GPM_TRIPLE = 64;
GPM_MFLAG = 128;
GPM_HARD = 256;
GPM_ENTER = 512;
GPM_LEAVE = 1024;
\end{verbatim}
The following constants are used in defining margins:
\begin{verbatim}
GPM_TOP = 1;
GPM_BOT = 2;
GPM_LFT = 4;
GPM_RGT = 8;
\end{verbatim}

% Types
\subsection{Types}
The following general types are defined:
\begin{verbatim}
  TGpmEtype = longint;
  TGpmMargin = longint;
\end{verbatim}
The following type describes an event; it is passed in many of the gpm
functions.
\begin{verbatim}
PGpmEvent = ^TGpmEvent;
TGpmEvent = record
  buttons : byte;
  modifiers : byte;
  vc : word;
  dx : word;
  dy : word;
  x : word;
  y : word;
  EventType : TGpmEType;
  clicks : longint;
  margin : TGpmMargin;
end;
TGpmHandler=function(var event:TGpmEvent;clientdata:pointer):longint;cdecl;
\end{verbatim}
The following types are used in connecting to the \file{gpm} server:
\begin{verbatim}
PGpmConnect = ^TGpmConnect;
TGpmConnect = record
  eventMask : word;
  defaultMask : word;
  minMod : word;
  maxMod : word;
  pid : longint;
  vc : longint;
end;
\end{verbatim}
The following type is used to define {\em regions of interest}
\begin{verbatim}
PGpmRoi = ^TGpmRoi;
TGpmRoi = record
  xMin : integer;
  xMax : integer;
  yMin : integer;
  yMax : integer;
  minMod : word;
  maxMod : word;
  eventMask : word;
  owned : word;
  handler : TGpmHandler;
  clientdata : pointer;
  prev : PGpmRoi;
  next : PGpmRoi;
end;
\end{verbatim}

% Variables
\subsection{Variables}
The following variables are imported from the \var{gpm} library
\begin{verbatim}
gpm_flag           : longint;cvar;external;
gpm_fd             : longint;cvar;external;
gpm_hflag          : longint;cvar;external;
gpm_morekeys       : Longbool;cvar;external;
gpm_zerobased      : Longbool;cvar;external;
gpm_visiblepointer : Longbool;cvar;external;
gpm_mx             : longint;cvar;external;
gpm_my             : longint;cvar;external;
gpm_timeout        : TTimeVal;cvar;external;
_gpm_buf           : array[0..0] of char;cvar;external;
_gpm_arg           : ^word;cvar;external;
gpm_handler        : TGpmHandler;cvar;external;
gpm_data           : pointer;cvar;external;
gpm_roi_handler    : TGpmHandler;cvar;external;
gpm_roi_data       : pointer;cvar;external;
gpm_roi            : PGpmRoi;cvar;external;
gpm_current_roi    : PGpmRoi;cvar;external;
gpm_consolefd      : longint;cvar;external;
Gpm_HandleRoi      : TGpmHandler;cvar;external;
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Functions and procedures
\section{Functions and procedures}

\begin{functionl}{Gpm\_AnyDouble}{GpmAnyDouble}
\Declaration
function Gpm\_AnyDouble(EventType : longint) : boolean;
\Description
\var{Gpm\_AnyDouble} returns \var{True} if \var{EventType} contains
the \var{GPM\_DOUBLE} flag, \var{False} otherwise.
\Errors
None.
\SeeAlso
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
\seefl{Gpm\_AnySingle}{GpmAnySingle},
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
\seefl{Gpm\_AnyTriple}{GpmAnyTriple}
\end{functionl}

\begin{functionl}{Gpm\_AnySingle}{GpmAnySingle}
\Declaration
function Gpm\_AnySingle(EventType : longint) : boolean;
\Description
\var{Gpm\_AnySingle} returns \var{True} if \var{EventType} contains
the \var{GPM\_SINGLE} flag, \var{False} otherwise. 
\Errors
\SeeAlso
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
\seefl{Gpm\_AnyDoubmle}{GpmAnyDouble},
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
\seefl{Gpm\_AnyTriple}{GpmAnyTriple}
\end{functionl}

\begin{functionl}{Gpm\_AnyTriple}{GpmAnyTriple}
\Declaration
function Gpm\_AnyTriple(EventType : longint) : boolean;
\Description
\Errors
\SeeAlso
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
\seefl{Gpm\_AnyDoubmle}{GpmAnyDouble},
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
\seefl{Gpm\_AnySingle}{GpmAnySingle}
\end{functionl}

\begin{functionl}{Gpm\_Close}{GpmClose}
\Declaration
function Gpm\_Close:longint;cdecl;external;
\Description
\var{Gpm\_Close} closes the current connection, and pops the connection
stack; this means that the previous connection becomes active again.

The function returns -1 if the current connection is not the last one,
and it returns 0 if the current connection is the last one.
\Errors
None.
\SeeAlso
\seefl{Gpm\_Open}{GpmOpen}
\end{functionl}

for an example, see \seefl{Gpm\_GetEvent}{GpmGetEvent}.

\begin{functionl}{Gpm\_FitValues}{GpmFitValues}
\Declaration
function Gpm\_FitValues(var x,y:longint):longint;cdecl;external;
\Description
\var{Gpm\_fitValues} changes \var{x} and \var{y} so they fit in the visible
screen. The actual mouse pointer is not affected by this function.
\Errors
None.
\SeeAlso
\seefl{Gpm\_FitValuesM}{GpmFitValuesM},
\end{functionl}

\begin{functionl}{Gpm\_FitValuesM}{GpmFitValuesM}
\Declaration
function Gpm\_FitValuesM(var x,y:longint; margin:longint):longint;cdecl;external;
\Description
\var{Gpm\_FitValuesM} chnages \var{x} and \var{y} so they fit in the margin
indicated by \var{margin}. If \var{margin} is -1, then the values are fitted
to the screen. The actual mouse pointer is not affected by this function.
\Errors
None.
\SeeAlso
\seefl{Gpm\_FitValues}{GpmFitValues},
\end{functionl}

\begin{functionl}{Gpm\_GetEvent}{GpmGetEvent}
\Declaration
function Gpm\_GetEvent(var Event:TGpmEvent):longint;cdecl;external;
\Description
\var{Gpm\_GetEvent} Reads an event from the file descriptor \var{gpm\_fd}.
This file is only for internal use and should never be called by a client
application. 

It returns 1 on succes, and -1 on failue.
\Errors
On error, -1 is returned. 
\SeeAlso
seefl{Gpm\_GetSnapshot}{GpmGetSnapshot}
\end{functionl}

\FPCexample{gpmex}

\begin{functionl}{Gpm\_GetLibVersion}{GpmGetLibVersion}
\Declaration
function Gpm\_GetLibVersion(var where:longint):pchar;cdecl;external;
\Description
\var{Gpm\_GetLibVersion} returns a pointer to a version string, and returns
in \var{where} an integer representing the version. The version string
represents the version of the gpm library.

The return value is a pchar, which should not be dealloacted, i.e. it is not
on the heap.
\Errors
None.
\SeeAlso
\seefl{Gpm\_GetServerVersion}{GpmGetServerVersion}
\end{functionl}

\begin{functionl}{Gpm\_GetServerVersion}{GpmGetServerVersion}
\Declaration
function Gpm\_GetServerVersion(var where:longint):pchar;cdecl;external;
\Description
\var{Gpm\_GetServerVersion} returns a pointer to a version string, and 
returns in \var{where} an integer representing the version. The version string
represents the version of the gpm server program.

The return value is a pchar, which should not be dealloacted, i.e. it is not
on the heap.
\Errors
If the gpm program is not present, then the function returns \var{Nil}
\SeeAlso
\seefl{Gpm\_GetLibVersion}{GpmGetLibVersion}
\end{functionl}

\begin{functionl}{Gpm\_GetSnapshot}{GpmGetSnapshot}
\Declaration
function Gpm\_GetSnapshot(var Event:TGpmEvent):longint;cdecl;external;
\Description
\var{Gpm\_GetSnapshot} returns the picture that the server has of the 
current situation in \var{Event}. 
This call will not read the current situation from the mouse file
descriptor, but returns a buffered version.
The meaning of the fields is as follows:
\begin{description}
\item[x,y] current position of the cursor.
\item[dx,dy] size of the window.
\item[vc] number of te virtual console.
\item[modifiers] keyboard shift state.
\item[buttons] buttons which are currently pressed.
\item[clicks] number of clicks (0,1 or 2).
\end{description}
The function returns the number of mouse buttons, or -1 if this information
is not available.
\Errors
None.
\SeeAlso
\seefl{Gpm\_GetEvent}{GpmGetEvent}
\end{functionl}

\begin{functionl}{Gpm\_LowerRoi}{GpmLowerRoi}
\Declaration
function Gpm\_LowerRoi(which:PGpmRoi; after:PGpmRoi):PGpmRoi;cdecl;external;
\Description
\var{Gpm\_LowerRoi} lowers the region of interest \var{which} after
\var{after}. If \var{after} is \var{Nil}, the region of interest is moved to
the bottom of the stack.

The return value is the new top of the region-of-interest stack.
\Errors
None.
\SeeAlso
\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
\seefl{Gpm\_PopRoi}{GpmPopRoi},
\seefl{Gpm\_PushRoi}{GpmPopRoi} 
\end{functionl}

\begin{functionl}{Gpm\_Open}{GpmOpen}
\Declaration
function Gpm\_Open(var Conn:TGpmConnect; Flag:longint):longint;cdecl;external;
\Description
\var{Gpm\_Open} opens a new connection to the mouse server. The connection
is described by the fields of the \var{conn} record:
\begin{description}
\item[EventMask] A bitmask of the events the program wants to receive.
\item[DefaultMask] A bitmask to tell the library which events get their
default treatment (text selection).
\item[minMod] the minimum amount of modifiers needed by the program.
\item[maxMod] the maximum amount of modifiers needed by the program.
\end{description}
if \var{Flag} is 0, then the application only receives events that come from
its own terminal device. If it is negative it will receive all events. If
the value is positive then it is considered a console number to which to
connect.

The return value is -1 on error, or the file descriptor used to communicate
with the client. Under an X-Term the return value is -2.
\Errors
On Error, the return value is -1.
\SeeAlso
\seefl{Gpm\_Open}{GpmOpen}
\end{functionl}

for an example, see \seefl{Gpm\_GetEvent}{GpmGetEvent}.

\begin{functionl}{Gpm\_PopRoi}{GpmPopRoi}
\Declaration
function Gpm\_PopRoi(which:PGpmRoi):PGpmRoi;cdecl;external;
\Description
\var{Gpm\_PopRoi} pops the topmost region of interest from the stack.
It returns the next element on the stack, or \var{Nil} if the current 
element was the last one.
\Errors
None.
\SeeAlso
\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
\seefl{Gpm\_LowerRoi}{GpmLowerRoi}, 
\seefl{Gpm\_PushRoi}{GpmPopRoi} 
\end{functionl}

\begin{functionl}{Gpm\_PushRoi}{GpmPushRoi}
\Declaration
function Gpm\_PushRoi(x1:longint; y1:longint; X2:longint; Y2:longint; mask:longint; fun:TGpmHandler; xtradata:pointer):PGpmRoi;cdecl;external;
\Description
\var{Gpm\_PushRoi} puts a new {\em region of interest} on the stack.
The region of interest is defined by a rectangle described by the corners
\var{(X1,Y1)} and \var{(X2,Y2)}. 

The \var{mask} describes which events the handler {fun} will handle;
\var{ExtraData} will be put in the \var{xtradata} field of the {TGPM\_Roi} 
record passed to the \var{fun} handler.
\Errors
None.
\SeeAlso
\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
\seefl{Gpm\_PopRoi}{GpmPopRoi}, 
\seefl{Gpm\_LowerRoi}{GpmLowerRoi} 
\end{functionl}

\begin{functionl}{Gpm\_RaiseRoi}{GpmRaiseRoi}
\Declaration
function Gpm\_RaiseRoi(which:PGpmRoi; before:PGpmRoi):PGpmRoi;cdecl;external;
\Description
\var{Gpm\_RaiseRoi} raises the {\em region of interest} \var{which} till it
is on top of region \var{before}. If \var{before} is nil then the region is
put on top of the stack. The returned value is the top of the stack.
\Errors
None.
\SeeAlso
\seefl{Gpm\_PushRoi}{GpmPushRoi},
\seefl{Gpm\_PopRoi}{GpmPopRoi}, 
\seefl{Gpm\_LowerRoi}{GpmLowerRoi} 
\end{functionl}

\begin{functionl}{Gpm\_Repeat}{GpmRepeat}
\Declaration
function Gpm\_Repeat(millisec:longint):longint;cdecl;external;
\Description
\var{Gpm\_Repeat} returns 1 of no mouse event arrives in the next
\var{millisec} miiliseconds, it returns 0 otherwise.
\Errors
None.
\SeeAlso
\seefl{Gpm\_GetEvent}{GpmGetEvent}
\end{functionl}

\begin{functionl}{Gpm\_StrictDouble}{GpmStrictDouble}
\Declaration
function Gpm\_StrictDouble(EventType : longint) : boolean;
\Description
\var{Gpm\_StrictDouble} returns true if \var{EventType} contains only a 
doubleclick event, \var{False} otherwise.
\Errors
None.
\SeeAlso
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
\seefl{Gpm\_AnyDouble}{GpmAnyDouble},
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
\seefl{Gpm\_AnySingle}{GpmAnySingle}
\end{functionl}

\begin{functionl}{Gpm\_StrictSingle}{GpmStrictSingle}
\Declaration
function Gpm\_StrictSingle(EventType : longint) : boolean;
\Description
\var{Gpm\_StrictDouble} returns \var{True} if \var{EventType} contains only a 
singleclick event, \var{False} otherwise. 
\Errors
None.
\SeeAlso
\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
\seefl{Gpm\_AnyDouble}{GpmAnyDouble}, 
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
\seefl{Gpm\_AnySingle}{GpmAnySingle}
\end{functionl}

\begin{functionl}{Gpm\_StrictTriple}{GpmStrictTriple}
\Declaration
function Gpm\_StrictTriple(EventType : longint) : boolean;
\Description
\var{Gpm\_StrictTriple} returns true if \var{EventType} contains only a
triple click event, \var{False} otherwise.
\Errors
None.
\SeeAlso
\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
\seefl{Gpm\_AnyDouble}{GpmAnyDouble}, 
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
\seefl{Gpm\_AnySingle}{GpmAnySingle}
\end{functionl}