+ initial implementation

docs/gpm.tex

@@ -0,0 +1,414 @@
+\chapter{The GPM unit}
+
+\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 : integer;
+  dy : integer;
+  x : integer;
+  y : integer;
+  wdx : integer;
+  wdy : integer;
+  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}
+
+\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}{Gpm\_FitValuesM},
+\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}
+
+\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}
+
+\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}
+\Errors
+\SeeAlso
+\end{functionl}
+
+\begin{functionl}
+\Declaration
+function Gpm_Repeat(millisec:longint):longint;cdecl;external;
+\Description
+\Errors
+\SeeAlso
+\end{functionl}
+
+\begin{functionl}
+\Declaration
+function Gpm_StrictDouble(EventType : longint) : boolean;
+\Description
+\Errors
+\SeeAlso
+\end{functionl}
+
+\begin{functionl}
+\Declaration
+function Gpm_StrictSingle(EventType : longint) : boolean;
+\Description
+\Errors
+\SeeAlso
+\end{functionl}
+
+\begin{functionl}
+\Declaration
+function Gpm_StrictTriple(EventType : longint) : boolean;
+\Description
+\Errors
+\SeeAlso
+\end{functionl}