api.c File Reference

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

# /home/micah/picogui/pg1/client/c/src/api.c File Reference

`#include "clientlib.h"`
`#include <sys/types.h>`
`#include <sys/stat.h>`
`#include <unistd.h>`

## Defines
#define | DBG(fmt, args...) printf( "%s: " fmt, __FUNCTION__ , ## args); fflush(stdout)
#define | PGDM_INPUT_RAW 8
## Functions
void | pgUpdate (void)
| Update the screen.
int | pgEnterContext (void)
| Enter a new context.
int | pgGetContext (void)
| Get the current context ID.
void | pgLeaveContext (void)
| Leave a context.
void | pgSetContext (int id)
| Set the context ID used when creating new handles.
void | pgDeleteHandleContext (int id)
| Delete all handles in one context.
pghandle | pgDataString (struct pgmemdata obj)
| Load memory into a string handle.
pghandle | pgLoadTheme (struct pgmemdata obj)
| Load a compiled theme.
pghandle | pgLoadWidgetTemplate (struct pgmemdata obj)
| Load a compiled Widget Template.
u32 | pgThemeLookup (s16 object, s16 property)
| Retrieve a theme property.
pgmemdata | pgFromMemory (void *data, u32 length)
| Refer to data loaded into memory.
pgmemdata | pgFromTempMemory (void *data, u32 length)
| Refer to data loaded into memory, free when done.
pgmemdata | pgFromFile (const char *file)
| Refer to data in a file.
pgmemdata | pgFromStream (FILE *f, u32 length)
| Refer to data in an opened stream.
void | pgSetPayload (pghandle object, u32 payload)
| Set an object's payload.
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.
u32 | pgGetPayload (pghandle object)
| Get an object's payload.
pghandle | pgGetServerRes (u32 res)
| Get a server resource.
void | pgSetInactivity (u32 time)
| Set the inactivity timer.
u32 | pgGetInactivity (void)
| Get the inactivity timer.
pghandle | pgNewCursor (void)
| Create a cursor that can be used for input filters.
void | pgSubUpdate (pghandle widget)
| Update a subsection of the screen.
void | pgFocus (pghandle widget)
| Give a widget the keyboard focus.
void | pgDelete (pghandle object)
| Delete any object that has a handle.
pghandle | pgRegisterApp (s16 type, const char *name,...)
| Register a new application.
void | pgSetWidget (pghandle widget,...)
| Set widget properties.
pghandle | pgCreateWidget (s16 type)
| Create a new widget without a parent.
pghandle | pgNewInFilter (pghandle insert_after, u32 accept_trigs, u32 absorb_trigs)
| Create a new client-side input filter.
void | pgAttachWidget (pghandle parent, s16 rship, pghandle widget)
| Attach a widget to a new parent.
void | pgInFilterSend (union pg_client_trigger *trig)
| Send an event back from a client-side input filter.
pghandle | pgNewWidget (s16 type, s16 rship, pghandle parent)
| Create a new widget, derived from a parent widget.
pghandle | pgNewPopupAt (int x, int y, int width, int height)
| Create a popup box at the specified position.
pghandle | pgNewFont (const char *name, s16 size, u32 style)
| Create a new font object.
pghandle | pgNewPopup (int width, int height)
| Create a popup box, centered on the screen.
pghandle | pgNewBitmap (struct pgmemdata obj)
| Create a new bitmap object from existing data.
pghandle | pgCreateBitmap (s16 width, s16 height)
| Create a new bitmap object.
pghandle | pgNewString (const char *str)
| Create a new string object.
pghandle | pgFindWidget (const char *str)
| Search for a widget by its PG_WP_NAME property.
int | pgFindThemeObject (const char *str)
| Find a theme object's ID given its name.
pghandle | pgNewArray (const s32 *dat, u16 size)
| Create a new array object.
pghandle | pgEvalRequest (s16 reqtype, void *data, u32 datasize)
| Evaluate a PicoGUI request packet.
s32 | pgGetWidget (pghandle widget, s16 property)
| Get a widget property.
pghandle | pgTraverseWidget (pghandle widget, int direction, int count)
| Finds a widget in relation to another widget.
void | pgSizeText (int *w, int *h, pghandle font, pghandle text)
| Measure a string of text.
void | pgSizeBitmap (int *w, int *h, pghandle bitmap)
| Return the size of a bitmap object.
char * | pgGetString (pghandle string)
| Get the contents of a string handle.
pgshmbitmap * | pgMakeSHMBitmap (pghandle bitmap)
| Map a bitmap into a shared memory segment.
int | pgGetFontStyle (s16 index, char *name, u16 *size, u16 *fontrep, u32 *flags)
| Get information about a font style.
pgmodeinfo * | pgGetVideoMode (void)
| Get information about the current video mode.
void | pgDriverMessage (u32 message, u32 param)
| Send a message to the drivers.
void | pgReplaceText (pghandle widget, const char *str)
| Change a widget's text.
void | pgReplaceTextFmt (pghandle widget, const char *fmt,...)
| Change a widget's text, with formatting.
void | pgWriteData (pghandle widget, struct pgmemdata data)
| Write data to a widget.
void | pgWriteCmd (pghandle widget, s32 command, s16 numparams,...)
| Write a command to a widget.
void | pgRender (pghandle bitmap, s16 groptype,...)
| Render a gropnode to a bitmap.
pghandle | pgLoadDriver (const char *name)
| Load an input driver by name and return a handle.
pghandle | pgDup (pghandle object)
| Duplicate an object that has a handle.
void | pgChangeContext (pghandle object, s16 delta)
| Change the handle context of an object.
int | pgCheckEvent (void)
| Check the number of pending events.
void | pgEventPoll (void)
| Get and dispatch new events if there are any.
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.

## Define Documentation

#define DBG | ( | fmt,
|  | args... |  | ) | printf( "%s: " fmt, __FUNCTION__ , ## args); fflush(stdout)

#define PGDM_INPUT_RAW 8

## 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 pgAttachWidget | ( | pghandle | parent,
|  | s16 | rship,
|  | pghandle | widget
| ) |

  | Attach a widget to a new parent. Parameters:
  parent | The parent widget's handle, or PGDEFAULT.
  rship | A PG_DERIVE_* constant indicating the new widget's relationship to it's parent. It can be PGDEFAULT.
  widget | The widget to attach
This is necessary if you earlier created a widget using pgCreateWidget and now need to attach it to a parent, or if you want to reattach a widget to a different parent. If the widget has any subwidgets, they are moved along with the specified widget. See also: pgCreateWidget, pgDeleteWidget

void pgChangeContext | ( | pghandle | object,
|  | s16 | delta
| ) |

  | Change the handle context of an object. Parameters:
  object | A handle to any PicoGUI object
  delta | The value to add to the context level
A positive delta value increases the object's context, equivalent to adding extra pgEnterContext() layers. The delta value may be negative, to 'send' the handle to a higher-level context. For example, you may want to return data from a dialog box:
    pgEnterContext();
    pgDialogBox("My Dialog");
    ... Allocate lots of memory ...
    pgChangeContext(important_data,-1);
    pgLeaveContext();
    return important_data;
See also: pgEnterContext, pgLeaveContext

int pgCheckEvent | ( | void |  | ) |

| Check the number of pending events. Returns: The number of events in the application's queue The PicoGUI server keeps a ring buffer of waiting events for each client connected to it. This function returns the number of events waiting in this buffer. Note that this buffer is usually relatively small. At the time of this writing, it is set to hold 16 events. If the buffer is full, old events will be discarded. You can use this function if, for some reason, you need to poll PicoGUI events instead of waiting for them. In the middle of a long operation, for example, you may wish to periodically check if the user clicks a cancel button. If this function indicates that there are events waiting, pgGetEvent will return immediately with the oldest queued event. See also: pgGetEvent, pgEventLoop

pghandle pgCreateBitmap | ( | s16 | width,
|  | s16 | height
| ) |

  | Create a new bitmap object. Parameters:
  width | Width, in pixels, of the new bitmap
  height | Height, in pixels, of the new bitmap
Returns: A handle to the new bitmap object. It's contents are undefined See also: pgNewBitmap

pghandle pgCreateWidget | ( | s16 | type | ) |

  | Create a new widget without a parent. Parameters:
  type | A PG_WIDGET_* constant for the widget type
This function creates a widget, but does not attach it to the parent widget. You can still set the widget's parameters and attach child widgets to this one, but the widget cannot be drawn until you call pgAttachWidget. See also: pgAttachWidget, pgNewWidget

pghandle pgDataString | ( | struct pgmemdata | obj | ) |

  | Load memory into a string handle. Parameters:
  obj | A pgmemdata structure, as returned by a pgFrom* function
Returns: A handle to the new string object created in the PicoGUI server This is like pgNewString() except that the string is loaded from a pgmemdata structure, and it does not need to be null-terminated. This makes it easy to load text files, for instance. See also: pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext

void pgDelete | ( | pghandle | object | ) |

  | Delete any object that has a handle. Parameters:
  object | A handle to any type of object (String, widget, bitmap, etc.)
This function frees the memory in the PicoGUI server associated with `object.`

void pgDeleteHandleContext | ( | int | id | ) |

| Delete all handles in one context. This lets you use contexts as individuals with an ID rather than as a stack. pgLeaveContext() deletes the current context (stored per-connection) and decrements that current context. This function deletes the specified context without touching the current context number. This way new contexts can be requested and discarded indefinitely (or at least until the IDs wrap around, in which case the server will skip context nubmers that are in use) See also: pgEnterContext

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.

pghandle pgDup | ( | pghandle | object | ) |

  | Duplicate an object that has a handle. Parameters:
  object | A handle to one of several types of PicoGUI objects
Some objects simply can't be duplicated: For example, it would not make sense to duplicate a widget, driver, or theme. At the time of this writing, the only object type for which duplication is implemented is the string object. See also: pgDelete, pgNewString

int pgEnterContext | ( | void |  | ) |

| Enter a new context. PicoGUI uses a context system, similar to a variable's scope in C. Whenever the program leaves a context, all objects created while in that context are deleted. No memory is used by creating a context, and they can be nested a very large number of times. Returns: the ID of the new context Here is an example, indented to show the context levels:
    pghandle x,y,z;

    pgEnterContext();
      x = pgNewString("X");
      pgEnterContext();
        y = pgNewString("Y");
      pgLeaveContext();           // y is deleted
      z = pgNewString("Z");
    pgLeaveContext();             // x and z are deleted
See also: pgLeaveContext

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 pgEventPoll | ( | void |  | ) |

| Get and dispatch new events if there are any. This function is a non-blocking version of pgEventLoop(). It calls pgCheckEvent(), and if there are any new events it uses pgGetEvent() and pgDispatchEvent() to retrieve and process any pending events. This is good to call during an animation or other lengthy operation to check for the user clicking the close button, canceling the operation, etc. See also: pgGetEvent, pgCheckEvent, pgDispatchEvent

int pgFindThemeObject | ( | const char * | key | ) |

  | Find a theme object's ID given its name. Parameters:
  key | The "name" property to search for
Returns: The theme ID, or zero if it's not found This function is useful for finding custom theme objects. Theme objects defined as `custom` are assigned an ID automatically at load time. These objects can be found with this function as long as each is assigned a unique `name` property. See also: pgLoadTheme, pgFindWidget

pghandle pgFindWidget | ( | const char * | key | ) |

  | Search for a widget by its PG_WP_NAME property. Parameters:
  key | The name to search for
Returns: The handle of the found widget, or zero if no widget matches the supplied name Every widget can be given a name by setting it's PG_WP_NAME property to a string handle. This function can search for a widget's handle based on this name. Note that this function will search all widgets, even those not owned by this application. See also: PG_WP_NAME, pgSetWidget

void pgFocus | ( | pghandle | widget | ) |

| Give a widget the keyboard focus.

struct pgmemdata pgFromFile | ( | const char * | file | ) |

  | Refer to data in a file. Parameters:
  file | The name of the file containing data to be referred to
Returns: A pgmemdata structure describing the data. This is needed by many PicoGUI API functions that require data as input. Depending on implementation the file may be loaded into memory temporarily, or memory-mapped if possible See also: pgFromMemory, pgFromTempMemory, pgFromStream

struct pgmemdata pgFromMemory | ( | void * | data,
|  | u32 | length
| ) |

  | Refer to data loaded into memory. Parameters:
  data | A pointer to data loaded into memory
  length | The length, in bytes, of the data referred to
Returns: A pgmemdata structure describing the data When using pgFromMemory, the data pointer must remain valid for a relatively long period of time, usually until the request buffer is flushed. If you would rather have the client library free the memory for you when it is done, see pgFromTempMemory See also: pgFromFile, pgFromStream, pgFromTempMemory

struct pgmemdata pgFromStream | ( | FILE * | f,
|  | u32 | length
| ) |

  | Refer to data in an opened stream. Parameters:
  f | C stream, as returned by `fopen()` in `stdio.h`
  length | The number of bytes to read from the stream
Returns: A pgmemdata structure describing the data Depending on implementation, the data may be read from the stream into memory, or memory-mapped if possible. The chunk of data referred to begins at the stream's current position and extends `length` bytes past it. The stream's position is advanced by `length` bytes. See also: pgFromMemory, pgFromTempMemory, pgFromFile

struct pgmemdata pgFromTempMemory | ( | void * | data,
|  | u32 | length
| ) |

  | Refer to data loaded into memory, free when done. Parameters:
  data | A pointer to data loaded into memory
  length | The length, in bytes, of the data referred to
Returns: A pgmemdata structure describing the data The data pointer must have been dynamically allocated with malloc() or equivalent. When the client library is done using it, `data` will be freed with the free() function. See also: pgFromMemory, pgFromFile, pgFromStream

int pgGetContext | ( | void |  | ) |

| Get the current context ID. See also: pgDeleteHandleContext, pgEnterContext, pgLeaveContext, pgSetContext

int pgGetFontStyle | ( | s16 | index,
|  | char * | name,
|  | u16 * | size,
|  | u16 * | fontrep,
|  | u32 * | flags
| ) |

  | Get information about a font style. Parameters:
  index | A zero-based index to select a font style in the order that the were compiled or loaded into pgserver
  name | Pointer to a buffer to store the font name in. Must be 40 bytes long
  size | Pointer that the font size is returned in. For bitmapped fonts (all PicoGUI currently supports) this is height in pixels
  fontrep | Pointer that the font representation is returned in. This is a combination of one or more PG_FR_* flags.
  flags | Pointer that font style flags are returned in. This is a combination of PG_FSTYLE_* flags
Returns: Nonzero if the index was valid and data was stored in the supplied pointers This function can be used to iterate through the available fonts. For example:
    char name[40];
    u16 size;
    u16 fontrep;
    u32 flags;
    s16 i;

    i = 0;
    while (pgGetFontStyle(i++, name, &size, &fontrep, &flags)) {
       printf("Font #%d: %s\n"
              "    size: %d\n"
              " fontrep: 0x%04X\n"
              "   flags: 0x%08X\n\n",
              i,name,size,fontrep,flags);
    }
See also: pgNewFont

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

u32 pgGetPayload | ( | pghandle | object | ) |

  | Get an object's payload. Parameters:
  object | A handle to any PicoGUI object
Returns: The 32-bit piece of application-defined data set using pgSetPayload See pgSetPayload for more information about payloads and their uses. See also: pgSetPayload

pghandle pgGetServerRes | ( | u32 | id | ) |

| Get a server resource. Returns: The resource handle associated with the given PGRES_* constant

char* pgGetString | ( | pghandle | string | ) |

  | Get the contents of a string handle. Parameters:
  string | Must be a handle to a string object
Returns: A pointer to the string object's contents The returned string pointer must be treated as read-only. It is only valid until the next PicoGUI function call. See also: pgNewString

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

s32 pgGetWidget | ( | pghandle | widget,
|  | s16 | property
| ) |

  | Get a widget property. Parameters:
  widget | Widget handle
  property | A widget property (PG_WP_* constant)
Returns: The value associated with the specified property See also: pgSetWidget, pgNewWidget

void pgInFilterSend | ( | union pg_client_trigger * | trig | ) |

  | Send an event back from a client-side input filter. Parameters:
  trig | Client-side trigger union, representing the event
See also: pgNewCursor, pgNewInFilter

void pgLeaveContext | ( | void |  | ) |

| Leave a context. When leaving a context, all objects created within it are deleted, and the context ID is decremented. This default behavior simulates a stack of contexts. See pgEnterContext for an example. See also: pgEnterContext, pgDeleteHandleContext

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

pghandle pgLoadTheme | ( | struct pgmemdata | obj | ) |

  | Load a compiled theme. Parameters:
  obj | A pgmemdata structure, as returned by a pgFrom* function
Returns: A handle to the new theme object created in the PicoGUI server The compiled theme data can be generated using the `themec` utility. The theme can be unloaded by calling pgDelete with the returned theme handle. See also: pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext

pghandle pgLoadWidgetTemplate | ( | struct pgmemdata | obj | ) |

  | Load a compiled Widget Template. Parameters:
  obj | A pgmemdata structure, as returned by a pgFrom* function
Returns: A handle to the new Widget Template object created in the PicoGUI server This widget template is like a cookie-cutter that can be used to instantiate a whole tree of widgets or other objects. You instantiate the template using pgDup(). See also: pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgDup

struct pgshmbitmap* pgMakeSHMBitmap | ( | pghandle | bitmap | ) |

  | Map a bitmap into a shared memory segment. Parameters:
  bitmap | Handle to the bitmap to map
Returns: A pgshmbitmap structure with the SHM key and format info, valid until the next PicoGUI call This isn't well documented yet, see picogui/network.h for the pgshmbitmap structure. See also: pgNewBitmap, pgCreateBitmap

pghandle pgNewArray | ( | const s32 * | dat,
|  | u16 | size
| ) |

  | Create a new array object. Parameters:
  dat | The data to put in the array
  size | Number of entries in the array
Returns: A handle to the new array object

pghandle pgNewBitmap | ( | struct pgmemdata | obj | ) |

  | Create a new bitmap object from existing data. Parameters:
  obj | A pgmemdata structure, as returned by a pgFrom* function
Returns: A handle to the new bitmap object created in the PicoGUI server See also: pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext, pgCreateBitmap

pghandle pgNewCursor | ( | void |  | ) |

| Create a cursor that can be used for input filters. Returns: A handle to the cursor See also: pgInFilterSend

pghandle pgNewFont | ( | const char * | name,
|  | s16 | size,
|  | u32 | style
| ) |

  | Create a new font object. Parameters:
  name | The name of the font to search for, or NULL
  size | The size (height in pixels) of the font to search for, or zero
  style | Zero or more PG_FSTYLE_* flags or'ed together
Returns: A handle to the new font object created in the PicoGUI server Based on the supplied parameters, finds the closest installed font and creates an object describing it. For example:
    fDefault = pgNewFont(NULL,0,PG_FSTYLE_DEFAULT);                  // Find the font marked as default
    fBold    = pgNewFont(NULL,0,PG_FSTYLE_DEFAULT | PG_FSTYLE_BOLD); // Bold version of the default font
    fBig     = pgNewFont(NULL,40,PG_FSTYLE_ITALIC);                  // A large italic font
    fFlush   = pgNewFont("Helvetica",0,PG_FSTYLE_FLUSH);             // Helvetica at the default size, with no space at the edges
See also: pgNewString, pgDelete, pgEnterContext, pgLeaveContext, pgGetFontStyle

pghandle pgNewInFilter | ( | pghandle | insert_after,
|  | u32 | accept_trigs,
|  | u32 | absorb_trigs
| ) |

  | Create a new client-side input filter. Parameters:
  insert_after | This is the handle of the input filter to insert the new one after, or 0 to make this the first
  accept_trigs | Mask of PG_TRIGGER_* constants for triggers to send in a PG_NWE_INFILTER event
  absorb_trigs | Specifies a mask of triggers to prevent from automatically passing on to the next filter
Returns: A handle to the new input filter See also: pgNewCursor, pgInFilterSend

pghandle pgNewPopup | ( | int | width,
|  | int | height
| ) |

| Create a popup box, centered on the screen. Returns: A handle to the popup box root widget `width` and/or `height` can be PGDEFAULT (zero) to determine the size automatically. This is preferred because the app should assume as little as possible about physical screen coordinates. NOTE: This function is now just a shortcut for creating a popup widget and setting its PG_WP_ABSOLUTEX, PG_WP_ABSOLUTEY, PG_WP_WIDTH, and PG_WP_HEIGHT properties See also: pgNewPopupAt

pghandle pgNewPopupAt | ( | int | x,
|  | int | y,
|  | int | width,
|  | int | height
| ) |

| Create a popup box at the specified position. Returns: A handle to the popup box root widget `width` and/or `height` can be PGDEFAULT (zero) to determine the size automatically. This is preferred because the app should assume as little as possible about physical screen coordinates. `x` and/or `y` can be a PG_POPUP_* constant: PG_POPUP_CENTER: Centered on the screen, same behavior as pgNewPopup PG_POPUP_ATCURSOR: At the pointing device's cursor. If the cursor is over a button or menuitem, the popup snaps to its edge automatically NOTE: This function is now just a shortcut for creating a popup widget and setting its PG_WP_ABSOLUTEX, PG_WP_ABSOLUTEY, PG_WP_WIDTH, and PG_WP_HEIGHT properties See also: pgNewPopup

pghandle pgNewString | ( | const char * | str | ) |

  | Create a new string object. Parameters:
  str | The string make an object with
Returns: A handle to the new string object created in the PicoGUI server See also: pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext

pghandle pgNewWidget | ( | s16 | type,
|  | s16 | rship,
|  | pghandle | parent
| ) |

  | Create a new widget, derived from a parent widget. Parameters:
  type | A PG_WIDGET_* constant for the widget type
  rship | A PG_DERIVE_* constant indicating the new widget's relationship to it's parent. It can be PGDEFAULT.
  parent | The parent widget's handle, or PGDEFAULT.
Returns: A handlet to the new widget `rship` indicates where in the widget stacking order, relative to the parent, the new widget will be: PG_DERIVE_INSIDE: For container widgets, put the new widget inside the parent but before other widgets that may already be inside it. PG_DERIVE_BEFORE: Before the parent widget in the stacking order PG_DERIVE_AFTER: After the parent widget in the stacking order See also: pgSetWidget

pghandle pgRegisterApp | ( | s16 | type,
|  | const char * | name,
|  | ... |
| ) |

| Register a new application. < Send PG_NWE_PNTR_RAW from the specified widget

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 pgRender | ( | pghandle | bitmap,
|  | s16 | groptype,
|  | ... |
| ) |

  | Render a gropnode to a bitmap. Parameters:
  bitmap | A bitmap handle to render to. Alternatively, if the app has registered exclusive display access this can be zero to draw directly to the display.
  groptype | A PG_GROP_* constant indicating the type of gropnode
Gropnode parameters follow the gropnode type. See also: pgWriteCmd, pgNewBitmapContext, pgRegisterOwner

void pgReplaceText | ( | pghandle | widget,
|  | const char * | str
| ) |

  | Change a widget's text. Parameters:
  widget | A pointer to a widget with the PG_WP_TEXT property
  str | The string to set PG_WP_TEXT to
This function performs the following steps: Calls pgGetWidget to find the old text handle Uses pgNewString to get a handle to the new text Uses pgSetWidget to send the new handle to the widget If the old handle was non-NULL, deletes it with pgDelete It is the preferred way of setting or changing the text of a button, label, or other widget that takes a PG_WP_TEXT property. See also: pgGetWidget, pgNewString, pgSetWidget, pgDelete

void pgReplaceTextFmt | ( | pghandle | widget,
|  | const char * | fmt,
|  | ... |
| ) |

| Change a widget's text, with formatting. This function is equivalent to pgReplaceText, with support for printf-style formatting See also: pgReplaceText

void pgSetContext | ( | int | id | ) |

| Set the context ID used when creating new handles. See also: pgDeleteHandleContext, pgEnterContext, pgLeaveContext, pgGetContext

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 pgSetPayload | ( | pghandle | object,
|  | u32 | payload
| ) |

  | Set an object's payload. Parameters:
  object | A handle to any PicoGUI object
  payload | A 32-bit piece of application-defined data
The "payload" is a client-defined chunk of data attatched to any object that has a handle. Some good uses for this are assigning numerical values to buttons, or even creating a linked list of objects by storing a handle in the payload. It is usually possible for the client to store pointers in the payload, but this is not recommended, for two reasons: If the pgserver is buggy or compromised, the client is vulnerable to crashes or data corruption If the client-side architecture uses pointers of more than 32 bits, it will not work See also: pgGetPayload, pgGetEvent

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 pgSetWidget | ( | pghandle | widget,
|  | ... |
| ) |

  | Set widget properties. Parameters:
  widget | Widget handle, may be PGDEFAULT
After `widget,` pgSetWidget accepts a list of property-value pairs terminated by a zero. For example:
    pgSetWidget(wLabel,
                PG_WP_TEXT,pgNewString("Hello"),
                PG_WP_FONT,pgNewFont("Helvetica",12,0),
                0);
See also: pgNewWidget, pgGetWidget, pgNewString, pgNewFont

void pgSizeBitmap | ( | int * | w,
|  | int * | h,
|  | pghandle | bitmap
| ) |

  | Return the size of a bitmap object. Parameters:
  w | The address to return the width in
  h | The address to return the height in
  bitmap | Handle to a valid PicoGUI bitmap object
See also: pgCreateBitmap, pgNewBitmap

void pgSizeText | ( | int * | w,
|  | int * | h,
|  | pghandle | font,
|  | pghandle | text
| ) |

  | Measure a string of text. Parameters:
  w | The address to return the width in
  h | The address to return the height in
  font | A font to render the text in
  text | A handle to the text to measure
In `*w` and `*h,` returns the size in pixels of the given text in the given font. Font may be PGDEFAULT to use the default font. Note that if you use pgNewText to create a string object just for this function call, you should delete it afterwards to prevent a memory leak:
    pghandle sText;
    int w,h;

    sText = pgNewString("Hello, World!");
    pgSizeText(&w,&h,PGDEFAULT,sText);
    pgDelete(sText);
Alternatively, defining a context with pgEnterContext and pgLeaveContext will clean up the string object automatically:
    pgEnterContext();
    pgSizeText(&w,&h,PGDEFAULT,pgNewString("Hello, World!");
    pgLeaveContext();
See also: pgEnterContext, pgLeaveContext, pgNewString, pgNewFont

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.

u32 pgThemeLookup | ( | s16 | object,
|  | s16 | property
| ) |

  | Retrieve a theme property. Parameters:
  object | A PGTH_O_* theme object constant
  property | A PGTH_P_* theme property constant
Returns: The theme property's value See also: pgLoadTheme

pghandle pgTraverseWidget | ( | pghandle | widget,
|  | int | direction,
|  | int | count
| ) |

  | Finds a widget in relation to another widget. Parameters:
  widget | The widget being referenced
  direction | A direction to traverse specified with a PG_TRAVERSE_* constant
  count | The number of steps to take in that direction
There are four possible values for `direction` at this time: PG_TRAVERSE_CHILDREN returns the count'th child of the specified widget PG_TRAVERSE_FORWARD returns the widget added count'th widgets after this widget PG_TRAVERSE_BACKWARD the opposite of forward PG_TRAVERSE_CONTAINER travels to the widget's container, for `count` iterations PG_TRAVERSE_APP travels to the root widget that contains the specified widget, then forward in the application list for `count` iterations. If the `widget` is 0, it returns the first app root widget. Note that the app list is continuously sorted by "Z-order".

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

void pgWriteCmd | ( | pghandle | widget,
|  | s32 | command,
|  | s16 | numparams,
|  | ... |
| ) |

  | Write a command to a widget. Parameters:
  widget | The handle of the widget to receive the command
  command | A widget-defined command number
  numparams | The number of parameters following this one
This function creates a pgcommand structure from it's arguments and uses pgWriteData to send it to the specified widget. Currently this is used as the low-level interface to the canvas widget. See also: pgWriteData, PG_WIDGET_CANVAS, pgNewCanvasContext

void pgWriteData | ( | pghandle | widget,
|  | struct pgmemdata | data
| ) |

  | Write data to a widget. Parameters:
  widget | The handle of the widget to receive data
  data | A pgmemdata structure containing the data, as returned by a pgFrom* function
Write a chunk of widget-defined data to a widget. For example, this can be used to send text to a terminal widget or commands to a canvas widget. (For canvas drawing pgWriteCmd or PGFX should usually be used instead) See also: pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, PG_WIDGET_TERMINAL, PG_WIDGET_CANVAS, pgWriteCmd, pgNewCanvasContext