You.i Engine
Events

Detailed Description

Events and event dispatching.

You.i Engine's event system is based on the W3C Dom Level 3 events standard.

Events Broadcasting

The CYIApp instance generates and dispatches most of the events that are dealt with. Events that users are typically interested in are touch and move events (CYIActionEvent), key input events (CYIKeyEvent) and trackpad events (CYITrackpadEvent).

When user input is detected by the CYIApp instance, one or more corresponding events are generated and broadcast. The object which receives the events depends on the event type, and on which object are registered as events listener.

For CYIActionEvent, a CYIRay is generated at the screen coordinates specified in the event. The ray is then transformed into the scene nodes' local space to find the scene node that should receive the event. This node is called the event target. The Capture phase of the event system is then initiated. Starting at the root node of the scene tree, the ancestors of the event target are traversed one by one. This gives ancestors the opportunity to 'capture' the event from the event target by setting the CYIEvent::bStopPropagation flag to true. If the propagation isn't stopped, the event is then given to the event target to process. Again, the event target can stop propagation by setting CYIEvent::bStopPropagation to true. Once processed by the event target, and if the propagation hasn't been stopped, the ancestors of the event target are traversed again but starting at the event target and going towards the root node. This last traversal is called the Bubble phase.

Note
Only scene nodes that have registered themselves as event listeners are considered for handling events. This registration is done using the CYIEventTarget::AddEventListener() function. Other objects can register themselves as event listeners by subclassing CYIEventTarget and registering themselves through the CYISceneManager.

For CYIKeyEvent and CYITrackpadEvent, only the scene node that has been registered as capturing events receives the event. This registration is done using the CYISceneNode::StartCaptureKeyboardEvents() and CYISceneNode::StartCaptureTrackpadEvents() functions. While a pick ray is not used to determine the event target, the Capture and Bubble phases are still performed for key and trackpad events.

Event Types

There are multiple event classes used in You.i Engine, all having CYIEvent as the base class. There exist functions on the CYIEvent class which can be used to determine, at runtime, what class an event is. Additionally, the CYIEvent::Type enum lists various subtypes that each event can be. For example, the CYIKeyEvent class can be of type CYIEvent::Type::KeyDown, CYIEvent::Type::KeyUp or CYIEvent::Type::KeyInput. It is often desirable to check the event's type in a scene node's CYIEventHandler::HandleEvent() function.

Note
In most cases, users do not need to create CYIEvent objects manually. The events are generated by You.i Engine as needed, and only need to be processed by users.

Classes

class  CYIAccessibilityEvent
 Accessibility related events. More...
 
class  CYIActionEvent
 Stores data related to a user Action event. More...
 
class  CYIAbstractDeferredDeletionEvent
 Abstract event for handling deferred deletion of data. More...
 
class  CYIDeferredDeletionEvent< YI_TYPE, SfinaeHelper >
 Event for handling deferred deletion of data of type YI_TYPE. SfinaeHelper type is used to control a partial-specialization for CYISceneNode, to ensure the CYISceneNode is removed from it's parent in the scenetree. More...
 
class  CYIDeferredDeletionEventHandler
 Handles events where data deletion needs to be deferred. More...
 
class  CYIEvent
 Base class for events. More...
 
class  IYIEventDispatcherListener
 Implementors of this Listener interface can register themselves with the CYIEventDispather and become Observers of various event dispatching actions. More...
 
class  CYIEventDispatcher
 Stores, queues and dispatches events as well as sending notifications to IYIEventDispatcherListener objects regarding different actions being taken on the events. More...
 
class  CYIEventFilter
 Allows children that inherit from this class to implement processing before and after events are handled. More...
 
class  CYIEventFilterProxy
 Proxy for a CYIEventFilter allowing safe destruction of the internal event filter objects. More...
 
class  CYIEventHandler
 Allows registering of event filters which can be used to perform processing on an event before and after the event has been handled and/or dispatched. More...
 
class  CYIEventHandlerProxy
 Proxy for a CYIEventHandler allowing safe destruction of the internal event handler objects. More...
 
class  CYIEventTarget
 Represents an event target of type CYIEventTarget::SpecialEventTargetType. More...
 
class  CYIFocusEvent
 Focus events represent when a view receives or loses focus. More...
 
class  CYIGestureEvent
 Gesture related events. More...
 
class  CYIKeyEvent
 Class for key events. More...
 
class  CYIRay
 Encapsulates the origin and direction points of a ray. More...
 
class  CYISwipeGestureEvent
 Swipe gesture event. More...
 
class  CYITaskEvent
 Event class containing CYITaskBase items. Supports the task being executed when the event is handled. More...
 
class  CYITaskEventHandler
 Handles events where tasks are executed when the event is processed on an event queue. More...
 
class  CYITrackpadEvent
 Stores data related to trackpad input. More...
 

Functions

template<typename YI_TYPE >
void YiDeleteLater (std::unique_ptr< YI_TYPE > pPtr)
 Adds the given pointer to the deferred deletion queue. More...
 

Function Documentation

template<typename YI_TYPE >
void YiDeleteLater ( std::unique_ptr< YI_TYPE >  pPtr)
inline

Adds the given pointer to the deferred deletion queue.

The data is passed in a

See also
CYIDeferredDeletionEvent, and will be deleted when the deletion Events are processed.