client_c.h

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

void pgFlushRequests(void);

/*!
 * \brief 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.
 * 
 * \sa pgFlushRequests, pgSubUpdate
 */
void pgUpdate(void);

/*!
 * \briefUpdate 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.
 * 
 * \sa pgUpdate, pgFlushRequests
 */
void pgSubUpdate(pghandle widget);

/*!
 *
 * \brief Attatch an event handler to a widget and/or event.
 * 
 * \param widgetkey A widget to attach to, or PGBIND_ANY to respond to any widget's events
 * \param eventkey An event to attach to, or PGBIND_ANY to respond to any event by the selected widget(s).
 * \param handler A pointer to a PicoGUI event handler
 * \param extra The value to pass within the pgEvent's \p extra field
 * 
 * When the widgetkey and eventkey both match, the handler is called,
 * and the specified value for extra is passed in its pgEvent structure. The extra value passed
 * depends on the binding that triggered the call, not on the widget or event involved.
 * If widgetkey and eventkey are exactly the same as an existing binding, its
 * handler and extra value are reset to the ones specified here. If handler is
 * NULL the binding is deleted.
 * 
 * \sa pgevthandler, pgEvent
 */
void pgBind(pghandle widgetkey,s16 eventkey,
	    pgevthandler handler,void *extra);

#ifdef FD_SET
/*!
 *
 * \brief Wait on your own file descriptors
 *
 * \param handler If non-NULL, this is used instead of select() in the client library
 *
 * This function allows you to specify a handler that acts as
 * a wrapper around the client library's calls to select(), so 
 * you can wait on your own file descriptors. 
 *
 * IMPORTANT: The select() handler can not make any PicoGUI calls, because the
 * event queue is in an unknown state. The 'bottomhalf' function will be called
 * shortly after the select handler returns, and it is allowed to make
 * PicoGUI API calls.
 * 
 * To cancel this, call with a NULL handler and the select handle will be set
 * back to the standard select() system call.
 *
 * To use this function, the proper header files must be included
 * before picogui.h for select()
 * 
 * \sa pgSetIdle, pgEventLoop
 */
void pgCustomizeSelect(pgselecthandler handler, pgselectbh bottomhalf);
#endif

/*!
 * \brief Register exclusive access to a resouce
 *
 * \param 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
 *
 * \sa PG_OWN_KEYBOARD, PG_OWN_POINTER, PG_OWN_SYSEVENTS
 */
void pgRegisterOwner(int resource);

/*!
 * \brief Unregister exclusive access to a resouce
 *
 * \param 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.
 * 
 * \sa pgRegisterOwner
 */
void pgUnregisterOwner(int resource);

/*!
 * \brief Change video mode at runtime
 * 
 * \param xres New horizontal resolution
 * \param yres New vertical resolution
 * \param bpp Color depth in bits per pixel
 * \param flagmode PG_FM_* constant specifying how to combine \p flags with the current video flags
 *
 * \p xres, \p yres, and \p bpp can be zero to keep the current values. 
 * 
 * \p 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
 * 
 * \p 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.
 * 
 * \sa pgGetVideoMode
 */
void pgSetVideoMode(u16 xres,u16 yres,
		    u16 bpp,u16 flagmode,
		    u32 flags);

/*!
 * \brief 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:
 * 
 * \code
struct pgmodeinfo mi;
mi = *pgGetVideoMode();
 * \endcode
 *
 * \sa pgSetVideoMode, pgmodeinfo
 */
struct pgmodeinfo *pgGetVideoMode(void);

/*!
 * \brief Send a message to the drivers
 *
 * \param message A PGDM_* driver message constant
 * \param 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.
 */
void pgDriverMessage(u32 message, u32 param);

/*!
 * \brief Send a message to a widget owned by any application
 *
 * \param dest Handle of the destination widget
 * \param data A pgmemdata structure containing the data, as returned by a pgFrom* function
 *
 * The \p data parameter is sent as the \p data in a PG_WE_APPMSG
 * event on behalf of the \p dest widget.
 */
void pgAppMessage(pghandle dest, struct pgmemdata data);

/*! 
 * \brief Evaluate a PicoGUI request packet
 *
 * \param reqtype A PGREQ_* constant indicating the packet type
 * \param data Pointer to the raw packet data
 * \param 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.
 */
pghandle pgEvalRequest(s16 reqtype, void *data, u32 datasize);

/*!
 * \brief Set the inactivity timer
 *
 * \param 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.
 *
 * \sa pgGetInactivity
 */
void pgSetInactivity(u32 time);

/*!
 * \brief 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
 * 
 * \sa pgSetInactivity
 */
u32 pgGetInactivity(void);

/*!
 * \brief Get a server resource
 *
 * \returns The resource handle associated with the given PGRES_* constant
 */
pghandle pgGetServerRes(u32 id);

//! \}

/******************** Objects */

/*!
 * \defgroup pgobjects Object Manipulation
 *
 * Functions for creating and manipulating handles and the objects they
 * represent. Includes Applications, Widgets, and Strings.
 *
 * \{
 */

/*!
 * \brief Delete any object that has a handle 
 *
 * \param object A handle to any type of object (String, widget, bitmap, etc.)
 * 
 * This function frees the memory in the PicoGUI server associated with \p object.
 */
void pgDelete(pghandle object);

/*!
 * \brief Duplicate an object that has a handle
 *
 * \param 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.
 *
 * \sa pgDelete, pgNewString
 */
pghandle pgDup(pghandle object);

/*!
 * \brief Change the handle context of an object
 *
 * \param object A handle to any PicoGUI object
 * \param 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:
 * \code
pgEnterContext();
pgDialogBox("My Dialog");
... Allocate lots of memory ...
pgChangeContext(important_data,-1);
pgLeaveContext();
return important_data;
 * \endcode
 *
 * \sa pgEnterContext, pgLeaveContext
 */
void pgChangeContext(pghandle object, s16 delta);

//!  Give a widget the keyboard focus 
void pgFocus(pghandle widget);

/*! 
 * \brief Register a new application
 * 
 * \param type A PG_APP_* constant like PG_APP_NORMAL or PG_APP_TOOLBAR
 * \param name The application's name, displayed in it's panelbar if applicable
 * 
 * \returns A handle to the application's root widget
 * 
 * Optional specifications (PG_APPSPEC_*) are specified 
 * in name-value pairs, terminated with a 0.
 * Currently most PG_APPSPEC_* constants are unimplemented, but the application's
 * initial size and position can be set by using pgSetWidget on the application's
 * root widget.
 *
 * Example:
 * \code
pgRegisterApp(PG_APP_NORMAL,"My App",
              PG_APPSPEC_SIDE,PG_S_TOP,
              PG_APPSPEC_MINHEIGHT,50,
              0);
pgSetWidget(PGDEFAULT,
            PG_WP_SIZE,50,
            PG_WP_SIZEMODE,PG_SZMODE_PERCENT,
            0);
 * \endcode
 * 
 * \sa pgNewWidget, pgSetWidget, pgNewPopup, PG_APP_NORMAL, PG_APP_TOOLBAR
 */
pghandle pgRegisterApp(s16 type,const char *name, ...);

/*!
 * \brief Create a new widget, derived from a parent widget
 * 
 * \param type A PG_WIDGET_* constant for the widget type
 * \param rship A PG_DERIVE_* constant indicating the new widget's relationship to it's parent. It can be PGDEFAULT.
 * \param parent The parent widget's handle, or PGDEFAULT.
 * 
 * \returns A handlet to the new widget
 *
 * \p 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
 *
 * \sa pgSetWidget
 */
pghandle pgNewWidget(s16 type,s16 rship,
		     pghandle parent);

/*!
 * \brief Create a new widget without a parent
 *
 * \param 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.
 *
 * \sa pgAttachWidget, pgNewWidget
 */
pghandle pgCreateWidget(s16 type);

/*!
 * \brief Attach a widget to a new parent
 *
 * \param parent The parent widget's handle, or PGDEFAULT.
 * \param rship A PG_DERIVE_* constant indicating the new widget's relationship to it's parent. It can be PGDEFAULT.
 * \param 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.
 *
 * \sa pgCreateWidget, pgDeleteWidget
 */
void pgAttachWidget(pghandle parent, s16 rship, pghandle widget);

/*!
 * \brief Finds a widget in relation to another widget
 *
 * \param widget The widget being referenced
 * \param direction A direction to traverse specified with a PG_TRAVERSE_* constant
 * \param count The number of steps to take in that direction
 *