Subsections

6. The GPM unit

gpmex

6.1 Introduction

The GPM unit implements an interface to filelibgpm, 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 libgpm library.

6.2 Constants, types and variables

6.2.1 constants

The following constants are used to denote filenames used by the library:
_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';
The following constants denote the buttons on the mouse:
GPM_B_LEFT   = 4;
GPM_B_MIDDLE = 2;
GPM_B_RIGHT  = 1;
The following constants define events:
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;
The following constants are used in defining margins:
GPM_TOP = 1;
GPM_BOT = 2;
GPM_LFT = 4;
GPM_RGT = 8;

6.2.2 Types

The following general types are defined:
  TGpmEtype = longint;
  TGpmMargin = longint;
The following type describes an event; it is passed in many of the gpm functions.
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;
The following types are used in connecting to the gpm server:
PGpmConnect = ^TGpmConnect;
TGpmConnect = record
  eventMask : word;
  defaultMask : word;
  minMod : word;
  maxMod : word;
  pid : longint;
  vc : longint;
end;
The following type is used to define regions of interest
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;

6.2.3 Variables

The following variables are imported from the gpm library
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;

6.3 Functions and procedures


6.3.1 Gpm_AnyDouble

Declaration
function Gpm_AnyDouble(EventType : longint) : boolean;
Description
Gpm_AnyDouble returns True if EventType contains the GPM_DOUBLE flag, False otherwise.
Errors
None.
See also
Gpm_StrictSingle, Gpm_AnySingle, Gpm_StrictDouble, Gpm_StrictTriple, Gpm_AnyTriple


6.3.2 Gpm_AnySingle

Declaration
function Gpm_AnySingle(EventType : longint) : boolean;
Description
Gpm_AnySingle returns True if EventType contains the GPM_SINGLE flag, False otherwise.
Errors
See also
Gpm_StrictSingle, Gpm_AnyDoubmle, Gpm_StrictDouble, Gpm_StrictTriple, Gpm_AnyTriple


6.3.3 Gpm_AnyTriple

Declaration
function Gpm_AnyTriple(EventType : longint) : boolean;
Description
Errors
See also
Gpm_StrictSingle, Gpm_AnyDoubmle, Gpm_StrictDouble, Gpm_StrictTriple, Gpm_AnySingle


6.3.4 Gpm_Close

Declaration
function Gpm_Close:longint;cdecl;external;
Description
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.
See also
Gpm_Open

for an example, see Gpm_GetEvent.


6.3.5 Gpm_FitValues

Declaration
function Gpm_FitValues(var x,y:longint):longint;cdecl;external;
Description
Gpm_fitValues changes x and y so they fit in the visible screen. The actual mouse pointer is not affected by this function.
Errors
None.
See also
Gpm_FitValuesM,


6.3.6 Gpm_FitValuesM

Declaration
function Gpm_FitValuesM(var x,y:longint; margin:longint):longint;cdecl;external;
Description
Gpm_FitValuesM chnages x and y so they fit in the margin indicated by margin. If margin is -1, then the values are fitted to the screen. The actual mouse pointer is not affected by this function.
Errors
None.
See also
Gpm_FitValues,


6.3.7 Gpm_GetEvent

Declaration
function Gpm_GetEvent(var Event:TGpmEvent):longint;cdecl;external;
Description
Gpm_GetEvent Reads an event from the file descriptor 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.
See also
seeflGpm_GetSnapshotGpmGetSnapshot

Example
program gpmex;

{
  Example program to demonstrate the use of the gpm unit.
}

uses gpm;

var
  connect : TGPMConnect;
  event : tgpmevent;
 
begin
  connect.EventMask:=GPM_MOVE or GPM_DRAG or GPM_DOWN or GPM_UP;
  connect.DefaultMask:=0;
  connect.MinMod:=0;
  connect.MaxMod:=0;
  if Gpm_Open(connect,0)=-1 then
    begin
    Writeln('No mouse handler present.');
    Halt(1);
    end;
  Writeln('Click right button to end.');
  Repeat
    gpm_getevent(Event);
    With Event do
      begin
        Write('Pos = (',X,',',Y,') Buttons : (');
        if (buttons and Gpm_b_left)<>0 then
          write('left ');
        if (buttons and Gpm_b_right)<>0 then
          write('right ');
        if (buttons and Gpm_b_middle)<>0 then
          Write('middle ');
        Write(') Event : ');   
        Case EventType and $F of
          GPM_MOVE: write('Move');
          GPM_DRAG: write('Drag');
          GPM_DOWN: write('Down');
          GPM_UP: write('Up');
        end;  
        Writeln;
      end;  
  Until (Event.Buttons and gpm_b_right)<>0;
  gpm_close;
end.


6.3.8 Gpm_GetLibVersion

Declaration
function Gpm_GetLibVersion(var where:longint):pchar;cdecl;external;
Description
Gpm_GetLibVersion returns a pointer to a version string, and returns in 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.
See also
Gpm_GetServerVersion


6.3.9 Gpm_GetServerVersion

Declaration
function Gpm_GetServerVersion(var where:longint):pchar;cdecl;external;
Description
Gpm_GetServerVersion returns a pointer to a version string, and returns in 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 Nil
See also
Gpm_GetLibVersion


6.3.10 Gpm_GetSnapshot

Declaration
function Gpm_GetSnapshot(var Event:TGpmEvent):longint;cdecl;external;
Description
Gpm_GetSnapshot returns the picture that the server has of the current situation in 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:
x,y
current position of the cursor.
dx,dy
size of the window.
vc
number of te virtual console.
modifiers
keyboard shift state.
buttons
buttons which are currently pressed.
clicks
number of clicks (0,1 or 2).
The function returns the number of mouse buttons, or -1 if this information is not available.
Errors
None.
See also
Gpm_GetEvent


6.3.11 Gpm_LowerRoi

Declaration
function Gpm_LowerRoi(which:PGpmRoi; after:PGpmRoi):PGpmRoi;cdecl;external;
Description
Gpm_LowerRoi lowers the region of interest which after after. If after is 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.
See also
Gpm_RaiseRoi, Gpm_PopRoi, Gpm_PushRoi


6.3.12 Gpm_Open

Declaration
function Gpm_Open(var Conn:TGpmConnect; Flag:longint):longint;cdecl;external;
Description
Gpm_Open opens a new connection to the mouse server. The connection is described by the fields of the conn record:
EventMask
A bitmask of the events the program wants to receive.
DefaultMask
A bitmask to tell the library which events get their default treatment (text selection).
minMod
the minimum amount of modifiers needed by the program.
maxMod
the maximum amount of modifiers needed by the program.
if 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.
See also
Gpm_Open

for an example, see Gpm_GetEvent.


6.3.13 Gpm_PopRoi

Declaration
function Gpm_PopRoi(which:PGpmRoi):PGpmRoi;cdecl;external;
Description
Gpm_PopRoi pops the topmost region of interest from the stack. It returns the next element on the stack, or Nil if the current element was the last one.
Errors
None.
See also
Gpm_RaiseRoi, Gpm_LowerRoi, Gpm_PushRoi


6.3.14 Gpm_PushRoi

Declaration
function Gpm_PushRoi(x1:longint; y1:longint; X2:longint; Y2:longint; mask:longint; fun:TGpmHandler; xtradata:pointer):PGpmRoi;cdecl;external;
Description
Gpm_PushRoi puts a new region of interest on the stack. The region of interest is defined by a rectangle described by the corners (X1,Y1) and (X2,Y2).

The mask describes which events the handler fun will handle; ExtraData will be put in the xtradata field of the TGPM_Roi record passed to the fun handler.

Errors
None.
See also
Gpm_RaiseRoi, Gpm_PopRoi, Gpm_LowerRoi


6.3.15 Gpm_RaiseRoi

Declaration
function Gpm_RaiseRoi(which:PGpmRoi; before:PGpmRoi):PGpmRoi;cdecl;external;
Description
Gpm_RaiseRoi raises the region of interest which till it is on top of region before. If before is nil then the region is put on top of the stack. The returned value is the top of the stack.
Errors
None.
See also
Gpm_PushRoi, Gpm_PopRoi, Gpm_LowerRoi


6.3.16 Gpm_Repeat

Declaration
function Gpm_Repeat(millisec:longint):longint;cdecl;external;
Description
Gpm_Repeat returns 1 of no mouse event arrives in the next millisec miiliseconds, it returns 0 otherwise.
Errors
None.
See also
Gpm_GetEvent


6.3.17 Gpm_StrictDouble

Declaration
function Gpm_StrictDouble(EventType : longint) : boolean;
Description
Gpm_StrictDouble returns true if EventType contains only a doubleclick event, False otherwise.
Errors
None.
See also
Gpm_StrictSingle, Gpm_AnyTriple, Gpm_AnyDouble, Gpm_StrictTriple, Gpm_AnySingle


6.3.18 Gpm_StrictSingle

Declaration
function Gpm_StrictSingle(EventType : longint) : boolean;
Description
Gpm_StrictDouble returns True if EventType contains only a singleclick event, False otherwise.
Errors
None.
See also
Gpm_AnyTriple, Gpm_StrictDouble, Gpm_AnyDouble, Gpm_StrictTriple, Gpm_AnySingle


6.3.19 Gpm_StrictTriple

Declaration
function Gpm_StrictTriple(EventType : longint) : boolean;
Description
Gpm_StrictTriple returns true if EventType contains only a triple click event, False otherwise.
Errors
None.
See also
Gpm_AnyTriple, Gpm_StrictDouble, Gpm_AnyDouble, Gpm_StrictSingle, Gpm_AnySingle


root
2000-12-20