NAME

AG_Event — agar event handlers / virtual functions

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

The AG_Event (or AG_Function) type represents an event handler (or more generally a virtual function) under an AG_Object(3). It provides a general-purpose, thread-safe message passing system. It is used to implement virtual functions in objects. The AG_Event structure contains an optional name identifier (a string of up to AG_EVENT_NAME_MAX characters long). Event Handlers are declared as follows:

void
MyEventHandler(AG_Event *event);

The final stack of arguments passed to MyEventHandler() contains both the arguments from the initial AG_SetEvent() call followed by any extra arguments appended by subsequent AG_PostEvent() calls. See the EVENT ARGUMENTS section for details and examples.

An AG_Event may store up to AG_EVENT_ARGS_MAX arguments. The arguments contained in an AG_Event can be accessed by the event handler either by index or by name.

EVENT PROCESSING

AG_Event *
AG_SetEvent(AG_Object *obj, const char *name, void (*fn)(AG_Event *event), const char *fmt, ...);

AG_Event *
AG_AddEvent(AG_Object *obj, const char *name, void (*fn)(AG_Event *event), const char *fmt, ...);

AG_Event *
AG_FindEventHandler(AG_Object *obj, const char *name);

void
AG_UnsetEvent(AG_Object *obj, const char *name);

void
AG_UnsetEventByPtr(AG_Object *obj, AG_Event *event);

void
AG_PostEvent(AG_Object *obj, const char *name, const char *fmt, ...);

void
AG_PostEventByPtr(AG_Object *obj, AG_Event *event, const char *fmt, ...);

int
AG_SchedEvent(AG_Object *obj, Uint32 ticks, const char *name, const char *fmt, ...);

The AG_SetEvent() function sets an event handler to service events of type name. If a handler of the given name already exists, it is replaced. The AG_AddEvent() variant preserves any pre-existing handler (such that multiple handlers will be invoked by the event). fn is a pointer to the event handler function. fmt is an optional format string which specifies following arguments (see EVENT ARGUMENTS).

AG_FindEventHandler() searches for an event handler by name and returns a pointer to its AG_Event structure on success or NULL if not found.

AG_UnsetEvent() and AG_UnsetEventByPtr() delete the given event handler.

AG_PostEvent() raises the event identified by name under object obj. fmt is an optional format string specifying following arguments that will be passed to the event handler function. The event handler will see the arguments added by AG_SetEvent() followed by those added by AG_PostEvent().

The AG_PostEventByPtr() variant accepts a pointer to an AG_Event element as opposed to looking up the event handler by name.

AG_SchedEvent() provides an interface similar to AG_PostEvent() except that the event is scheduled to occur in the given number of ticks. AG_SchedEvent() returns 0 on success or -1 if the timer could not be created. When an AG_Object(3) is detached or destroyed, any event scheduled for execution is automatically cancelled. A more flexible interface for timers is described in AG_Timer(3) (which AG_SchedEvent() uses internally).

EVENT ARGUMENTS

The AG_SetEvent(), AG_AddEvent() and AG_PostEvent() routines accept a special fnArgs format string specifying a list of arguments to be passed to the event handler function. For example, "%s,%p,%i" (or "%s%p%i") says that the following arguments are a string, a pointer and an integer. An event handler routine will typically use accessor macros to extract argument values out of the event structure:

void
MyEventHandler(AG_Event *event)
{
	char *s = AG_STRING(1);
	void *p = AG_PTR(2);
	int i   = AG_INT(3);

	/* ... */
}

It is customary for Agar object classes to define accessor macros AG_<T>_PTR() (for accessing arguments by index), AG_<T>_NAMED() (for accessing arguments by name), and AG_<T>_SELF() (for accessing argument 0, equivalent to "AG_<T>_PTR(0)"). Arguments marked constant must be accessed with AG_c<T>_PTR() and AG_c<T>_SELF().

Here is an example using Agar-GUI widget classes:

static void
PushedOK(AG_Event *event)
{
	AG_Button *button = AG_BUTTON_SELF();
	AG_Radio *radio   = AG_RADIO_PTR(1);
	AG_Button *button = AG_BUTTON_PTR(2);
	const AG_Checkbox *cb = AG_cCHECKBOX_PTR(3);

/* 	cb->invert = 1;              <- Incorrect (cb is const) */
/*	AG_WidgetDisable(cb);        <- Incorrect (cb is const) */
	AG_WidgetDisable(radio);  /* <- OK */
	AG_WidgetDisable(button); /* <- OK */
}

AG_Window *win = AG_WindowNew(0);
AG_Checkbox *radio = AG_RadioNew(window, 0, NULL);
AG_Button *button = AG_ButtonNew(window, 0, "OK");
AG_Checkbox *checkbox = AG_CheckboxNew(window, 0, "Some option");

AG_SetEvent(button, "button-pushed",
    PushedOK, "%p,%Cp", radio, checkbox);

Arguments are optionally named (tagged with a string) and retrieved with AG_<TYPE>_NAMED():

static void
CopySomeData(AG_Event *event)
{
	const void *src = AG_cPTR_NAMED("src");
	void *dst = AG_PTR_NAMED("dst");
	long offs = AG_LONG_NAMED("offs");

	/* ... */
}

void *src, *dst;
long offs = 0;

AG_SetEvent(obj, "some-event",
    CopySomeData, "%Cp(src),%p(dst),%li(offs)",
    src, dst, offs);

The following argument specifiers are accepted:

%p: A pointer to data: void *.
%Cp: A pointer to const data: const void *.
%i: Signed integer: int.
%u: Unsigned integer: Uint.
%li: Signed long integer: long. Not in AG_SMALL.
%lu: Unsigned long integer: Ulong. Not in AG_SMALL.
%f: Real number: float. Requires AG_HAVE_FLOAT.
%d: Real number: double. Requires AG_HAVE_FLOAT.
%s: C string (NUL-terminated): char *.

The following macros extract the arguments contained in an AG_Event structure. If Agar is compiled with either --enable-debug or --enable-type-safety, they also check for potential accesses to incorrect types.

AG_Object *
AG_SELF(void);

const AG_Object *
AG_cSELF(void);

void *
AG_PTR(int index);

const void *
AG_cPTR(int index);

AG_Object *
AG_OBJECT(int index, const char *hierarchy);

const AG_Object *
AG_cOBJECT(int index, const char *hierarchy);

char *
AG_STRING(int index);

int
AG_INT(int index);

Uint
AG_UINT(int index);

long
AG_LONG(int index);

Ulong
AG_ULONG(int index);

float
AG_FLOAT(int index);

double
AG_DOUBLE(int index);

void *
AG_PTR_NAMED(const char *key);

const void *
AG_cPTR_NAMED(const char *key);

AG_Object *
AG_OBJECT_NAMED(const char *key, const char *hierarchy);

const AG_Object *
AG_cOBJECT_NAMED(const char *key, const char *hierarchy);

char *
AG_STRING_NAMED(const char *key);

int
AG_INT_NAMED(const char *key);

Uint
AG_UINT_NAMED(const char *key);

long
AG_LONG_NAMED(const char *key);

Ulong
AG_ULONG_NAMED(const char *key);

float
AG_FLOAT_NAMED(const char *key);

double
AG_DOUBLE_NAMED(const char *key);

The AG_SELF() and AG_cSELF() macros expand to a pointer to the AG_Object(3) receiving the event (the obj argument passed to AG_PostEvent()). They are equivalent to AG_PTR(0) and AG_cPTR(0), respectively.

The following macros return a specific item in the list of arguments. When retrieving arguments by index, note that the arguments to AG_PostEvent() follow the arguments to AG_SetEvent() (i.e., the arguments to AG_SetEvent() are pushed first onto the argument stack, followed by the arguments to AG_PostEvent(), if any). These macros ensure type safety if Agar is compiled with --enable-debug or --enable-type-safety.

AG_PTR() returns a pointer (a ‘%p’ argument). AG_cPTR() returns a const pointer (a ‘%Cp’ argument).

AG_OBJECT() returns a pointer to an AG_Object(3) (a ‘%p’ argument). In debug mode, assert that the argument points to a valid AG_Object(3) by performing a validity test, and a class membership test. The AG_cOBJECT() variant asserts that the pointer is a const pointer (a ‘%Cp’ argument).

AG_STRING() returns a pointer to a string (a ‘%s’ argument).

AG_INT(), AG_UINT(), AG_LONG() and AG_ULONG() return a natural or long integer (a ‘%i’, ‘%u’, ‘%li’ or ‘%lu’ argument, respectively).

AG_FLOAT() and AG_DOUBLE() return the given floating-point number (a ‘%f’ for a float or ‘%d’ for a double argument).

The AG_*_NAMED() macros retrieve the given argument by name instead of by index. If there is no argument matching the name, a fatal error is raised.

ARGUMENT MANIPULATION

In some cases it is desirable for functions to accept a list of event handler arguments like AG_SetEvent(), and possibly manipulate its entries directly. For example, the AG_MenuAction(3) function of the GUI widget AG_Menu(3) accepts a pointer to an event handler function, followed by an AG_SetEvent() style format string and a variable list of arguments. The following functions allow such manipulations.

void
AG_EventInit(AG_Event *ev);

void
AG_EventArgs(AG_Event *ev, const char *fmt, ...);

void
AG_EventCopy(AG_Event *dst, const AG_Event *src);

AG_Event *
AG_EventDup(const AG_Event *src);

void
AG_EVENT_DUMP(const AG_Event *ev);

void
AG_EventPushPointer(AG_Event *ev, const char *key, void *val);

void
AG_EventPushConstPointer(AG_Event *ev, const char *key, const void *val);

void
AG_EventPushString(AG_Event *ev, const char *key, char *val);

void
AG_EventPushInt(AG_Event *ev, const char *key, int val);

void
AG_EventPushUint(AG_Event *ev, const char *key, Uint val);

void
AG_EventPushLong(AG_Event *ev, const char *key, long val);

void
AG_EventPushUlong(AG_Event *ev, const char *key, Ulong val);

void
AG_EventPushFloat(AG_Event *ev, const char *key, float val);

void
AG_EventPushDouble(AG_Event *ev, const char *key, double val);

void
AG_EVENT_PUSH_ARG(va_list ap, char formatChar, AG_Event *ev);

void *
AG_EventPopPointer(AG_Event *ev);

const void *
AG_EventPopConstPointer(AG_Event *ev);

char *
AG_EventPopString(AG_Event *ev);

int
AG_EventPopInt(AG_Event *ev);

Uint
AG_EventPopUint(AG_Event *ev);

long
AG_EventPopLong(AG_Event *ev);

Ulong
AG_EventPopUlong(AG_Event *ev);

float
AG_EventPopFloat(AG_Event *ev);

double
AG_EventPopDouble(AG_Event *ev);

AG_EventInit() initializes an AG_Event structure with no arguments.

AG_EventArgs() initializes ev and also specifies a list of arguments (in the same format as AG_SetEvent()).

AG_EventCopy() copies the function pointer and arguments from one AG_Event to another. AG_EventDup() returns a newly-allocated duplicate.

The AG_EVENT_DUMP() macro produces a listing of the arguments of ev on the console via AG_Debug(3).

The AG_EventPush*() routines put a new argument on top of the argument stack, incrementing the argument count. AG_EventPop*() decrement the argument count, returning a copy of the data of the last element.

The AG_EVENT_PUSH_ARG() macro insert an argument on the argument stack, determining the type from formatChar and the data from the following va_arg(3) arguments. The supported formatChar characters are documented in the EVENT ARGUMENTS section.

EVENT QUEUES

Under some circumstances, it is useful to gather AG_Event objects into a simple queue. For example, a custom event loop routine (see AG_EventLoop(3)) or a low-level Agar driver (see AG_Driver(3)) may gather events from input devices and later process them.

STRUCTURE DATA

For the AG_Event structure:

char * name: String identifier for the event.
int argc: Argument count.
AG_Variable *argv: Argument data (see AG_Variable(3)).

EXAMPLES

The following code fragment demonstrates a typical AG_Event usage in the Agar-GUI library. We bind an action to the button press event, which is called ‘button-pushed’. This event is documented in the AG_Button(3) manual, and so are the arguments it appends to the list of arguments passed to the event handler (in this case, a single int).

void
SayHello(AG_Event *event)
{
	char *s   = AG_STRING(1);  /* From AG_SetEvent() */
	int state = AG_INT(2);     /* From later AG_PostEvent() */

	AG_TextMsg(AG_MSG_INFO, "Hello, %s! (state=%d)", s, state);
}

AG_Button *btn;

btn = AG_ButtonNew(NULL, 0, "Say hello");
AG_SetEvent(btn, "button-pushed", SayHello, "%s", "World");

The AG_Button API provides a shorthand constructor routine, AG_ButtonNewFn(), which accepts the ‘button-pushed’ event handler as argument:

AG_ButtonNewFn(NULL, 0, "Say hello", SayHello, "%s", "World");

The following code fragment is equivalent:

AG_Button *btn;
AG_Event *ev;

btn = AG_ButtonNew(NULL, 0, "Say hello");
ev = AG_SetEvent(btn, "button-pushed", SayHello, NULL);
AG_EventPushString(ev, NULL, "World");

The following code fragment invokes a handler routine artificially:

void
SayHello(AG_Event *event)
{
	char *s = AG_STRING(1);
	int   i = AG_INT(2);
}

AG_Event ev;

AG_EventArgs(&ev, "%s,%d", "Foo string", 1234);
SayHello(&ev);

HISTORY

The AG_Event mechanism first appeared in Agar 1.0. The AG_Variable(3) structure was first used to represent event handler arguments in Agar 1.3.4. Agar 1.6.0 added the const argument accessor macros and introduced validity and class membership tests for object pointers in event handler arguments. AG_EventCopy(), AG_EventDup() and AG_UnsetEventByPtr() appeared in Agar 1.6.0.