Manpages

NAME

Administrative Functions −

Functions

void pgInit (int argc, char **argv)
Initialize PicoGUI.
void pgSetErrorHandler (void(*handler)(u16 errortype, const char *msg))
Replace the default error handler.
pghandle pgLoadDriver (const char *name)
Load an input driver by name and return a handle.
const char * pgErrortypeString (u16 errortype)
Convert a numerical errortype to a string.
pgidlehandler pgSetIdle (s32 t, pgidlehandler handler)
Set a handler to be called periodically.
void pgFlushRequests (void)
Flush all unsent request packets to the server.
void pgUpdate (void)
Update the screen.
void pgSubUpdate (pghandle widget)
Update a subsection of the screen.
void pgBind (pghandle widgetkey, s16 eventkey, pgevthandler handler, void *extra)
Attatch an event handler to a widget and/or event.
void pgCustomizeSelect (pgselecthandler handler, pgselectbh bottomhalf)
Wait on your own file descriptors.
void pgRegisterOwner (int resource)
Register exclusive access to a resouce.
void pgUnregisterOwner (int resource)
Unregister exclusive access to a resouce.
void pgSetVideoMode (u16 xres, u16 yres, u16 bpp, u16 flagmode, u32 flags)
Change video mode at runtime.
pgmodeinfo * pgGetVideoMode (void)
Get information about the current video mode.
void pgDriverMessage (u32 message, u32 param)
Send a message to the drivers.
void pgAppMessage (pghandle dest, struct pgmemdata data)
Send a message to a widget owned by any application.
void * pgSyncAppMessage (pghandle dest, struct pgmemdata data)
Send a message to a widget owned by any application, and wait for an answer.
pghandle pgEvalRequest (s16 reqtype, void *data, u32 datasize)
Evaluate a PicoGUI request packet.
void pgSetInactivity (u32 time)
Set the inactivity timer.
u32 pgGetInactivity (void)
Get the inactivity timer.
pghandle pgGetServerRes (u32 id)
Get a server resource.

Detailed Description

Functions that affect the entire server, or the connection between client and server. Includes pgInit, error handling, and exclusive access

Function Documentation

void pgAppMessage (pghandle dest, struct pgmemdata data)
Send a message to a widget owned by any application.Parameters:

dest Handle of the destination widget
data A pgmemdata structure containing the data, as returned by a pgFrom* function

The data parameter is sent as the data in a PG_WE_APPMSG event on behalf of the dest widget.

void pgBind (pghandle widgetkey, s16 eventkey, pgevthandler handler, void * extra)
Attatch an event handler to a widget and/or event.Parameters:

widgetkey A widget to attach to, or PGBIND_ANY to respond to any widget’s events
eventkey An event to attach to, or PGBIND_ANY to respond to any event by the selected widget(s).
handler A pointer to a PicoGUI event handler
extra The value to pass within the pgEvent’s extra field

When the widgetkey and eventkey both match, the handler is called, and the specified value for extra is passed in its pgEvent structure. The extra value passed depends on the binding that triggered the call, not on the widget or event involved. If widgetkey and eventkey are exactly the same as an existing binding, its handler and extra value are reset to the ones specified here. If handler is NULL the binding is deleted.

See also:

pgevthandler, pgEvent

void pgCustomizeSelect (pgselecthandler handler, pgselectbh bottomhalf)
Wait on your own file descriptors.Parameters:

handler If non-NULL, this is used instead of select() in the client library

This function allows you to specify a handler that acts as a wrapper around the client library’s calls to select(), so you can wait on your own file descriptors.

IMPORTANT: The select() handler can not make any PicoGUI calls, because the event queue is in an unknown state. The ’bottomhalf’ function will be called shortly after the select handler returns, and it is allowed to make PicoGUI API calls.

To cancel this, call with a NULL handler and the select handle will be set back to the standard select() system call.

To use this function, the proper header files must be included before picogui.h for select()

See also:

pgSetIdle, pgEventLoop

void pgDriverMessage (u32 message, u32 param)
Send a message to the drivers.Parameters:

message A PGDM_* driver message constant
param Defined by the type of message sent

This command can send ’extra’ commands that may be hardware-specific, like beeps, cursor blanking, and backlight control.

const char* pgErrortypeString (u16 errortype)
Convert a numerical errortype to a string.Parameters:

errortype A PG_ERRT_* error type constant

Returns:

A pointer to the corresponding string constant

pghandle pgEvalRequest (s16 reqtype, void * data, u32 datasize)
Evaluate a PicoGUI request packet.Parameters:

reqtype A PGREQ_* constant indicating the packet type
data Pointer to the raw packet data
datasize Length of raw packet data

Returns:

Returns the request packet’s return value, if any. If the request packet does not return a simple data type, the value is undefined.

This is a good way to reuse PicoGUI’s serialization capabilities to load a generic binary object from file. It is advisable to validate the request’s type first so you don’t allow the input to do wierd things like change video mode or leave the current context.

The format of the data accepted by the request packet depends on the type of packet.

void pgFlushRequests (void)
Flush all unsent request packets to the server.Usually this is handled automatically, but it is needed in some situations. For example, a remote input driver that has no real event loop, but needs to send keyboard or mouse events. The events would not actually be sent to the server until pgFlushRequests is called.

See also:

pgUpdate

u32 pgGetInactivity (void)
Get the inactivity timer.Returns:

The inactivity timer value in milliseconds

This timer is maintained by PicoGUI. It continually increments, but it is cleared whenever user input is recieved and it can be set by pgSetInactivity

See also:

pgSetInactivity

pghandle pgGetServerRes (u32 id)
Get a server resource.Returns:

The resource handle associated with the given PGRES_* constant

struct pgmodeinfo* pgGetVideoMode (void)
Get information about the current video mode.Returns:

A pgmodeinfo structure with information about the current video mode.

The returned pointer is good only until the next PicoGUI call. It is recommended to use something like the following:

struct pgmodeinfo mi;
mi = *pgGetVideoMode();

See also:

pgSetVideoMode, pgmodeinfo

void pgInit (int argc, char ** argv)
Initialize PicoGUI.See if there are any command line args relevant to PicoGUI (such as for setting the PicoGUI server) and establish a connection to the server. This must be the first PicoGUI call in the client, and it should almost certainly be called before and command line processing.

pgInit processes command line arguments beginning with ’--pg’ and removes them from the argument list and terminates argv[] with a NULL. This is compatible with optarg and probably other argument-processing systems. Currently the following arguments are handled:

Connects to the PicoGUI server specified in

Prints the client library version

Unrecognized commands beginning with ’--pg’ display a list of available commands. If it is unable to contact the server, a client error is triggered.

The client does not need to explicitly disconnect from the PicoGUI server

See also:

pgRegisterApp, pgSetErrorHandler

pghandle pgLoadDriver (const char * name)
Load an input driver by name and return a handle.Parameters:

name Driver name as reported by ’pgserver -l’

Returns:

A handle to the loaded driver

void pgRegisterOwner (int resource)
Register exclusive access to a resouce.Parameters:

resource A PG_OWN_* constant indicating the resource you request

If the resource is already in use or cannot be obtained, a client error is triggered

See also:

PG_OWN_KEYBOARD, PG_OWN_POINTER, PG_OWN_SYSEVENTS

void pgSetErrorHandler (void(* handler)(u16 errortype, const char *msg))
Replace the default error handler.Parameters:

handler A pointer to the new handler function
errortype The general type of error, a PG_ERRT_* constant
msg A message string with more information

Errors can be triggered by the client (in the case of an IO error or fatal signal) or by the server. (A bug somewhere, out of memory, etc.)

The default error handler displays a message dialog allowing the user to optionally terminate the program. If it is unable to display the message dialog, the error is printed to stderr and the program is terminated.

See also:

pgInit, pgErrortypeString

pgidlehandler pgSetIdle (s32 t, pgidlehandler handler)
Set a handler to be called periodically.Parameters:

t Maximum number of milliseconds to wait between calls to handler
handler Pointer to a handler function, or NULL to disable

Returns:

Pointer to the previous handler function

This is based on the pgSetnonblocking code added by Philippe, but this fits the event-driven model better, and most importantly it handles stopping and starting the event loop automatically. Note that it is still possible for PicoGUI to block if the server sends a partial reply packet, but even if the idle handler were called during this time the network connection would be ’jammed’ so there wouldn’t be much point.

See also:

pgEventLoop

void pgSetInactivity (u32 time)
Set the inactivity timer.Parameters:

Inactivity timer value in milliseconds

This sets the inactivity timer. Set it to zero periodically if you want to prevent screensavers or sleep modes from activating even if there is no user input.

See also:

pgGetInactivity

void pgSetVideoMode (u16 xres, u16 yres, u16 bpp, u16 flagmode, u32 flags)
Change video mode at runtime.Parameters:

xres New horizontal resolution
yres New vertical resolution
bpp Color depth in bits per pixel
flagmode PG_FM_* constant specifying how to combine flags with the current video flags

xres, yres, and bpp can be zero to keep the current values.

flagmode can have the following values:

flags specifies extra optional features that may be present in the video driver. Unsupported flags are ignored. It can be zero or more of the following values or’ed together:

See also:

pgGetVideoMode

void pgSubUpdate (pghandle widget)
Update a subsection of the screen.The given widget and all other widgets contained within it are redrawn if necessary. The request buffer is flushed and the section is redrawn independantly and immediately.

This function is recommended for animation. Areas of the screen other than the specified widget and its children are never updated, and SubUpdates can occur in toolbars even while a popup dialog is onscreen.

See also:

pgUpdate, pgFlushRequests

void* pgSyncAppMessage (pghandle dest, struct pgmemdata data)
Send a message to a widget owned by any application, and wait for an answer.Parameters:

dest Handle of the destination widget
data A pgmemdata structure containing the data, as returned by a pgFrom* function

Returns:

Returns a pointer to the answer message. This will have to be freed by the calling application.

The data parameter is sent as the data in a PG_WE_APPMSG event on behalf of the dest widget.

This call acts very similarly to pgAppMessage, except that the calling client is blocked until the remote widget has sent an answer message. The answer is application specific.

NOTE: The data is assumed to be a structure whose very first field is of type pghandle. This field will be used by pgSyncAppMessage to store the widget handle to which the receiver will send the answer.

void pgUnregisterOwner (int resource)
Unregister exclusive access to a resouce.Parameters:

resource A PG_OWN_* constant indicating the resource you release

An error will be triggered if the client does not already own the specified resource.

See also:

pgRegisterOwner

void pgUpdate (void)
Update the screen.Redraw portions of the screen if necessary. This forces all unsent packets to be flushed to the server, and instructs the server to draw changed areas of the screen.

If your application is pgEventLoop (or pgGetEvent) based, this is handled automatically. The server always updates the screen before waiting for user interaction.

For doing animation, consider using pgSubUpdate instead.

See also:

pgFlushRequests, pgSubUpdate