eventsbridge.h File Reference

#include "stdint.h"
#include "ship/events/EventTypes.h"
#include "ship/Api.h"
#include <memory>

Include dependency graph for eventsbridge.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
namespace	Ship
	Core namespace for the libultraship engine framework.

Functions
void	EventSystemSetEvents (std::shared_ptr< Ship::Events > events)
	Sets the global Events instance used by the C bridge.
std::shared_ptr< Ship::Events >	EventSystemGetEvents ()
	Returns the current bridged Events component, if any.
API_EXPORT EventID	EventSystemRegisterEvent (const char *name)
	Registers a new internally managed event type under the given name.
API_EXPORT ListenerID	EventSystemRegisterListener (EventID id, EventCallback callback, EventPriority priority, const char *file, int line)
	Registers a listener callback for the given event.
API_EXPORT void	EventSystemUnregisterEvent (EventID id)
	Removes an event and all listeners registered to it.
API_EXPORT void	EventSystemUnregisterListener (EventID ev, ListenerID id)
	Removes a previously registered listener.
API_EXPORT void	EventSystemCallEvent (EventID id, void *event, const char *file, int line, const char *key)
	Fires an event synchronously.

Function Documentation

EventSystemCallEvent()

API_EXPORT void EventSystemCallEvent	(	EventID	id,
		void *	event,
		const char *	file,
		int	line,
		const char *	key
	)

Fires an event synchronously.

Internally this forwards to Ship::Events::CallEvent(), which pushes a dispatch context and executes matching listeners by calling Events->Tick(id).

Parameters

id	Event to fire.
event	Pointer to event-specific data passed to each listener callback.
file	Source file of the caller (use the __FILE__ macro).
line	Source line of the caller (use the __LINE__ macro).
key	Optional de-duplication key; pass nullptr for unconditional dispatch.

EventSystemGetEvents()

std::shared_ptr< Ship::Events > EventSystemGetEvents

(

)

Returns the current bridged Events component, if any.

EventSystemRegisterEvent()

API_EXPORT EventID EventSystemRegisterEvent

(

const char *

name

)

Registers a new internally managed event type under the given name.

Returned IDs are negative values less than -1. User-defined event IDs are represented by 0 and positive values and do not need to be allocated here.

Parameters

name	Human-readable event name (e.g. "OnLoadGame").

Returns

Negative EventID that can be passed to listener registration and dispatch.

EventSystemRegisterListener()

API_EXPORT ListenerID EventSystemRegisterListener	(	EventID	id,
		EventCallback	callback,
		EventPriority	priority,
		const char *	file,
		int	line
	)

Registers a listener callback for the given event.

Negative IDs must already be registered through EventSystemRegisterEvent(). Zero and positive IDs are treated as user-defined IDs and are created lazily.

Parameters

id	Event to listen to.
callback	Function invoked when the event fires.
priority	Relative priority; higher-priority listeners are called first.
file	Source file of the caller (use the __FILE__ macro).
line	Source line of the caller (use the __LINE__ macro).

Returns

ListenerID that can be passed to EventSystemUnregisterListener().

EventSystemSetEvents()

void EventSystemSetEvents

(

std::shared_ptr< Ship::Events >

events

)

Sets the global Events instance used by the C bridge.

Parameters

events

Shared Events component to forward bridge calls to.

EventSystemUnregisterEvent()

API_EXPORT void EventSystemUnregisterEvent

(

EventID

id

)

Removes an event and all listeners registered to it.

Parameters

id	Event to remove.

EventSystemUnregisterListener()

API_EXPORT void EventSystemUnregisterListener	(	EventID	ev,
		ListenerID	id
	)

Removes a previously registered listener.

Removing the listener also removes its backing ListenerAction from the Events component's action list.

Parameters

ev	Event the listener was registered for.
id	ListenerID returned by EventSystemRegisterListener().