---

Administrative Functions
[Core PicoGUI API]

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	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 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: --pgserver Connects to the PicoGUI server specified in --version 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: PG_FM_SET: Set all video flags to the specified value PG_FM_ON: Turns on specified flags, leaves others untouched PG_FM_OFF: Turns off specified flags PG_FM_TOGGLE: Toggles specified flags 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: PG_VID_FULLSCREEN: Uses a fullscreen mode if available PG_VID_DOUBLEBUFFER: Uses double buffering if available PG_VID_ROTATE90, PG_VID_ROTATE180, PG_VID_ROTATE270: Rotate the screen by the indicated number of degrees anticlockwise. All rotation flags are mutually exclusive. 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

---