\input texinfo
@titlepage
@title LibGII API Manual
@subtitle For libggi 2.0, imminent release
@author Steve Cheng
@page
@vskip 0pt plus 1fill
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@end titlepage
@node top
@top LibGII API Manual
This document describes the application programming interface for LibGII,
a flexible library for input. It is used by LibGGI.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@node Preface
@chapter Preface
There should not be any more changes to the LibGII/LibGGI API until the next
major version. Unfortunately, implementation and documentation do not
always match; if you encounter any such differences
or have any other questions or comments on this documentation, please
mail us at @email{steve@@ggi-project.org}, or the GGI mailing list. Thank you.
For other developers: if you want to change this manual and do not know
DocBook/SGML, just mail me the ASCII version and I will gladly format
and include it for you.
This manual is primarily written as a reference to the user-visible API
of LibGII. However, it is being expanded to cover basic graphics
concepts as well. It will not be a full tutorial, as actual working
code serves that function better. This manual is also not intended to
be an LibGII internals guide, although implementation hints are dropped
throughout the manual :)
This documentation is written in DocBook. The SGML source
can be used to generate Unix manpages, HTML and text formats
automatically.
@node Introduction
@chapter Introduction
LibGII (General Input Interface Library) is a flexible library for handling
input from a variety of sources, including keyboards, mice, joysticks, etc.
LibGII consists of a main library (@file{libgii.so}) and a multitude of
dynamic drivers. The library then loads the necessary "drivers" for the
requested input.
@node General
@chapter General
To use LibGII, #include @file{ggi/gii.h} in a C program.
Most LibGII functions return @code{0} to indicate success, and a
negative error code to indicate errors. @code{Return codes
greater than 0} are usually additional hints or other non-negative
integer data.
A list of error codes and descriptions can be found in the
@file{ggi/errors.h} file, which is part of the
LibGGI/LibGG package.
@node Library control
@chapter Library control
@menu
* giiInit::
* giiPanic::
@end menu
@node giiInit
@section giiInit
@menu
@end menu
@subheading Name
giiInit, giiExit --- Initialize and uninitialize LibGII
@subheading Synopsis
@example
#include <ggi/gii.h>
int giiInit(void);
int giiExit(void);
@end example
@subheading Description
@code{giiInit} initalizes the library. This function must be called
before using other LibGII functions; otherwise the results will be undefined.
@code{giiExit} uninitializes the library (after being initalized by
@code{giiInit}) and automatically cleanup if necessary. This should be
called after an application is finished with the library. If any GGI
functions are called after the library has been uninitialized, the results
will be undefined.
@code{giiInit} allows multiple invocations. A reference count is
maintained, and to completely uninitialize the library, @code{giiExit}
must be called as many times as @code{giiInit} has been called
beforehand.
@subheading Return value
@code{giiInit} returns @code{0} for OK, otherwise an error code.
@code{giiExit} returns:
@table @asis
@item @code{0}
after successfully cleaning up,
@item @code{> 0}
the number of 'open' @code{giiInit} calls, if there has been more
than one call to @code{giiInit}. As @code{giiInit} and
@code{giiExit} must be used in properly nested pairs, e.g. the first
@code{giiExit} after two @code{giiInit}s will return 1.
@item @code{< 0}
error, especially if more @code{giiExit} calls have
been done than @code{giiInit} calls.
@end table
@subheading Examples
Initialize and uninitialize LibGII
@sp 1
@example
if (!giiInit())
@{
exit(EXIT_FAILURE); /* can't start! */
@}
@var{/* Do some libgii stuff */}
giiExit();
@end example
@node giiPanic
@section giiPanic
@menu
@end menu
@subheading Name
giiPanic --- Exit LibGII programs for fatal errors
@subheading Synopsis
@example
#include <ggi/gii.h>
int giiPanic(const char *format, ...);
@end example
@subheading Description
@code{giiPanic} does a graceful shutdown, with
@code{printf}(3)-style
reporting, taking a format string and any additional variables. It will
close all inputs, print the given error message to stderr, and then exit
the application.
@code{giiPanic} should only be used by usermode programs when something
is really screwed, and they do not know what to do. The same applies for
libraries, but might be used in rare situations such as corruption of
critical data structures.
@subheading Return value
Never returns.
@subheading Examples
An unrecoverable error
@sp 1
@example
if (my_important_struct->magic != MAGIC) @{
giiPanic("Fatal error: magic corrupted\n");
@}
@end example
@subheading Description
@code{giiOpen} opens an input. This function is given the name of an
input driver to load. Passing @code{NULL} here results in an auto-select
mechanism, which currently means examining the contents of
@code{GII_INPUT}.
The optional arguments are a @code{NULL}-terminated list of pointers,
which are used to give additional information to the targets. Currently
only the first pointer is specified: @code{void*} @code{argptr}, a
pointer to a library-specific struct. It is used to pass parameters that
are not easily transferable in textual form.
Parameters which can be represented in text format are usually transfered
in the @code{input} parameter, in the format:
@samp{library_name:
arguments}
@code{giiJoinInputs} joins two inputs into one. From a programmers'
point of view, this closes both @code{inp} and @code{inp2} and
opens an new input that combines both inputs into one. That is, after
@code{giiJoinInputs} has completed, there is no need to
@code{giiClose} @code{inp} and @code{inp2} any more. When
cleaning up, you need to close the returned input instead. See the
example for details. However the inputs are not actually closed or
reopened internally. That is, you will not get any startup-events or
similar the driver generates, though pending events of both old inputs
are transferred to the newly created input.
@code{giiClose} releases and destroys an open input and its
associated internal control structures. This will put back
input streams to their default modes, etc.
@subheading Return value
@code{giiOpen} and @code{giiJoin} return the
opened or joined input (@code{gii_input_t}), or @code{NULL} for error.
@code{giiClose} returns @code{0} for OK, otherwise an error
code.
/* Initialize the GII library. This must be called before any other
* GII function. */
if (giiInit() != 0) exit(1);
/* Open the nulldevice for testing ... */
if ((inp=giiOpen("input-null",NULL)) == NULL) @{
giiExit();
exit(1);
@}
/* Open stdin for testing ... */
if ((inp2=giiOpen("input-stdin",NULL)) == NULL) @{
giiExit();
exit(1);
@}
/* Now join them. Note the usage of _i_n_p_=_giiJoin(inp,inp2);
* This is the recommended way to do this. */
inp=giiJoinInputs(inp,inp2);
/* Note that this mends inp2 into inp. That is you may not call
giiClose(inp2) - this happens together with giiClose(inp) ! */
@var{... do the real work here ...}
/* Close the joined input */
giiClose(inp);
/* Now close down LibGII. */
giiExit();
@end example
@subheading See Also
@ref{giiInit}
@node giiSetEventMask
@section giiSetEventMask
@menu
@end menu
@subheading Name
giiSetEventMask, giiGetEventMask, giiAddEventMask, giiRemoveEventMask --- set the types of events you want to see
@subheading Synopsis
@example
#include <ggi/gii.h>
int giiSetEventMask(gii_input_t inp, gii_event_mask evm);
gii_event_mask giiGetEventMask(gii_input_t inp);
int giiAddEventMask(gii_input_t inp, gii_event_mask mask);
int giiRemoveEventMask(gii_input_t inp, gii_event_mask mask);
@end example
@subheading Description
@code{giiSetEventMask} sets the mask of events you want to receive.
Keep that down to those you really handle, as this allows to save
time and memory by skipping checks and not allocating queues for
events you will never read out.
@code{giiGetEventMask} lets you query the currently set mask.
@code{giiAddEventMask} and @code{giiRemoveEventMask} are macros that
set or delete individual bits in the bitmask.
@subheading Return value
@code{giiSetEventMask}, @code{giiAddEventMask} and
@code{giiRemoveEventMask} return @code{0} on success or an error
code otherwise.
@code{giiGetEventMask} returns the currently set mask.
@node giiEventPoll
@section giiEventPoll
@menu
@end menu
@subheading Name
giiEventPoll, giiEventSelect, giiEventsQueued, giiEventRead --- wait for and receive events
int giiEventSelect(gii_input *inp, gii_event_mask *mask,
int n,
fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
struct timeval *timeout);
int giiEventsQueued(gii_input_t inp, gii_event_mask mask);
int giiEventRead(gii_input_t inp, gii_event *ev, gii_event_mask mask);
@end example
@subheading Description
@code{giiEventPoll} waits for specific events to become available on
an input. This call somewhat resembles the Unix @code{select}(2)
call, but only for LibGII events and is more portable. This function
is given the input to wait on, a mask of events, any of which will
terminate the waiting, and a timeout @code{t}, after which the
waiting will cease anyway. In case an event arrives, the timeout value
is updated to the time that would have been remaining. So make sure to
re-setup this value, when calling @code{giiEventPoll} in a loop.
@code{giiEventSelect} is the combination of @code{giiEventPoll}
and @code{select}(2) allowing to wait for both LibGII events and arbitrary file
descriptors in any of the three states. However, this function is
@emph{not} available if the operating system does not support the
@code{select}(2) call, not even as a stub.
@code{giiEventsQueued} returns the number of events matching the
specified event mask that are currently queued in the input.
@code{giiEventRead} blocks for and transfers an event from the
given input to the location pointed to by @code{ev}. The event with
the earliest timestamp that matches the given mask is returned to the
application.
@subheading Return value
@code{giiEventPoll} returns a mask of available events
(constrained by the given mask). It is @code{0} if no events are
available. On error, a negative error code is returned.
@code{giiEventSelect} returns the same values as @code{select}(2).
Unlike other LibGGI/LibGII functions, it also uses @code{errno}.
It will update the timeout regardless of whether or not the system call
does so.
@code{giiEventsQueued} returns the number of events.
@code{giiEventRead} returns the size of event on success, and
@code{0} on error.
@node giiEventSend
@section giiEventSend
@menu
@end menu
@subheading Name
giiEventSend --- inject an event into the input
@subheading Synopsis
@example
#include <ggi/gii.h>
int giiEventSend(gii_input_t inp, gii_event *ev);
@end example
@subheading Description
@code{giiEventSend} injects an event into the queue. Such events can be
identified by @samp{(event->any.origin == GII_EV_ORIGIN_SENDEVENT)}.
There are three main uses for this function:
@itemize @bullet
@item
"Simulating" input for independent subprograms.
@item
Sending events to externally attached programs via specialized
"inputs", that are actually rather "outputs".
@item
Sending command events to inputs, like querying the axis of a
valuator device.
@end itemize
@subheading Return value
@code{giiEventSend} returns @code{0} on success, or an
error code otherwise.
@subheading See Also
@ref{giiEventPoll}
@node Event Structures
@chapter Event Structures
All of the event structures are included by @file{ggi/events.h}.
Events are of type @code{gii_event}. It is a union of all of the
LibGII event structures:
All of the event structures begin with @code{COMMON_DATA}, which
contains housekeeping information:
@example
#define COMMON_DATA \
uint8 size; /* size of event in bytes */\
uint8 type; /* type of this event */\
sint16 error; /* error (for replies) */\
uint32 origin; /* origin device (etc) */\
uint32 target; /* target device (etc) */\
struct timeval time /* timestamp */
@end example
@table @asis
@item @code{size}
specifies the size of the given event
(in bytes). Note that @code{size} is also accessable as the first
member of @code{gii_event} as well.
@item @code{type}
is an enumeration of the possible types of LibGII events:
@example
typedef enum gii_event_type @{
evNothing = 0, /* event is not valid. (must be zero) */
evCommand, /* report command/do action */
evInformation, /* notification of new information */
evExpose, /* exposure event */
/* empty slot */
evKeyPress=5, /* key has been pressed */
evKeyRelease, /* key has been released */
evKeyRepeat, /* automatically repeated keypress */
Thus, by analyzing the contents of @code{any.type}, you can determine
what the given event is, and select the appropriate member of the
@code{gii_event} union to access to get at the event data.
@item @code{error}
is mainly there to round things
up to a 32 bit boundary, but could be used to signal an error in a
send-reply sequence.
@item @code{origin}
is a device handle; it distinguishes one input device from
another, other than that there's no real meaning to the number.
@item @code{target}
is also a device handle, but for distinguishes input devices
when sending events @emph{to} an input device (e.g. via
@code{giiEventSend}).
@item @code{time}
indicates when the event in question has been generated.
@end table
@menu
* Key events::
* Pointer movement events::
* Pointer button events::
* Commands and information::
* Valuators::
* Expose events::
@end menu
@node Key events
@section Key events
The @code{gii_key_event} structure represents key/button events from
keyboards and other devices.
Event types:
@itemize @asis
@item
@code{evKeyPress}
@item
@code{evKeyRepeat}
@item
@item
@code{evKeyRelease}
@end itemize
@example
/* key events should be used to report events obtained from keys and
** other switches.
*/
typedef struct gii_key_event @{
COMMON_DATA;
uint32 modifiers; /* current modifiers in effect */
uint32 sym; /* meaning of key */
uint32 label; /* label on key */
uint32 button; /* button number */
@} gii_key_event;
@end example
@table @asis
@item @code{effect}
specifies the modifiers currently in effect, for example, the shift keys on
a keyboard.
@item @code{sym}
is the 'symbol' of the key, describing the resultant character produced by
the key. This is roughly the '@code{label}' on the key (described
below) combined with the @code{effect}.
@item @code{label}
is the actual label which is present on the key in question, and the
main '@code{sym}bol' on the key. @code{label} can be used
as a generalized, portable keycode or scancode of the key.
@item @code{button}
is the button number distinguishing between the different buttons on the
device. For example, on a keyboard it is a number from 0 to 127 (i.e. a
'scancode'), on a joystick it might be 1 to 4, and on a spaceorb it will
be 1 to 8.
@end table
In GGI, key values and characters are specified in accordance to
@file{ggi/keyboard.h}. They are organized in a similar
way to Linux keysyms (but without the braindamage) and Unicode.
However, in the GGI system, no key is guaranteed to exist; the key
values are for identification only. Particularly, applications should
@emph{not} rely on their presence. Also, because not all keyboards
are configured in the same way, GGI application are encouraged to allow
user configuration of the keys used and not hardcode them.
@menu
* GGI keysym system::
@end menu
@node GGI keysym system
@subsection GGI keysym system
A list of GGI keysyms and some macros for manipulating them are found in
@file{gii/keyboard.h}.
To be done.
@node Pointer movement events
@section Pointer movement events
@example
/* This is used to report change of pointer position.
** Depending on the event type, the values are either absolute
** or relative.
*/
typedef struct gii_pmove_event @{
COMMON_DATA;
sint32 x, y; /* absolute/relative position */
sint32 z, wheel;
@} gii_pmove_event;
@end example
The @code{gii_pmove_event} structure describes pointer motion in terms
of the x, y, z coordinates and the 'wheel'. The motion described may be
relative (offset from the current location) or absolute (a specific location
on the 'screen'), depending on whether the event is of type @code{evPtrRelative}
or @code{evPtrAbsolute}, respectively.
@node Pointer button events
@section Pointer button events
@example
/* Button events are sent to report a change in pointer button
** state. Depending on the event type, the button is either being
** pressed or released.
*/
typedef struct gii_pbutton_event @{
COMMON_DATA;
uint32 button; /* button number. This is a number, NOT a mask */
@} gii_pbutton_event;
@end example
@code{gii_pbutton_event} simply specifies that the
@code{button} is being pressed (type @code{evPtrButtonPress}) or released
(type @code{evPtrButtonRelease}).
Pointer buttons are specified in order of common usage, with 1 being the
primary button:
@example
#define GII_PBUTTON_LEFT 1 /* Left or primary button */
#define GII_PBUTTON_PRIMARY 1
#define GII_PBUTTON_FIRST 1
#define GII_PBUTTON_MIDDLE 3 /* Middle or tertiary */
#define GII_PBUTTON_TERTIARY 3
#define GII_PBUTTON_THIRD 3
@end example
Of course, applications should avoid hardcoding mouse button values.
@node Commands and information
@section Commands and information
@code{gii_cmd_event} is the basic structure for @code{evCommand} and
@code{evInformation} events. It may need to be casted to some other
structure (depending on @code{code}) to access the data.
/* These are used internally either to the application or the
* kernel. The same event is used for both Command and Information
* events. The recipient must not store references to the data. If
* the data information is needed afterwards, copy it!
*/
typedef struct gii_cmd_event @{
COMMON_DATA;
uint32 code; /* command/request code */
uint8 data[GII_CMD_DATA_MAX]; /* command related data */
@} gii_cmd_event;
@end example
@menu
* Device information::
@end menu
@node Device information
@subsection Device information
One use of @code{evCommand} is to convey some capabilities of a GII
device:
@example
/* This event is sent/received to require/get the capabilities of a device
* as specified in target/origin.
* An event stating num_buttons=num_axes=0 says, that the device is inactive,
* unplugged, whatever. Devices automatically report (detectable) state
* changes via devinfo. But you need to re-query the valinfo records.
*/
#define GII_CMDCODE_GETDEVINFO (0x01)
typedef struct gii_cmddata_getdevinfo @{
char longname[75];
char shortname[5];
gii_event_mask can_generate;
int num_buttons; /* Maximum number of buttons. */
int num_axes; /* Maximum number of axes. */
@} gii_cmddata_getdevinfo;
@end example
This event is guaranteed to be generated immediately after opening an input
source.
@code{can_generate} is a mask of all events that the device can
generate. @code{num_buttons} and @code{num_axes} are the
number of buttons and axes that the device can report on.
@node Valuators
@section Valuators
To be done.
@node Expose events
@section Expose events
If an application loses the focus and is not physically displayed (e.g.
console switching, iconifying), it may be stopped. Some targets may
implement a backbuffer and allow continuing, though.
After reactivation, the application will receive a redraw event,
@code{evExpose}. This is its structure, describing the region which needs
to be redrawn:
@example
typedef struct gii_expose_event @{
COMMON_DATA;
uint32 x,y;
uint32 h,w;
@} gii_expose_event;
@end example
How to use
@sp 1
@example
ggi_event ev;
@var{/* ... wait and get the event... */}
if (ev.any.type == evExpose) @{
/* redraw part of screen... */
redraw_screen(ev.expose.x, ev.expose.y,
ev.expose.w, ev.expose.h);
@}
