---

Object Manipulation
[Core PicoGUI API]

Functions
void	pgDelete (pghandle object)
	Delete any object that has 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.
void	pgFocus (pghandle widget)
	Give a widget the keyboard focus.
pghandle	pgRegisterApp (s16 type, const char *name,...)
	Register a new application.
pghandle	pgNewWidget (s16 type, s16 rship, pghandle parent)
	Create a new widget, derived from a parent widget.
pghandle	pgCreateWidget (s16 type)
	Create a new widget without a parent.
void	pgAttachWidget (pghandle parent, s16 rship, pghandle widget)
	Attach a widget to a new parent.
pghandle	pgTraverseWidget (pghandle widget, int direction, int count)
	Finds a widget in relation to another widget.
pghandle	pgNewPopup (int width, int height)
	Create a popup box, centered on the screen.
pghandle	pgNewCursor (void)
	Create a cursor that can be used for input filters.
pghandle	pgNewInFilter (pghandle insert_after, u32 accept_trigs, u32 absorb_trigs)
	Create a new client-side input filter.
void	pgInFilterSend (union pg_client_trigger *trig)
	Send an event back from a client-side input filter.
pghandle	pgNewPopupAt (int x, int y, int width, int height)
	Create a popup box at the specified position.
void	pgSetWidget (pghandle widget,...)
	Set widget properties.
s32	pgGetWidget (pghandle widget, s16 property)
	Get a widget property.
pghandle	pgNewBitmap (struct pgmemdata obj)
	Create a new bitmap object from existing data.
pghandle	pgCreateBitmap (s16 width, s16 height)
	Create a new bitmap object.
pgshmbitmap *	pgMakeSHMBitmap (pghandle bitmap)
	Map a bitmap into a shared memory segment.
pghandle	pgNewString (const char *str)
	Create a new string object.
pghandle	pgNewArray (const s32 *dat, u16 size)
	Create a new array object.
char *	pgGetString (pghandle string)
	Get the contents of a string handle.
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.
pghandle	pgNewFont (const char *name, s16 size, u32 style)
	Create a new font object.
int	pgGetFontStyle (s16 index, char *name, u16 *size, u16 *fontrep, u32 *flags)
	Get information about a font style.
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.
pghandle	pgLoadTheme (struct pgmemdata obj)
	Load a compiled theme.
pghandle	pgLoadWidgetTemplate (struct pgmemdata obj)
	Load a compiled Widget Template.
int	pgFindThemeObject (const char *key)
	Find a theme object's ID given its name.
pghandle	pgDataString (struct pgmemdata obj)
	Load memory into a string handle.
u32	pgThemeLookup (s16 object, s16 property)
	Retrieve a theme property.
void	pgSetPayload (pghandle object, u32 payload)
	Set an object's payload.
u32	pgGetPayload (pghandle object)
	Get an object's payload.
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	pgFindWidget (const char *key)
	Search for a widget by its PG_WP_NAME property.

---

Detailed Description

Functions for creating and manipulating handles and the objects they represent. Includes Applications, Widgets, and Strings.

---

Function Documentation

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

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.

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 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.

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 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

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

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

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 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 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 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

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 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

---