You.i Engine
CYIEventDispatcher Class Reference

Detailed Description

Stores, queues and dispatches events as well as sending notifications to IYIEventDispatcherListener objects regarding different actions being taken on the events.

#include <event/YiEventDispatcher.h>

Inheritance diagram for CYIEventDispatcher:

Public Types

enum  Priority {
  Priority::High,
  Priority::Low
}
 

Public Member Functions

 CYIEventDispatcher ()
 
virtual ~CYIEventDispatcher ()
 
bool Start ()
 
bool Exit (bool join=false, bool waitUntilEmpty=false)
 
void WaitUntilEventQueueRunning ()
 
bool WaitUntilEventPosted (uint64_t timeoutMs=0)
 
bool ProcessOneEvent ()
 
bool ProcessAllEvents ()
 
bool ProcessAllEvents (uint64_t timeoutUs)
 
bool ProcessEventsOfType (CYIEvent::Type type)
 
bool ProcessEventsOfTypes (const std::vector< CYIEvent::Type > &types)
 
bool RegisterEventHandler (CYIEventHandler *pEventHandler, Priority priority=Priority::Low)
 
bool UnregisterEventHandler (CYIEventHandler *pEventHandler)
 
bool RegisterEventFilter (CYIEventFilter *pEventFilter, Priority priority=Priority::Low)
 
bool UnregisterEventFilter (CYIEventFilter *pEventFilter)
 
bool RegisterEventDispatcherListener (IYIEventDispatcherListener *pEventDispatcherListener, Priority priority=Priority::Low)
 
bool UnregisterEventDispatcherListener (IYIEventDispatcherListener *pEventDispatcherListener)
 
bool PostEvent (std::unique_ptr< CYIEvent > pEvent, CYIEvent::Priority priority=CYIEvent::Priority::Default, bool bump=false)
 
bool PostEvent (std::unique_ptr< CYIEvent > pEvent, CYIEventHandler *pDestination, CYIEvent::Priority priority=CYIEvent::Priority::Default, bool bump=false)
 
bool PostUniqueEvent (std::unique_ptr< CYIEvent > pEvent, CYIEvent::Priority priority=CYIEvent::Priority::Default)
 
bool PostUniqueEvent (std::unique_ptr< CYIEvent > pEvent, CYIEventHandler *pDestination, CYIEvent::Priority priority=CYIEvent::Priority::Default)
 
bool SendEvent (std::unique_ptr< CYIEvent > pEvent)
 
bool SendEvent (std::unique_ptr< CYIEvent > pEvent, CYIEventHandler *pDestination)
 
size_t GetEventCount () const
 
void Shutdown ()
 
void DiscardAllPosts ()
 
void DiscardPosts (CYIEventHandler *pDestination)
 
void DiscardPostsIf (bool(*predicate)(const std::shared_ptr< CYIEventDispatcher > &, CYIEvent *, CYIEventHandler *, CYIEvent::Priority))
 
CYIEventHandlerGetSignalEmitEventHandler ()
 
CYIEventHandlerGetDeferredDeletionEventHandler ()
 
CYIEventHandlerGetTaskEventHandler ()
 
- Public Member Functions inherited from CYISignalHandler
 CYISignalHandler ()
 
 CYISignalHandler (const CYISignalHandler &rSignalHandler)
 
virtual ~CYISignalHandler ()
 
CYISignalHandleroperator= (const CYISignalHandler &rSignalHandler)
 
void MoveToThread (CYIThread *pThread)
 This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...
 
CYIThreadHandle GetThreadAffinity () const
 
void SetThreadAffinity (const CYIThreadHandle &rThreadAffinity)
 
virtual bool IsConnected () const
 
virtual bool IsConnected (const CYISignalBase &rSignal) const
 
void Disconnect (CYISignalBase &rSignal)
 
void DisconnectFromAllSignals ()
 
- Public Member Functions inherited from CYIThread::Listener
 Listener ()
 
virtual ~Listener ()
 
virtual void OnThreadStarted (CYIThread *)
 
virtual void OnThreadTerminated (CYIThread *)
 
virtual void OnThreadFinished (CYIThread *)
 

Static Public Member Functions

static std::shared_ptr< CYIEventDispatcherGetDispatcher (const CYIThreadHandle &threadAffinity)
 
static const std::shared_ptr< CYIEventDispatcher > & GetDefaultDispatcher ()
 
static const CYIThreadHandleGetDefaultDispatcherThreadAffinity ()
 
static const std::shared_ptr< CYIEventDispatcher > & GetDrawDispatcher ()
 
static void SetDispatcher (const CYIThreadHandle &threadAffinity, const std::shared_ptr< CYIEventDispatcher > &pDispatcher)
 
static void RemoveDispatcher (const CYIThreadHandle &threadAffinity)
 
static void SetDefaultDispatcher (const std::shared_ptr< CYIEventDispatcher > &pDispatcher)
 
static void RemoveDefaultDispatcher ()
 
static void SetDrawDispatcher (const std::shared_ptr< CYIEventDispatcher > &pDispatcher)
 
static void RemoveDrawDispatcher ()
 

Friends

class CYIEventHandler
 

Member Enumeration Documentation

◆ Priority

Describes the priority of item and the order in which it will be added to a list.

See also
RegisterEventHandler
RegisterEventFilter
RegisterEventDispatcherListener
Enumerator
High 

The item is higher priority and will be added at the front of the list.

Low 

The item is lower priority and will be added at the back of the list.

Constructor & Destructor Documentation

◆ CYIEventDispatcher()

CYIEventDispatcher::CYIEventDispatcher ( )

◆ ~CYIEventDispatcher()

virtual CYIEventDispatcher::~CYIEventDispatcher ( )
virtual

Member Function Documentation

◆ DiscardAllPosts()

void CYIEventDispatcher::DiscardAllPosts ( )

Clears the event queue and deletes each item.

◆ DiscardPosts()

void CYIEventDispatcher::DiscardPosts ( CYIEventHandler pDestination)

Deletes each item in the queue that belongs to pDestination.

◆ DiscardPostsIf()

void CYIEventDispatcher::DiscardPostsIf ( bool(*)(const std::shared_ptr< CYIEventDispatcher > &, CYIEvent *, CYIEventHandler *, CYIEvent::Priority predicate)

Deletes each item in the queue if the predicate for that event returns true.

◆ Exit()

bool CYIEventDispatcher::Exit ( bool  join = false,
bool  waitUntilEmpty = false 
)

Stops the event queue.

If join is true, wait for the thread to exit.

If waitUntilEmpty is true, wait for the queue to be empty before stopping.

◆ GetDefaultDispatcher()

static const std::shared_ptr<CYIEventDispatcher>& CYIEventDispatcher::GetDefaultDispatcher ( )
static

Returns the default CYIEventDispatcher.

◆ GetDefaultDispatcherThreadAffinity()

static const CYIThreadHandle& CYIEventDispatcher::GetDefaultDispatcherThreadAffinity ( )
static

Returns the CYIThreadHandle of the default dispatcher.

◆ GetDeferredDeletionEventHandler()

CYIEventHandler* CYIEventDispatcher::GetDeferredDeletionEventHandler ( )

Returns the current CYIDeferredDeletionEventHandler.

◆ GetDispatcher()

static std::shared_ptr<CYIEventDispatcher> CYIEventDispatcher::GetDispatcher ( const CYIThreadHandle threadAffinity)
static

Returns the CYIEventDispatcher belonging to threadAffinity.

◆ GetDrawDispatcher()

static const std::shared_ptr<CYIEventDispatcher>& CYIEventDispatcher::GetDrawDispatcher ( )
static

Returns the current draw dispatcher for drawing hardware-mirrored assets.

See also
CYIAssetHardware

◆ GetEventCount()

size_t CYIEventDispatcher::GetEventCount ( ) const

Returns the number of events in the queue.

◆ GetSignalEmitEventHandler()

CYIEventHandler* CYIEventDispatcher::GetSignalEmitEventHandler ( )

Returns the current CYISignalEmitEventHandler.

◆ GetTaskEventHandler()

CYIEventHandler* CYIEventDispatcher::GetTaskEventHandler ( )

Returns the current CYITaskEventHandler.

◆ PostEvent() [1/2]

bool CYIEventDispatcher::PostEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEvent::Priority  priority = CYIEvent::Priority::Default,
bool  bump = false 
)

Adds the event to the event queue with CYIEvent::Priority priority.

If bump is true, then push it to the top of the queue. Otherwise queue it normally.

◆ PostEvent() [2/2]

bool CYIEventDispatcher::PostEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEventHandler pDestination,
CYIEvent::Priority  priority = CYIEvent::Priority::Default,
bool  bump = false 
)

Adds both pEvent and pDestination to the event queue.

◆ PostUniqueEvent() [1/2]

bool CYIEventDispatcher::PostUniqueEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEvent::Priority  priority = CYIEvent::Priority::Default 
)

Adds the event to the event queue with the CYIEvent::Priority priority and deletes all previous instances of the event type.

◆ PostUniqueEvent() [2/2]

bool CYIEventDispatcher::PostUniqueEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEventHandler pDestination,
CYIEvent::Priority  priority = CYIEvent::Priority::Default 
)

Adds the event to the event queue with the CYIEvent::Priority priority and deletes all previous instances of the event type.

If pDestination is specified, then it gets stored in the queue along with the pEvent.

◆ ProcessAllEvents() [1/2]

bool CYIEventDispatcher::ProcessAllEvents ( )

Processes all events in the queue.

Returns true if there are items in the queue and the processing action is successful and false otherwise.

◆ ProcessAllEvents() [2/2]

bool CYIEventDispatcher::ProcessAllEvents ( uint64_t  timeoutUs)

Similar to ProcessAllEvents() but it adds the timeoutUs parameter which will limit the time processing the events.

◆ ProcessEventsOfType()

bool CYIEventDispatcher::ProcessEventsOfType ( CYIEvent::Type  type)

Similar to ProcessAllEvents() but only events of type type will be processed.

Warning
Calling this function can result in events being processed out of order, which can cause unexpected behaviour and/or crashes. For example, processing CYIEvent::Type::ActionDown events before CYIEvent::Type::ActionUp can result in buttons or lists 'sticking'.

Returns true if at least one event matched the specified type and the processing action is successful, and false otherwise.

See also
ProcessEventsOfTypes

◆ ProcessEventsOfTypes()

bool CYIEventDispatcher::ProcessEventsOfTypes ( const std::vector< CYIEvent::Type > &  types)

Similar to ProcessAllEvents() but only events whose type is contained in types will be processed.

Note
Calling this function is functionally different from calling ProcessEventsOfType(CYIEvent::Type) multiple times as the relative order of the events whose type is contained in types is preserved.
Warning
Calling this function can result in events being processed out of order, which can cause unexpected behaviour and/or crashes. For example, processing CYIEvent::Type::ActionDown events before CYIEvent::Type::ActionUp can result in buttons or lists 'sticking'.

Returns true if at least one event matched the specified types and the processing action is successful, and false otherwise.

See also
ProcessEventsOfType

◆ ProcessOneEvent()

bool CYIEventDispatcher::ProcessOneEvent ( )

Processes the first event in the queue if the queue is not empty.

Returns true if there are items in the queue and the processing action is successful and false otherwise.

◆ RegisterEventDispatcherListener()

bool CYIEventDispatcher::RegisterEventDispatcherListener ( IYIEventDispatcherListener pEventDispatcherListener,
Priority  priority = Priority::Low 
)

Adds pEventDispatcherListener to the list of event dispatch listeners. Specify priority to indicate how the event dispatcher listener should be added to the list of event disptacher listeners.

Warning
Registering an event dispatcher listener inside of any of the listener's methods is unsupported and will cause deadlock.

◆ RegisterEventFilter()

bool CYIEventDispatcher::RegisterEventFilter ( CYIEventFilter pEventFilter,
Priority  priority = Priority::Low 
)

Adds pEventFilter to the list of event filters. Specify priority to indicate how the event filter should be added to the list of event filters.

Note
The event dispatcher does not take ownership of pEventFilter.
Warning
Registering an event filter inside of the following methods is unsupported and will cause deadlock:

◆ RegisterEventHandler()

bool CYIEventDispatcher::RegisterEventHandler ( CYIEventHandler pEventHandler,
Priority  priority = Priority::Low 
)

Adds pEventHandler to the list of event handlers. Specify priority to indicate how the event handler should be added to the list of event handlers.

Warning
Registering an event handler inside of the following methods is unsupported and will cause deadlock:

◆ RemoveDefaultDispatcher()

static void CYIEventDispatcher::RemoveDefaultDispatcher ( )
static

Clears the default event dispatcher.

◆ RemoveDispatcher()

static void CYIEventDispatcher::RemoveDispatcher ( const CYIThreadHandle threadAffinity)
static

Removes the event dispatcher which belongs to threadAffinity.

◆ RemoveDrawDispatcher()

static void CYIEventDispatcher::RemoveDrawDispatcher ( )
static

Clears the default draw event dispatcher.

◆ SendEvent() [1/2]

◆ SendEvent() [2/2]

bool CYIEventDispatcher::SendEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEventHandler pDestination 
)

Immediately dispatches the event.

If pDestination is specified, then it gets dispatched along with the pEvent.

Warning
Calling this variation of send event inside of the following methods is only supported if pDestination is non-null.

The event may be posted instead.

See also
PostEvent

◆ SetDefaultDispatcher()

static void CYIEventDispatcher::SetDefaultDispatcher ( const std::shared_ptr< CYIEventDispatcher > &  pDispatcher)
static

Sets the default event dispatcher to pDispatcher.

◆ SetDispatcher()

static void CYIEventDispatcher::SetDispatcher ( const CYIThreadHandle threadAffinity,
const std::shared_ptr< CYIEventDispatcher > &  pDispatcher 
)
static

Sets the event dispatcher belonging to threadAffinity to pDispatcher.

◆ SetDrawDispatcher()

static void CYIEventDispatcher::SetDrawDispatcher ( const std::shared_ptr< CYIEventDispatcher > &  pDispatcher)
static

Sets the default draw event dispatcher to pDispatcher.

◆ Shutdown()

void CYIEventDispatcher::Shutdown ( )

Clears the events from the dispatcher.

Note
Console platforms (i.e Xbox, Playstation) restrictions require events to be purged from the queue without processing. In all other cases, all events are immediately processed.

◆ Start()

bool CYIEventDispatcher::Start ( )

Starts the event loop and event queue.

◆ UnregisterEventDispatcherListener()

bool CYIEventDispatcher::UnregisterEventDispatcherListener ( IYIEventDispatcherListener pEventDispatcherListener)

Removes pEventDispatcherListener from the list of event dispatch listeners.

Warning
Unregistering an event dispatcher listener inside of any of the listener's methods is unsupported and will cause deadlock.

◆ UnregisterEventFilter()

bool CYIEventDispatcher::UnregisterEventFilter ( CYIEventFilter pEventFilter)

Removes pEventFilter from the list of event filters.

Warning
Unregistering an event filter inside of the following methods is unsupported and will cause deadlock:

◆ UnregisterEventHandler()

◆ WaitUntilEventPosted()

bool CYIEventDispatcher::WaitUntilEventPosted ( uint64_t  timeoutMs = 0)

Blocks until an event has been posted to the queue or times out after timeoutMs milliseconds.

The default value 0, represents no timeout. Returns true if the wait timed out.

See also
PostEvent
PostUniqueEvent

◆ WaitUntilEventQueueRunning()

void CYIEventDispatcher::WaitUntilEventQueueRunning ( )

If the event queue is not running, blocks here until the event queue starts up.

Friends And Related Function Documentation

◆ CYIEventHandler

friend class CYIEventHandler
friend

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