---

Program Flow
[Core PicoGUI API]

Functions
void	pgEventLoop (void)
	Event processing and dispatching loop.
void	pgExitEventLoop (void)
	Exit the current event loop.
pgEvent *	pgGetEvent (void)
	Wait for a single event.
int	pgCheckEvent (void)
	Check the number of pending events.
void	pgDispatchEvent (struct pgEvent *evt)
	Dispatch an event to registered handlers.
void	pgEventPoll (void)
	Get and dispatch new events if there are any.
int	pgEnterContext (void)
	Enter a new context.
void	pgLeaveContext (void)
	Leave a context.
void	pgDeleteHandleContext (int id)
	Delete all handles in one context.
void	pgSetContext (int id)
	Set the context ID used when creating new handles.
int	pgGetContext (void)
	Get the current context ID.

---

Detailed Description

Event loops and handle contexts

---

Function Documentation

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

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 pgDispatchEvent (  struct pgEvent *    evt )

Dispatch an event to registered handlers. Parameters: 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. See also: pgGetEvent, pgCheckEvent, pgEventLoop

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

void pgEventLoop (  void    )

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. See also: pgGetEvent, pgExitEventLoop, pgBind, pgSetIdle

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

void pgExitEventLoop (  void    )

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 See also: pgEventLoop

int pgGetContext (  void    )

Get the current context ID. See also: pgDeleteHandleContext, pgEnterContext, pgLeaveContext, pgSetContext

struct pgEvent* pgGetEvent (  void    )

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: struct pgEvent evt; evt = *pgGetEvent(); 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: i = pgGetPayload( pgGetEvent()->from ); See also: pgEventLoop, pgBind, pgSetIdle, pgSetPayload, pgGetPayload, pgCheckEvent

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

void pgSetContext (  int    id )

Set the context ID used when creating new handles. See also: pgDeleteHandleContext, pgEnterContext, pgLeaveContext, pgGetContext

---