Dispatcher

The dispatcher is responsible for collecting emitted events and calling listeners with the respective events. We use an additional term in this documentation: addressable listener. With that we mean a listener that for one receives all the normal events but also addressable events. We support the feature to emit an event that is addressed to a specific listener.

In Obscura no particular base class is required for creating a listener. All you need is a class that implements the defined callbacks. These callbacks are defined via event definitions. In addition to defining your own events many events are pre-defined:

template<class Definition, class ...AdditionalDefinitions>
class ConfigurableDispatcher

The class provides an implementation for a dispatcher. It must be configured to be compatible with the events that are supposed to be dispatched. For that you must pass event definitions to the template parameters list. A Definition must satisfy the EventDefinition concept.

Template Parameters:

• Definition – Class that satisfies EventDefinition concept

• AdditionalDefinitions – Classes that satisfies EventDefinition concept

Subclassed by obscura::LoopBase< Dispatcher >

Public Functions

inline void dispatch()

Dispatches all enqueued events to the respective listeners.

inline void enqueue(typename Definition::Event &&event)

Enqueue an event in the dispatcher. The event is passed forward to the respective listener once dispatch() is called.

Parameters:

event – Can be any event, the dispatcher is configured for. The function only takes events that are defined for the dispatcher.

template<class Address>
inline void enqueue(const Address &address, typename Definition::Event &&event)

Same as enqueue(Definition::Event&&) but additionally requires a listener. Events enqueued with this function will only be dispatched to the given listener.

Template Parameters:

Address – Type of the listener to which the event shall be dispatched.

Parameters:

• address – Listener to which the event shall be dispatched.

• event – Can be any event, the dispatcher is configured for. The function only takes events that are defined for the dispatcher.

inline void enqueue(const typename Definition::Event &event)

Same as enqueue(Definition::Event&&) but the function takes a const reference of the event.

Parameters:

event – Can be any event, the dispatcher is configured for. The function only takes events that are defined for the dispatcher.

template<class Address>
inline void enqueue(const Address &address, const typename Definition::Event &event)

Same as enqueue(const Address&, Definition::Event&&) but the functions takes a const reference of the event.

Template Parameters:

Address – Type of the listener to which the event shall be dispatched.

Parameters:

• address – Listener to which the event shall be dispatched.

• event – Can be any event, the dispatcher is configured for. The function only takes events that are defined for the dispatcher.

template<class Listener, bool hasFoundMatchedConcept = false>
inline auto appendListener(Listener &listener) -> std::size_t

Appends a new listener to the register of the dispatcher. Listeners must be added before events can be dispatched to them.

Note

If you want to address an event to a specific listener, appendAddressableListener(Listener&) must be used.

Template Parameters:

• Listener – Type of the listener

• hasFoundMatchedConcept – Template parameter that indicates if the listener fits any of the configured definitions. The parameter is false by default and should not be manually changed.

Parameters:

listener – The listener that is registered with the dispatcher. Can be any object as long as it contains at least one of the callback defined via the event definitions. If the listener is not fitting a compile error will be thrown. One listener can have arbitrarily many supported callbacks.

Returns:

Returns a handle to the registered listener. This handle must be used to unregister the listener again from the dispatcher.

template<class Listener, bool hasFoundMatchedConcept = false>
inline auto appendAddressableListener(Listener &listener) -> std::size_t

Same as appendListener(Listener&) but listeners registered with this function are only invoked if an event is enqueued with enqueue(const Address&, const Definition::Event&) targeted for the appended listener.

Note

Globally enqueued events are also dispatched to listeners registered with this function.

Template Parameters:

• Listener – Type of the listener

• hasFoundMatchedConcept – Template parameter that indicates if the listener fits any of the configured definitions. The parameter is false by default and should not be manually changed.

Parameters:

listener – The listener that is registered with the dispatcher. Can be any object as long as it contains at least one of the callback defined via the event definitions. If the listener is not fitting a compile error will be thrown. One listener can have arbitrarily many supported callbacks.

Returns:

Returns a handle to the registered listener. This handle must be used to unregister the listener again from the dispatcher.

template<class Listener>
inline auto removeListener(Listener &listener) -> bool

Removes a listener from the register of the dispatcher, i.e., events will not be dispatched to the respective listener anymore.

Template Parameters:

Listener – Type of the listener.

Parameters:

listener – Reference to the listener.

Returns:

Whether the removal was successful or not.

template<class Listener>
inline auto hasListenerRegistered(const Listener &listener) -> bool

inline auto hasListenerForEvent([[maybe_unused]] const typename Definition::Event &event) -> bool

Checks whether a listener was appended that a certain event can be dispatched to.

Parameters:

event – Any event the dispatcher is configured for.

Returns:

Whether a listener for an event is appended.

using obscura::Dispatcher = ConfigurableDispatcher<TickDefinition, KeyPressedDefinition, MouseMovedDefintion, KeyReleasedDefintion, KeyRepeatedDefintion, WindowClosedDefintion, MouseClickedDefinition, LoopEndDefinition>

The Obscura default dispatcher with all predefined event types pre-configured. Use this class if you have no need to define custom events.

Helper functions

These are functions that are internally used in the dispatcher implementation

template<class Definition, class Queue>
void obscura::appendToEventQueue(typename Definition::Event &&event, Queue &eventQueue)

Given an event and an event queue, the function checks if the event queue has a listener registered for this event (if not a warning will be logged) and enqueues the event in the queue.

Template Parameters:

• Definition – The event definition.

• Queue – The type of the queue.

Parameters:

• event – The event of type Definition::Event.

• eventQueue – The event queue object.

template<class Definition, class Queue>
void obscura::appendToEventQueue(const typename Definition::Event &event, Queue &eventQueue)

Same as appendToEventQueue(Definition::Event&&, Queue&) but with a const reference to the event.

Template Parameters:

• Definition – The event definition.

• Queue – The type of the queue.

Parameters:

• event – The event of type Definition::Event.

• eventQueue – The event queue object.

template<class Definition, class Queue, class Address>
void obscura::appendToEventQueue(const Address &address, typename Definition::Event &&event, Queue &eventQueue)

Same as appendToEventQueue(typename Definition::Event&& event, Queue& eventQueue) but addresses the event only to the given listener.

Template Parameters:

• Definition – The event definition.

• Queue – The type of the queue.

• Address – Type of the addressed listener.

Parameters:

• address – Listener to which the event shall be solely dispatched.

• event – The event of type Definition::Event.

• eventQueue – The event queue object.

template<class Definition, class Queue, class Address>
void obscura::appendToEventQueue(const Address &address, const typename Definition::Event &event, Queue &eventQueue)

Same as appendToEventQueue(const Address& address, typename Definition::Event&& event, Queue& eventQueue) but with a const reference event.

Template Parameters:

• Definition – The event definition.

• Queue – The type of the queue.

• Address – Type of the addressed listener.

Parameters:

• address – Listener to which the event shall be solely dispatched.

• event – The event of type Definition::Event.

• eventQueue – The event queue object.

template<class Definition, class Queue>
void obscura::checkIfHasListener(std::size_t code, const Queue &eventQueue)

Checks if a queue has any listener for the given code.

Template Parameters:

• Definition – The event definition.

• Queue – The type of the event queue.

Parameters:

• code – 0 for generic listeners and <address> (i.e. the pointer address) for addressable listeners

• eventQueue – The event queue object.

template<class Definition, class Listener, class Queue, class ListenerRegistry>
auto obscura::appendToListenerQueue(Listener &listener, Queue &queue, ListenerRegistry &registry)

Register a listener with an event queue.

Template Parameters:

• Definition – The event definition.

• Listener – The listener type.

• Queue – The event queue type.

• ListenerRegistry – The type of the listener registry. Usually, std::unordered_map<std::size_t, std::list<Handle>>

Parameters:

• listener – The listener object.

• queue – The event queue object.

• registry – The listener registry keeps track of appended listeners and their handles such that they can be removed again.

Returns:

Returns the address of the appended listener casted to size_t.