Main Page Modules Alphabetical List Compound List File List Compound Members File Members

# 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