plGlobalEvent Class Reference

A class to broadcast and handle global (system-wide) events. More...

#include <GlobalEvent.h>

Inheritance diagram for plGlobalEvent:

Classes
struct	EventData

Public Types
using	EventMap = plMap<plString, EventData>
using	PL_GLOBAL_EVENT_HANDLER = void (*)(const plVariant&, const plVariant&, const plVariant&, const plVariant&)
	[internal] Use the macro PL_ON_GLOBAL_EVENT or PL_ON_GLOBAL_EVENT_ONCE to create an event handler.

Public Member Functions
	plGlobalEvent (plStringView sEventName, PL_GLOBAL_EVENT_HANDLER eventHandler, bool bOnlyOnce)
	[internal] Use the macro PL_ON_GLOBAL_EVENT or PL_ON_GLOBAL_EVENT_ONCE to create an event handler.

Static Public Member Functions
static void	Broadcast (plStringView sEventName, plVariant param0=plVariant(), plVariant param1=plVariant(), plVariant param2=plVariant(), plVariant param3=plVariant())
	This function will broadcast a system wide event to all event handlers that are registered to handle this specific type of event.
static void	PrintGlobalEventStatistics ()
	This function will output (via plLog) some statistics about which events are used and how often.
static void	UpdateGlobalEventStatistics ()
	Updates all global event statistics.
static const EventMap &	GetEventStatistics ()
	Returns the map that holds the current statistics about the global events.
Static Public Member Functions inherited from plNoBase
static const plRTTI *	GetStaticRTTI ()

Additional Inherited Members
Protected Attributes inherited from plEnumerable< plGlobalEvent >
plEnumerable *	m_pNextInstance

Detailed Description

A class to broadcast and handle global (system-wide) events.

A global event is an event that will be sent to all instances of plGlobalEvent (or rather their respective handler functions), without the need to first register these event-handlers anywhere. Thus they are very useful to notify sub-systems of certain important events, such as that some kind of initialization will be done shortly, which means they can react by preparing properly. For example the plStartup-class will send certain events before doing startup and shutdown steps, which allows code to free resources before a sub-system might be shut down. plGlobalEvent's should be used when there is a kind of event that should be propagated throughout the entire engine, without knowledge which systems might want to know about it. These systems can then use an plGlobalEvent-instance to hook themselves into the global-event pipeline and react accordingly. Global events should mostly be used for startup / configuration / shutdown procedures. Also one should never assume any specific order of execution, all event handlers should be completely independent from each other.

To create a global event handler, simply add this code inside a cpp file:

PL_ON_GLOBAL_EVENT(EventName) { ... do something ... }

You can also use PL_ON_GLOBAL_EVENT_ONCE, if the handler should only be executed the first time the event is sent. This is more efficient than filtering out duplicate events inside the event handler.

Member Function Documentation

Broadcast()

void plGlobalEvent::Broadcast ( plStringView sEventName, plVariant param0 = plVariant(), plVariant param1 = plVariant(), plVariant param2 = plVariant(), plVariant param3 = plVariant() )

static

This function will broadcast a system wide event to all event handlers that are registered to handle this specific type of event.

The string specifies the event type, the parameters are optional and can be used to send additional event specific data.

PrintGlobalEventStatistics()

void plGlobalEvent::PrintGlobalEventStatistics ( )

static

This function will output (via plLog) some statistics about which events are used and how often.

This allows to figure out which events are used throughout the engine and which events might be fired too often.

---

The documentation for this class was generated from the following files:

• Code/Engine/Foundation/Communication/GlobalEvent.h
• Code/Engine/Foundation/Communication/Implementation/GlobalEvent.cpp