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

Generated on Fri May 23 03:39:45 2003 for PicoGUI by doxygen1.3-rc3