gpm: Connection Details
3.4 Connection Details
======================
Each virtual console has a stack of clients attached to it. They talk
to gpm by writing to a control socket and get mouse events by reading
it. All the clients in the stack can receive events. Gpm-1.10 and
earlier only sent events to the top client, but sometimes users play
with multiple programs using suspend-resume (thanks Ian).
In addition to the per-console stacks, another stack is there to
store default-handling clients. 
Default Handlers.
Each client registers with the server and tells which events it is
interested in. Events not managed by the client can be handled by the
selection mechanism, which is compiled in the server itself. This
approach simplifies writing clients which respond only to button
press/release events, because highlighting the mouse pointer can be
performed by the server. A default handler in turn can respond only to
mouse events associated with modifier keys, so that selection is used
for any mouse-only event.
Clients are required to fill a 'Gpm_Connect' structure and pass it to
the server. The structure is made up by four 'unsigned int' fields.
Open and Close.
'eventMask'
A bitmask of the events the client wants to receive. Both bare and
cooked events are allowed to appear in the mask.
'defaultMask'
A mask to tell which events allow a default treatment (the
selection one). These are mouse events, independent of the
modifier keys.
'minMod'
The minimum amount of modifiers required by the client. This field
is used for default-handlers which manage control-mouse events
without interfering with mouse-only ones. Default
Handlers.
'maxMod'
The maximum amount of modifiers the client is willing to receive.
Events featuring a modifier key not included in 'maxMod' won't be
passed to the client.
Two more fields are there to tell about the connection itself, and
you're not asked to fill them, because 'Gpm_Open' will do it for you.
'int pid'
The process id of the connecting application.
'int vc'
Which virtual console to gain control of.
Keyboard modifiers are used to multiplex clients on the same virtual
console. You (as a programmer) don't need to care about the internal
workings. They are detailed in Default Handlers, but you only
need to choose the right values for your application.
Examples:
'minMod=0; maxMod=0;'
specifies a client which senses mouse-only events, but neither
shift-mouse nor alt-mouse nor control-mouse.
'minMod=0; maxMod=~0;'
is a client which gets any mouse event.
'minMod=1<<KG_SHIFT; maxMod=1<<KG_SHIFT;'
is a client which senses all shift-mouse events and nothing more.
'minMod=1<<KG_SHIFT; maxMod=~0;'
is a client interested in shift-and-whatever-else mouse events, but
disregarding mouse-only events.
If the modifier keys in the event are too few or too many, the event
won't be reported to the client. If the modifiers are right but the
current event is not part of the 'eventMask', it is not reported as
well. If the event is not used by the client, it can nonetheless be
passed to another client (a default handler or the internal selection
mechanism), according to the 'defaultMask'. If the event has been
already reported to the current application, it will also be passed
along the chain, if the GPM_HARD bit is set the 'defaultMask'.
Good values for 'defaultMask' can thus be the following:
'0'
To sink any event, even those I don't use.
'~eventMask'
Pass along any event I don't use.
'~GPM_HARD'
Just the same, independently of 'eventMask'.
'GPM_MOVE|GPM_HARD'
Pass motion events, even if I use them. This is the good choice
for an application which wants information on mouse motion, but
leaves the task of cursor-drawing to the server.
Info Catalog
gpm: Event Types
gpm: Gpm Internals
gpm: Default Handlers