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