libui/doc/events.md

Event Handling

Overview

Reference

uiEvent

typedef struct uiEvent uiEvent;

uiEvent is an opaque type that describes an event.

uiEventHandler

typedef void (*uiEventHandler)(void *sender, void *args, void *data);

uiEventHandler is the type of a pointer to an event handler function registered with uiEventAddHandler().

uiEventOptions

typedef struct uiEventOptions uiEventOptions;
struct uiEventOptions {
	// TODO size
	bool Global;
};

uiEventOptions describes the properties of a uiEvent; you pass these to uiNewEvent().

If Global is true, the event is "global" — there are no specific senders, and all registered handler functions are called when the event is fired. Otherwise, the event has specific senders, and only handlers registered with the sender that is currently firing the event will be called.

uiNewEvent()

uiEvent *uiNewEvent(uiEventOptions *options);

uiNewEvent() creates a new uiEvent.

uiEventAddHandler()

int uiEventAddHandler(uiEvent *e, uiEventHandler handler, void *sender, void *data);

uiEventAddHandler() adds a handler to an event. When the event is fired, handler is called with data as its last parameter.

For a global event handler, sender must be NULL. For a non-global event handler, sender must be a non-NULL object that may fire the given event, and the handler will only be called if sender actually does fire the event.

The return value is an identifier that may be used to delete or block the event. This identifier is not passed directly to the handler function; if you would like the handler function to know the identifier, store it somewhere in data.

Note that event handlers are NOT deduplicated; if you call uiEventAddHandler() twice with the same handler, then handler will be registered twice and will thus be called twice, even if sender and/or data are the same, and uiEventAddHandler() will return two distinct identifiers.

uiEventDeleteHandler()

void uiEventDeleteHandler(uiEvent *e, int which);

uiEventFire()

void uiEventFire(uiEvent *e, void *sender, void *args);

uiEventFire() fires the given event, calling associated handlers sequentially and returning only when the last handler returns. If no associated handlers are registered, uiEventFire() does nothing.

If the event is a global event, sender must be NULL, and all registered handlers will be called. Otherwise, sender must be non-NULL, and only handlers that were registered with uiEventAddHandler() with the same sender will be called. Any handlers that are blocked by a call to uiEventSetHandlerBlocked() will not be called.

Each handler that is to be called will receive whatever you pass in as args to its respective args argument; this allows args to be used to send information about the current firing of the event to the handlers. This argument can be NULL if no such information is available.

Note that the order that handler functions are called in is unspecified.

uiEventHandlerBlocked()

bool uiEventHandlerBlocked(uiEvent *e, int which);

uiEventHandlerBlocked() returns whether or not the given registered event handler is blocked. A blocked event handler will not be called by uiEventFire(), even if that handler matches the parameters passed to uiEventFire(). which should be the identifier of a previously registered event handler as returned by uiEventAddHandler().

uiEventSetHandlerBlocked()

void uiEventSetHandlerBlocked(uiEvent *e, int which, bool blocked);

uiEventSetHandlerBlocked() changes whether or not the given registered event handler is bocked. which should be the identifier of a previously registered event handler as returned by uiEventAddHandler().

The effect of calling this function on a handler that matches a currently active uiEventFire() is unspecified.