GNU Info

(gpm.info)Connection Details

---

Next: Default Handlers Prev: Event Types Up: Gpm Internals

---

Enter node , (file) or (file)node

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.  Note: 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.
Note: 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.  Note: 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 Note: 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.