2
% $Id: gpm.tex,v 1.2 2003/03/16 15:22:18 peter Exp $
3
% This file is part of the FPC documentation.
4
% Copyright (C) 1997, by Michael Van Canneyt
6
% The FPC documentation is free text; you can redistribute it and/or
7
% modify it under the terms of the GNU Library General Public License as
8
% published by the Free Software Foundation; either version 2 of the
9
% License, or (at your option) any later version.
11
% The FPC Documentation is distributed in the hope that it will be useful,
12
% but WITHOUT ANY WARRANTY; without even the implied warranty of
13
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
% Library General Public License for more details.
16
% You should have received a copy of the GNU Library General Public
17
% License along with the FPC documentation; see the file COPYING.LIB. If not,
18
% write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19
% Boston, MA 02111-1307, USA.
21
\chapter{The GPM unit}
23
\section{Introduction}
24
The \file{GPM} unit implements an interface to file{libgpm}, the console
25
program for mouse handling. This unit was created by Peter Vreman, and
26
is only available on \linux.
28
When this unit is used, your program is linked to the C libraries, so
29
you must take care of the C library version. Also, it will only work with
30
version 1.17 or higher of the \file{libgpm} library.
32
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
33
% Constants, types and variables
34
\section{Constants, types and variables}
35
\subsection{constants}
36
The following constants are used to denote filenames used by the library:
38
_PATH_VARRUN = '/var/run/';
40
GPM_NODE_DIR = _PATH_VARRUN;
41
GPM_NODE_DIR_MODE = 0775;
42
GPM_NODE_PID = '/var/run/gpm.pid';
43
GPM_NODE_DEV = '/dev/gpmctl';
44
GPM_NODE_CTL = GPM_NODE_DEV;
45
GPM_NODE_FIFO = '/dev/gpmdata';
47
The following constants denote the buttons on the mouse:
53
The following constants define events:
67
The following constants are used in defining margins:
77
The following general types are defined:
82
The following type describes an event; it is passed in many of the gpm
85
PGpmEvent = ^TGpmEvent;
94
EventType : TGpmEType;
98
TGpmHandler=function(var event:TGpmEvent;clientdata:pointer):longint;cdecl;
100
The following types are used in connecting to the \file{gpm} server:
102
PGpmConnect = ^TGpmConnect;
112
The following type is used to define {\em regions of interest}
124
handler : TGpmHandler;
125
clientdata : pointer;
132
\subsection{Variables}
133
The following variables are imported from the \var{gpm} library
135
gpm_flag : longint;cvar;external;
136
gpm_fd : longint;cvar;external;
137
gpm_hflag : longint;cvar;external;
138
gpm_morekeys : Longbool;cvar;external;
139
gpm_zerobased : Longbool;cvar;external;
140
gpm_visiblepointer : Longbool;cvar;external;
141
gpm_mx : longint;cvar;external;
142
gpm_my : longint;cvar;external;
143
gpm_timeout : TTimeVal;cvar;external;
144
_gpm_buf : array[0..0] of char;cvar;external;
145
_gpm_arg : ^word;cvar;external;
146
gpm_handler : TGpmHandler;cvar;external;
147
gpm_data : pointer;cvar;external;
148
gpm_roi_handler : TGpmHandler;cvar;external;
149
gpm_roi_data : pointer;cvar;external;
150
gpm_roi : PGpmRoi;cvar;external;
151
gpm_current_roi : PGpmRoi;cvar;external;
152
gpm_consolefd : longint;cvar;external;
153
Gpm_HandleRoi : TGpmHandler;cvar;external;
156
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
157
% Functions and procedures
158
\section{Functions and procedures}
160
\begin{functionl}{Gpm\_AnyDouble}{GpmAnyDouble}
162
function Gpm\_AnyDouble(EventType : longint) : boolean;
164
\var{Gpm\_AnyDouble} returns \var{True} if \var{EventType} contains
165
the \var{GPM\_DOUBLE} flag, \var{False} otherwise.
169
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
170
\seefl{Gpm\_AnySingle}{GpmAnySingle},
171
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
172
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
173
\seefl{Gpm\_AnyTriple}{GpmAnyTriple}
176
\begin{functionl}{Gpm\_AnySingle}{GpmAnySingle}
178
function Gpm\_AnySingle(EventType : longint) : boolean;
180
\var{Gpm\_AnySingle} returns \var{True} if \var{EventType} contains
181
the \var{GPM\_SINGLE} flag, \var{False} otherwise.
184
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
185
\seefl{Gpm\_AnyDoubmle}{GpmAnyDouble},
186
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
187
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
188
\seefl{Gpm\_AnyTriple}{GpmAnyTriple}
191
\begin{functionl}{Gpm\_AnyTriple}{GpmAnyTriple}
193
function Gpm\_AnyTriple(EventType : longint) : boolean;
197
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
198
\seefl{Gpm\_AnyDoubmle}{GpmAnyDouble},
199
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
200
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
201
\seefl{Gpm\_AnySingle}{GpmAnySingle}
204
\begin{functionl}{Gpm\_Close}{GpmClose}
206
function Gpm\_Close:longint;cdecl;external;
208
\var{Gpm\_Close} closes the current connection, and pops the connection
209
stack; this means that the previous connection becomes active again.
211
The function returns -1 if the current connection is not the last one,
212
and it returns 0 if the current connection is the last one.
216
\seefl{Gpm\_Open}{GpmOpen}
219
for an example, see \seefl{Gpm\_GetEvent}{GpmGetEvent}.
221
\begin{functionl}{Gpm\_FitValues}{GpmFitValues}
223
function Gpm\_FitValues(var x,y:longint):longint;cdecl;external;
225
\var{Gpm\_fitValues} changes \var{x} and \var{y} so they fit in the visible
226
screen. The actual mouse pointer is not affected by this function.
230
\seefl{Gpm\_FitValuesM}{GpmFitValuesM},
233
\begin{functionl}{Gpm\_FitValuesM}{GpmFitValuesM}
235
function Gpm\_FitValuesM(var x,y:longint; margin:longint):longint;cdecl;external;
237
\var{Gpm\_FitValuesM} chnages \var{x} and \var{y} so they fit in the margin
238
indicated by \var{margin}. If \var{margin} is -1, then the values are fitted
239
to the screen. The actual mouse pointer is not affected by this function.
243
\seefl{Gpm\_FitValues}{GpmFitValues},
246
\begin{functionl}{Gpm\_GetEvent}{GpmGetEvent}
248
function Gpm\_GetEvent(var Event:TGpmEvent):longint;cdecl;external;
250
\var{Gpm\_GetEvent} Reads an event from the file descriptor \var{gpm\_fd}.
251
This file is only for internal use and should never be called by a client
254
It returns 1 on succes, and -1 on failue.
256
On error, -1 is returned.
258
seefl{Gpm\_GetSnapshot}{GpmGetSnapshot}
263
\begin{functionl}{Gpm\_GetLibVersion}{GpmGetLibVersion}
265
function Gpm\_GetLibVersion(var where:longint):pchar;cdecl;external;
267
\var{Gpm\_GetLibVersion} returns a pointer to a version string, and returns
268
in \var{where} an integer representing the version. The version string
269
represents the version of the gpm library.
271
The return value is a pchar, which should not be dealloacted, i.e. it is not
276
\seefl{Gpm\_GetServerVersion}{GpmGetServerVersion}
279
\begin{functionl}{Gpm\_GetServerVersion}{GpmGetServerVersion}
281
function Gpm\_GetServerVersion(var where:longint):pchar;cdecl;external;
283
\var{Gpm\_GetServerVersion} returns a pointer to a version string, and
284
returns in \var{where} an integer representing the version. The version string
285
represents the version of the gpm server program.
287
The return value is a pchar, which should not be dealloacted, i.e. it is not
290
If the gpm program is not present, then the function returns \var{Nil}
292
\seefl{Gpm\_GetLibVersion}{GpmGetLibVersion}
295
\begin{functionl}{Gpm\_GetSnapshot}{GpmGetSnapshot}
297
function Gpm\_GetSnapshot(var Event:TGpmEvent):longint;cdecl;external;
299
\var{Gpm\_GetSnapshot} returns the picture that the server has of the
300
current situation in \var{Event}.
301
This call will not read the current situation from the mouse file
302
descriptor, but returns a buffered version.
303
The meaning of the fields is as follows:
305
\item[x,y] current position of the cursor.
306
\item[dx,dy] size of the window.
307
\item[vc] number of te virtual console.
308
\item[modifiers] keyboard shift state.
309
\item[buttons] buttons which are currently pressed.
310
\item[clicks] number of clicks (0,1 or 2).
312
The function returns the number of mouse buttons, or -1 if this information
317
\seefl{Gpm\_GetEvent}{GpmGetEvent}
320
\begin{functionl}{Gpm\_LowerRoi}{GpmLowerRoi}
322
function Gpm\_LowerRoi(which:PGpmRoi; after:PGpmRoi):PGpmRoi;cdecl;external;
324
\var{Gpm\_LowerRoi} lowers the region of interest \var{which} after
325
\var{after}. If \var{after} is \var{Nil}, the region of interest is moved to
326
the bottom of the stack.
328
The return value is the new top of the region-of-interest stack.
332
\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
333
\seefl{Gpm\_PopRoi}{GpmPopRoi},
334
\seefl{Gpm\_PushRoi}{GpmPopRoi}
337
\begin{functionl}{Gpm\_Open}{GpmOpen}
339
function Gpm\_Open(var Conn:TGpmConnect; Flag:longint):longint;cdecl;external;
341
\var{Gpm\_Open} opens a new connection to the mouse server. The connection
342
is described by the fields of the \var{conn} record:
344
\item[EventMask] A bitmask of the events the program wants to receive.
345
\item[DefaultMask] A bitmask to tell the library which events get their
346
default treatment (text selection).
347
\item[minMod] the minimum amount of modifiers needed by the program.
348
\item[maxMod] the maximum amount of modifiers needed by the program.
350
if \var{Flag} is 0, then the application only receives events that come from
351
its own terminal device. If it is negative it will receive all events. If
352
the value is positive then it is considered a console number to which to
355
The return value is -1 on error, or the file descriptor used to communicate
356
with the client. Under an X-Term the return value is -2.
358
On Error, the return value is -1.
360
\seefl{Gpm\_Open}{GpmOpen}
363
for an example, see \seefl{Gpm\_GetEvent}{GpmGetEvent}.
365
\begin{functionl}{Gpm\_PopRoi}{GpmPopRoi}
367
function Gpm\_PopRoi(which:PGpmRoi):PGpmRoi;cdecl;external;
369
\var{Gpm\_PopRoi} pops the topmost region of interest from the stack.
370
It returns the next element on the stack, or \var{Nil} if the current
371
element was the last one.
375
\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
376
\seefl{Gpm\_LowerRoi}{GpmLowerRoi},
377
\seefl{Gpm\_PushRoi}{GpmPopRoi}
380
\begin{functionl}{Gpm\_PushRoi}{GpmPushRoi}
382
function Gpm\_PushRoi(x1:longint; y1:longint; X2:longint; Y2:longint; mask:longint; fun:TGpmHandler; xtradata:pointer):PGpmRoi;cdecl;external;
384
\var{Gpm\_PushRoi} puts a new {\em region of interest} on the stack.
385
The region of interest is defined by a rectangle described by the corners
386
\var{(X1,Y1)} and \var{(X2,Y2)}.
388
The \var{mask} describes which events the handler {fun} will handle;
389
\var{ExtraData} will be put in the \var{xtradata} field of the {TGPM\_Roi}
390
record passed to the \var{fun} handler.
394
\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
395
\seefl{Gpm\_PopRoi}{GpmPopRoi},
396
\seefl{Gpm\_LowerRoi}{GpmLowerRoi}
399
\begin{functionl}{Gpm\_RaiseRoi}{GpmRaiseRoi}
401
function Gpm\_RaiseRoi(which:PGpmRoi; before:PGpmRoi):PGpmRoi;cdecl;external;
403
\var{Gpm\_RaiseRoi} raises the {\em region of interest} \var{which} till it
404
is on top of region \var{before}. If \var{before} is nil then the region is
405
put on top of the stack. The returned value is the top of the stack.
409
\seefl{Gpm\_PushRoi}{GpmPushRoi},
410
\seefl{Gpm\_PopRoi}{GpmPopRoi},
411
\seefl{Gpm\_LowerRoi}{GpmLowerRoi}
414
\begin{functionl}{Gpm\_Repeat}{GpmRepeat}
416
function Gpm\_Repeat(millisec:longint):longint;cdecl;external;
418
\var{Gpm\_Repeat} returns 1 of no mouse event arrives in the next
419
\var{millisec} miiliseconds, it returns 0 otherwise.
423
\seefl{Gpm\_GetEvent}{GpmGetEvent}
426
\begin{functionl}{Gpm\_StrictDouble}{GpmStrictDouble}
428
function Gpm\_StrictDouble(EventType : longint) : boolean;
430
\var{Gpm\_StrictDouble} returns true if \var{EventType} contains only a
431
doubleclick event, \var{False} otherwise.
435
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
436
\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
437
\seefl{Gpm\_AnyDouble}{GpmAnyDouble},
438
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
439
\seefl{Gpm\_AnySingle}{GpmAnySingle}
442
\begin{functionl}{Gpm\_StrictSingle}{GpmStrictSingle}
444
function Gpm\_StrictSingle(EventType : longint) : boolean;
446
\var{Gpm\_StrictDouble} returns \var{True} if \var{EventType} contains only a
447
singleclick event, \var{False} otherwise.
451
\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
452
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
453
\seefl{Gpm\_AnyDouble}{GpmAnyDouble},
454
\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
455
\seefl{Gpm\_AnySingle}{GpmAnySingle}
458
\begin{functionl}{Gpm\_StrictTriple}{GpmStrictTriple}
460
function Gpm\_StrictTriple(EventType : longint) : boolean;
462
\var{Gpm\_StrictTriple} returns true if \var{EventType} contains only a
463
triple click event, \var{False} otherwise.
467
\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
468
\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
469
\seefl{Gpm\_AnyDouble}{GpmAnyDouble},
470
\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
471
\seefl{Gpm\_AnySingle}{GpmAnySingle}
added
removed
docs/gpm.tex
