client_c.h

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

u32 pgThemeLookup(s16 object, s16 property);

/*! 
 * \brief Set an object's payload
 * 
 * \param object A handle to any PicoGUI object
 * \param 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
 * 
 * \sa pgGetPayload, pgGetEvent
 */
void pgSetPayload(pghandle object,u32 payload);

/*!
 * \brief Get an object's payload
 * 
 * \param 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.
 * 
 * \sa pgSetPayload
 */
u32 pgGetPayload(pghandle object);

/*!
 * \brief Write data to a widget
 *
 * \param widget The handle of the widget to receive data
 * \param 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)
 * 
 * \sa pgFromMemory, pgFromFile, pgFromStream, pgFromTempMemory, PG_WIDGET_TERMINAL, PG_WIDGET_CANVAS, pgWriteCmd, pgNewCanvasContext
 */
void pgWriteData(pghandle widget,struct pgmemdata data);

/*!
 * \brief Write a command to a widget
 *
 * \param widget The handle of the widget to receive the command
 * \param command A widget-defined command number
 * \param 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.
 * 
 * \sa pgWriteData, PG_WIDGET_CANVAS, pgNewCanvasContext
 */
void pgWriteCmd(pghandle widget,s16 command,s16 numparams, ...);

/*!
 * \brief Render a gropnode to a bitmap
 *
 * \param 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.
 * \param groptype A PG_GROP_* constant indicating the type of gropnode
 *
 * Gropnode parameters follow the gropnode type.
 *
 * \sa pgWriteCmd, pgNewBitmapContext, pgRegisterOwner
 */
void pgRender(pghandle bitmap,s16 groptype, ...);

/*!
 * \brief Search for a widget by its PG_WP_NAME property
 *
 * \param key The name to search for
 * \return 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.
 *
 * \sa PG_WP_NAME, pgSetWidget
 */
pghandle pgFindWidget(const char *key);

//! \}

/******************** Data loading */

/*!
 * \defgroup dataload Data Loading functions
 *
 * The pgFrom*() functions specify various ways to reference data using
 * the pgmemdata structure.
 *
 * \{
 */

/*!
 * \brief Refer to data loaded into memory
 * 
 * \param data A pointer to data loaded into memory
 * \param 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
 * 
 * \sa pgFromFile, pgFromStream, pgFromTempMemory
 */
struct pgmemdata pgFromMemory(void *data,u32 length);

/*!
 * \brief Refer to data loaded into memory, free when done
 * 
 * \param data A pointer to data loaded into memory
 * \param 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, \p data will be freed with the free() function.
 * 
 * \sa pgFromMemory, pgFromFile, pgFromStream
 */
struct pgmemdata pgFromTempMemory(void *data,u32 length);


/*!
 * \brief Refer to data in a file
 * 
 * \param 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
 * 
 * \sa pgFromMemory, pgFromTempMemory, pgFromStream
 */
struct pgmemdata pgFromFile(const char *file);

/*!
 * \brief Refer to data in an opened stream
 * 
 * \param f C stream, as returned by \p fopen() in \p stdio.h
 * \param 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 \p length bytes past it.
 * The stream's position is advanced by \p length bytes.
 * 
 * \sa pgFromMemory, pgFromTempMemory, pgFromFile
 */
struct pgmemdata pgFromStream(FILE *f, u32 length);

/* TODO: Load from resource. Allow apps to package necessary bitmaps
   and things in a file, named after their binary but with a '.res'
   extension.
   The server will also be able to request reloading data from these
   resource files, for example to reload bitmaps when the bit depth
   changes.

   This is just an idea, and I'll implement it later...
   This whole pgmemdata business is just my attempt to leave enough
   hooks to make this work.
*/

//! \}

/******************** Program flow */

/*!
 * \defgroup progflow Program Flow
 *
 * Event loops and handle contexts
 *
 * \{
 */

/*!
 * \brief Event processing and dispatching loop
 * 
 * pgEventLoop waits for events from the PicoGUI server and dispatches
 * them according to bindings set up with pgBind. The handler set with
 * pgSetIdle is also called if applicable.
 * 
 * pgEventLoop can be called more than once throughout the life of the
 * program, but it is not re-entrant.
 * 
 * If the app recieves an event while it is not waiting in an
 * EventLoop, the server will queue them until the client is
 * ready.
 * 
 * \sa pgGetEvent, pgExitEventLoop, pgBind, pgSetIdle
 */
void pgEventLoop(void);

/*!
 * \brief Exit the current event loop
 * 
 * If the client is currently inside an event loop, this function
 * sets a flag to exit it at the next possible opportunity
 * 
 * \sa pgEventLoop
 */
void pgExitEventLoop(void);

/*!
 * \brief Wait for a single event
 *
 * \returns A pgEvent structure
 * 
 * This is good for small dialog boxes, or other situations when pgBind and
 * pgEventLoop are overkill. pgGetEvent can be used while an event loop is already
 * in progress, for example in a pgSetIdle or pgBind handler function.
 *
 * You can also use this in combination with pgCheckEvent to passively check
 * for new events while performing some other operation, such as animation.
 *
 * Important! Note that the returned pointer is only valid until the next
 * PicoGUI call! It's usually a good idea to use something like this:
 *
 * \code

struct pgEvent evt;

evt = *pgGetEvent();

 * \endcode
 *
 * If the relevant values from the pgEvent structure will be copied elsewhere
 * before the next PicoGUI call, that is alright too. Thus, the following code
 * is perfectly fine:
 *
 * \code

i = pgGetPayload( pgGetEvent()->from );

 * \endcode
 * 
 * \sa pgEventLoop, pgBind, pgSetIdle, pgSetPayload, pgGetPayload, pgCheckEvent
 */
struct pgEvent *pgGetEvent(void);

/*!
 * \brief 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.
 * 
 * \sa pgGetEvent, pgEventLoop
 */
int pgCheckEvent(void);

/*!
 * \brief Dispatch an event to registered handlers
 *
 * \param evt Pointer to the event to dispatch. This should not be the same
 *            pointer returned by pgGetEvent(), as it is only valid until the
 *            next PicoGUI call! See pgGetEvent() for more information.
 *
 * This function searches all registered event handlers, and dispatches the
 * event to any applicable handlers. It also provides various default handlers,
 * such as closing the program on recieving PG_WE_CLOSE.
 *
 * \sa pgGetEvent, pgCheckEvent, pgEventLoop
 */
void pgDispatchEvent(struct pgEvent *evt);

/*!
 * \brief 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.
 *
 * \sa pgGetEvent, pgCheckEvent, pgDispatchEvent
 */
void pgEventPoll(void);

/*!
 * \brief 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:
 * \code
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
 * \endcode
 * 
 * \sa pgLeaveContext
 */
int pgEnterContext(void);

/*!
 * \brief 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.
 * 
 * \sa pgEnterContext, pgDeleteHandleContext
 */
void pgLeaveContext(void);

/*!
 * \brief 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)
 *
 * \sa pgEnterContext
 */
void pgDeleteHandleContext(int id);


/*
 * Added by kdhong..
 * Creating Device Incompatible Bitmap..
 *
 *
 */
 
struct pgdata_advbitmap* pgCreateAdvBitmap(s16 width, s16 height, s16 bpp, u32* clut, u32 clutsize );
void pgSetBitmapClut( pghandle bitmap, u32* clut, u32 clutsize );


//! \}

//! \}

#endif /* __H_PG_CLI_C */
/* The End */