gpm: Handling Functions
4.1 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.
Info Catalog
gpm: The ClientLib
gpm: The ClientLib
gpm: Low Level Library