Event helper macros

Macros
#define	DECLARE_EVENT(eventName)   extern "C" EventID eventName##ID = -1;
	Defines and initialises (to -1) the EventID variable for an event type.
#define	STRINGIFY_DETAIL(x)   #x
#define	TOSTRING(x)   STRINGIFY_DETAIL(x)
#define	FILE_AND_LINE   __FILE__ ":" TOSTRING(__LINE__)
	Produces a "file:line" string literal at the call site.
#define	DEFINE_EVENT(eventName, ...)
	Declares a new event type and its associated EventID variable.
#define	CALL_EVENT(eventType, ...)
	Fires an event without checking for cancellation.
#define	CALL_CANCELLABLE_EVENT(eventType, ...)
	Fires an event and enters the following block only if the event was NOT cancelled.
#define	CHECK_IF_NOT_CANCELLED(eventType)   if (!eventType##_.Event.Cancelled)
	Guard condition that is true when the previously fired cancellable event was NOT cancelled.
#define	CALL_CANCELLABLE_RETURN_EVENT(eventType, ...)
	Fires an event and returns from the enclosing function if the event was cancelled.
#define	REGISTER_EVENT(eventType)   eventType##ID = EventSystemRegisterEvent(#eventType);
	Registers an event type with the global EventSystem, populating eventName##ID.
#define	REGISTER_LISTENER(eventType, priority, callback)    EventSystemRegisterListener(eventType##ID, callback, priority, __FILE__, __LINE__);
	Registers a listener callback for an event type with the given priority.
#define	UNREGISTER_LISTENER(eventType, listenerID)   EventSystemUnregisterListener(eventType##ID, listenerID);
	Unregisters a listener using the ListenerID returned by REGISTER_LISTENER.

Detailed Description

These macros provide a convenient, type-safe way to declare, register, call, and listen to events without having to reference EventIDs directly.

Declaring an event type:

DEFINE_EVENT(OnWindowResize, int32_t Width; int32_t Height;)

This expands to a struct named OnWindowResize that embeds IEvent as its first member, and an external EventID named OnWindowResizeID.

Registering and calling:

REGISTER_EVENT(OnWindowResize);
CALL_EVENT(OnWindowResize, 1920, 1080);

Macro Definition Documentation

CALL_CANCELLABLE_EVENT

#define CALL_CANCELLABLE_EVENT	(		eventType,
			...
	)

Value:

    eventType eventType##_ = { { false }, __VA_ARGS__ };                                   \
    EventSystemCallEvent(eventType##ID, &eventType##_, __FILE__, __LINE__, FILE_AND_LINE); \
    if (!eventType##_.Event.Cancelled)

Fires an event and enters the following block only if the event was NOT cancelled.

Usage:

CALL_CANCELLABLE_EVENT(MyEvent, arg1, arg2) {
    // runs only if no listener cancelled the event
}

CALL_CANCELLABLE_RETURN_EVENT

#define CALL_CANCELLABLE_RETURN_EVENT	(		eventType,
			...
	)

Value:

    eventType eventType##_ = { { false }, __VA_ARGS__ };                                   \
    EventSystemCallEvent(eventType##ID, &eventType##_, __FILE__, __LINE__, FILE_AND_LINE); \
    if (eventType##_.Event.Cancelled) {                                                    \
        return;                                                                            \
    }

Fires an event and returns from the enclosing function if the event was cancelled.

CALL_EVENT

#define CALL_EVENT	(		eventType,
			...
	)

Value:

    eventType eventType##_ = { { false }, __VA_ARGS__ }; \
    EventSystemCallEvent(eventType##ID, &eventType##_, __FILE__, __LINE__, FILE_AND_LINE);

Fires an event without checking for cancellation.

Constructs the event payload from ... and calls EventSystem::CallEvent().

CHECK_IF_NOT_CANCELLED

#define CHECK_IF_NOT_CANCELLED

(

eventType

)

if (!eventType##_.Event.Cancelled)

Guard condition that is true when the previously fired cancellable event was NOT cancelled.

Must be used after a CALL_CANCELLABLE_EVENT block if a second check is needed.

DECLARE_EVENT

#define DECLARE_EVENT

(

eventName

)

extern "C" EventID eventName##ID = -1;

Defines and initialises (to -1) the EventID variable for an event type.

DEFINE_EVENT

#define DEFINE_EVENT	(		eventName,
			...
	)

Value:

    typedef struct {                 \
        IEvent Event;                \
        __VA_ARGS__                  \
    } eventName;                     \
                                     \
    DECLARE_EVENT(eventName)

Declares a new event type and its associated EventID variable.

Parameters

eventName	The name of the event struct (and its ID, eventName##ID).
...	Additional struct fields appended after the embedded IEvent base.

Example:

DEFINE_EVENT(OnPlayerDeath, int32_t PlayerIndex;)

FILE_AND_LINE

#define FILE_AND_LINE   __FILE__ ":" TOSTRING(__LINE__)

Produces a "file:line" string literal at the call site.

REGISTER_EVENT

#define REGISTER_EVENT

(

eventType

)

eventType##ID = EventSystemRegisterEvent(#eventType);

Registers an event type with the global EventSystem, populating eventName##ID.

Must be called once at startup before any CALL_EVENT or REGISTER_LISTENER uses of the event.

REGISTER_LISTENER

#define REGISTER_LISTENER	(		eventType,
			priority,
			callback
	)		EventSystemRegisterListener(eventType##ID, callback, priority, __FILE__, __LINE__);

Registers a listener callback for an event type with the given priority.

Parameters

eventType	The event type name (its ID is eventType##ID).
priority	An EventPriority value.
callback	Function pointer or lambda matching the EventCallback signature.

STRINGIFY_DETAIL

#define STRINGIFY_DETAIL

(

x

)

#x

TOSTRING

#define TOSTRING

(

x

)

STRINGIFY_DETAIL(x)

UNREGISTER_LISTENER

#define UNREGISTER_LISTENER	(		eventType,
			listenerID
	)		EventSystemUnregisterListener(eventType##ID, listenerID);

Unregisters a listener using the ListenerID returned by REGISTER_LISTENER.

Parameters

eventType	The event type name.
listenerID	ListenerID to remove.