GNU Info

(gpm.info)Handling Functions

---

Next: Low Level Library Prev: The ClientLib Up: The ClientLib

---

Enter node , (file) or (file)node

Handling Functions
==================

   A mouse handler is a function which registers itself within the
library, and is called whenever a mouse event is reported to the
application. It is passed two arguments and returns an integer value,
according to the following typedef:

   `typedef int Gpm_Handler(Gpm_Event *EVENT, void *CLIENTDATA);'

   The EVENT is used to instantiate the mouse event just received, and
the CLIENTDATA pointer is needed to implement some higher level
functionality. An handler will be typically invoked by `Gpm_Getc', or
by the high-level library, and the following discussion assumes the
invoking function is `Gpm_Getc' (the high-level library only runs on
behalf of `Gpm_Getc').

   Handling functions can do whatever they want to, and return to the
caller an integer value, which can be used to generate a keyboard
event. This feature is useful in that often the mouse is a shortcut for
something which could be made by means of the keyboard.

   The application main loop can detect if the keyboard event is a
physical or generated one by looking at the global variable
`gpm_hflag', which is not zero only for handler-generated events.

   An handling function can generate more than one key in response of a
single mouse event. If it sets the global variable `gpm_morekeys' to a
non-zero variable before returning, it will be invoked again without
waiting for mouse events. You can use `gpm_morekeys' as a counter of how
many times you want to be called again - the client library only
compares it to zero.

   The return value from an handler is used as follows:

`EOF'
     This value is used to signal a fatal error, and will cause
     `Gpm_Getc' to return the same value to the caller, after setting
     `gpm_hflag' to 1.

`0'
     A zero return value means that `Gpm_Getc' should go on as before,
     without returning to the caller. The event has been eaten by the
     handler and no key-press is simulated.

`ANYTHING-ELSE'
     Any other value is considered a simulated character, and is
     returned to the caller after setting `gpm_hflag'.  This allows a
     quick way to implement yes/no boxes and simple menus without
     interfering with the main body of an existing application.
     Moreover, if return values greater than 255 are used a single
     switch loop can parse both keyboard and mouse events.

A mouse handler is passed as second argument the content of the
`gpm_data' variable, i.e. the current clientdata. The clientdata is
almost unuseful unless you use the high-level library, because it holds
a static value. Delivering the clientdata however allows the high-level
management of mouse events to be a superset of the low-level code,
rather than an incompatible alternative.