client_c.h

The major functionality added in this release includes: - Rootless mode in X11 - Widget Templt

 * There are four possible values for \p 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 \p count iterations
 *  - PG_TRAVERSE_APP travels to the root widget that contains the specified widget, then forward in the application list for \p count iterations. If the \p widget is 0, it returns the first app root widget. Note that the app list is continuously sorted by "Z-order".
 *
 */
pghandle pgTraverseWidget(pghandle widget, int direction, int count);

/*!
 * \brief Create a popup box, centered on the screen
 * \returns A handle to the popup box root widget
 *
 * \p width and/or \p 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
 *
 * \sa pgNewPopupAt
 */
pghandle pgNewPopup(int width,int height);

/*!
 * \brief Create a cursor that can be used for input filters
 * \returns A handle to the cursor
 *
 * \sa pgInFilterSend
 */
pghandle pgNewCursor(void);

/*!
 * \brief Create a new client-side input filter
 *
 * \param insert_after This is the handle of the input filter to insert the new one after, or 0 to make this the first
 * \param accept_trigs Mask of PG_TRIGGER_* constants for triggers to send in a PG_NWE_INFILTER event
 * \param 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
 *
 * \sa pgNewCursor, pgInFilterSend
 */
pghandle pgNewInFilter(pghandle insert_after, u32 accept_trigs, u32 absorb_trigs);

/*!
 * \brief Send an event back from a client-side input filter
 *
 * \param trig Client-side trigger union, representing the event
 *
 * \sa pgNewCursor, pgNewInFilter
 */
void pgInFilterSend(union pg_client_trigger *trig);

/*!
 * \brief Create a popup box at the specified position
 * \returns A handle to the popup box root widget
 *
 * \p width and/or \p 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.
 *
 * \p x and/or \p 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
 *
 * \sa pgNewPopup
 */
pghandle pgNewPopupAt(int x,int y,int width,int height);

/*!
 * \brief Set widget properties
 * 
 * \param widget Widget handle, may be PGDEFAULT
 * 
 * After \p widget, pgSetWidget accepts a list of property-value pairs terminated by a zero.
 * For example:
 * 
 * \code
pgSetWidget(wLabel,
            PG_WP_TEXT,pgNewString("Hello"),
            PG_WP_FONT,pgNewFont("Helvetica",12,0),
            0);
 * \endcode
 * 
 * \sa pgNewWidget, pgGetWidget, pgNewString, pgNewFont
 */
void pgSetWidget(pghandle widget, ...);

/*!
 * \brief Get a widget property
 * 
 * \param widget Widget handle
 * \param property A widget property (PG_WP_* constant)
 * 
 * \returns The value associated with the specified property
 *
 * \sa pgSetWidget, pgNewWidget
 */
s32 pgGetWidget(pghandle widget,s16 property);

/*!
 * \brief Create a new bitmap object from existing data
 * 
 * \param obj A pgmemdata structure, as returned by a pgFrom* function
 * \returns A handle to the new bitmap object created in the PicoGUI server
 * 
 * \sa pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext, pgCreateBitmap
 */
pghandle pgNewBitmap(struct pgmemdata obj);

/*!
 * \brief Create a new bitmap object
 *
 * \param width Width, in pixels, of the new bitmap
 * \param height Height, in pixels, of the new bitmap
 * \returns A handle to the new bitmap object. It's contents are undefined
 *
 * \sa pgNewBitmap
 */
pghandle pgCreateBitmap(s16 width, s16 height);

/*!
 * \brief Map a bitmap into a shared memory segment
 *
 * \param 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.
 *
 * \sa pgNewBitmap, pgCreateBitmap
 */
struct pgshmbitmap *pgMakeSHMBitmap(pghandle bitmap);

/*!
 * \brief Create a new string object 
 *
 * \param str The string make an object with
 * \returns A handle to the new string object created in the PicoGUI server
 *
 * \sa pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext
 */
pghandle pgNewString(const char *str);

/*!
 * \brief Create a new array object  
 * 
 * \param dat The data to put in the array 
 * \param size Number of entries in the array 
 * \returns A handle to the new array object 
 * 
 */  
pghandle pgNewArray(const s32* dat, u16 size);  
 
/*!
 * \brief Get the contents of a string handle
 *
 * \param 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.
 * 
 * \sa pgNewString
 */
char *pgGetString(pghandle string);

/*! 
 * \brief Change a widget's text
 * 
 * \param widget A pointer to a widget with the PG_WP_TEXT property
 * \param 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.
 * 
 * \sa pgGetWidget, pgNewString, pgSetWidget, pgDelete
 */
void pgReplaceText(pghandle widget,const char *str);

/*!
 * \brief Change a widget's text, with formatting
 *
 * This function is equivalent to pgReplaceText, with support for printf-style formatting
 *
 * \sa pgReplaceText 
 */
void pgReplaceTextFmt(pghandle widget,const char *fmt, ...);

/*!
 * \brief Create a new font object
 * 
 * \param name The name of the font to search for, or NULL
 * \param size The size (height in pixels) of the font to search for, or zero
 * \param 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:
 * \code
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
 * \endcode
 * 
 * \sa pgNewString, pgDelete, pgEnterContext, pgLeaveContext, pgGetFontStyle
 */
pghandle pgNewFont(const char *name,s16 size,u32 style);

/*!
 * \brief Get information about a font style
 *
 * \param index A zero-based index to select a font style in the order that
 *              the were compiled or loaded into pgserver
 * \param name  Pointer to a buffer to store the font name in. Must be
 *              40 bytes long
 * \param size  Pointer that the font size is returned in. For bitmapped
 *              fonts (all PicoGUI currently supports) this is height in
 *              pixels
 * \param fontrep Pointer that the font representation is returned in. This
 *                is a combination of one or more PG_FR_* flags.
 * \param 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:
 * \code
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);
}
 * \endcode
 *
 * \sa pgNewFont
 */
int pgGetFontStyle(s16 index, char *name, u16 *size,
		   u16 *fontrep, u32 *flags);

/*!
 * \brief Measure a string of text
 * 
 * \param w The address to return the width in
 * \param h The address to return the height in
 * \param font A font to render the text in
 * \param text A handle to the text to measure
 * 
 * In \p *w and \p *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:
 * \code
pghandle sText;
int w,h;

sText = pgNewString("Hello, World!");
pgSizeText(&w,&h,PGDEFAULT,sText);
pgDelete(sText);
 * \endcode
 * 
 * Alternatively, defining a context with pgEnterContext and pgLeaveContext
 * will clean up the string object automatically:
 * \code
pgEnterContext();
pgSizeText(&w,&h,PGDEFAULT,pgNewString("Hello, World!");
pgLeaveContext();
 * \endcode
 * 
 * \sa pgEnterContext, pgLeaveContext, pgNewString, pgNewFont
 */
void pgSizeText(int *w,int *h,pghandle font,pghandle text);

/*!
 * \brief Return the size of a bitmap object
 *
 * \param w The address to return the width in
 * \param h The address to return the height in
 * \param bitmap Handle to a valid PicoGUI bitmap object
 *
 * \sa pgCreateBitmap, pgNewBitmap
 */
void pgSizeBitmap(int *w, int *h, pghandle bitmap);

/*!
 * \brief Load a compiled theme
 * 
 * \param 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 \p themec utility. The theme
 * can be unloaded by calling pgDelete with the returned theme handle.
 * 
 * \sa pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext
 */
pghandle pgLoadTheme(struct pgmemdata obj);

/*!
 * \brief Load a compiled Widget Template
 * 
 * \param 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().
 * 
 * \sa pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgDup
 */
pghandle pgLoadWidgetTemplate(struct pgmemdata obj);

/*!
 * \brief Find a theme object's ID given its name
 * 
 * \param 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 \p 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 \p name property.
 *
 * \sa pgLoadTheme, pgFindWidget
 */
int pgFindThemeObject(const char *key);

/*!
 * \brief Load memory into a string handle
 * 
 * \param 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.
 * 
 * \sa pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, pgDelete, pgEnterContext, pgLeaveContext
 */
pghandle pgDataString(struct pgmemdata obj);

/*!
 * \brief Retrieve a theme property
 *
 * \param object A PGTH_O_* theme object constant
 * \param property A PGTH_P_* theme property constant
 *
 * \returns The theme property's value
 *
 * \sa pgLoadTheme
 */