EventHandler

CubicVR.EventHandler

The EventHandler class is used to manage and run Event objects and their bound actions.

The built-in CubicVR events are available via addEvent() in SceneObject and are detailed in the Event documentation.

Typically unless you are doing custom event management you will not need to use this directly as Scene will manage updates to the EventHandler in each SceneObject.

Objects that support events will typically contain a method called addEvent() which takes an Event object or Event constructor and initializes it's own EventHandler.

Constructor:

EventHandler()

Parameters:

none.

Methods:

addEvent( event )

Add an event to the EventHandler.

Parameters:

• event : An existing Event object or an Event object constructor.

Returns:

The passed Event or if passed a constructor a new Event object.

removeEvent( event )

Remove the given event from the handler. If the listener count reaches 0 for a particular handler it will drop the event and unregister it's listener from the pool and free resources; making it preferable to remove an event versus just calling the event.disable() option. Event removal can safely occur during event calls allowing an event action to remove itself from the handler.

Parameters:

• event : An existing Event object that was previously added via addEvent()

Returns:

none.

getProperty( eventId, propName )

Return a user-defined property belonging to this event handler.

Parameters:

• eventId : A user-defined event handler property namespace, typically the same as the Event id but may be repurposed.
• propName : The name of the property to retrieve

Returns:

The value of the property.

setProperty( eventId, propName, value )

Set the value of a user-defined event handler property. Event handler properties are global to all events bound to the same handler making them ideal for shared storage between all bound events. Event weighting can allow you to ensure the sequence in which events are handled and ensure integrity of any logic order between event triggers so that data in the event property will be predictable.

Parameters:

• eventId : A user-defined event handler property namespace, typically the same as the Event id but may be repurposed.
• propName : The name of the property to set.
• value : The value to set the property to.

Returns:

none.

getProperties( eventId )

Return the object containing the user-defined event handler properties.

Parameters:

• eventId : A user-defined event handler property namespace, typically the same as the Event id but may be repurposed.

Returns:

An object containing all user-defined properties for the event.

setProperties( eventId, props )

Set the user-defined event handler property object.

Parameters:

• eventId : A user-defined event handler property namespace, typically the same as the Event id but may be repurposed.
• props : An object containing user-defined event handler properties.

Returns:

none.

hasEvent( eventId )

Check whether this handler has the given eventId listening.

Parameters:

• eventId : the eventId, user-defined or from CubicVR.enums.event

Returns:

true if event listening, false if not.

triggerEvent( eventId, properties )

Trigger the given eventId in the handler, for garbage collection efficency it is better to omit the properties parameter and use the returned object to set your properties. Note that properties may be present from another event trigger of the same type so relevant values should be emptied or overwritten and any default flags reset. If your event has greatly differing internal values between triggers it might be ideal to cache your own object and pass it as a property of the returned object.

Note that no event action will actually be called until the next call to update(), at which time triggered events may be buffered until the next call depending on timing conditions and event activation status or return condition.

Returns:

A recycled or new trigger properties object of the same event type if properties is omitted, otherwise it will return the properties passed.

update( time )

Perform all outstanding triggered event calls. Unprocessed triggers for resting events will be triggered on their next rest interval update and may be buffered. Any events removed during the trigger calls will not be removed until after the update() call completes.

Parameters:

• time : The absolute time in seconds of the update() call, used to process event timing but does not need to be clock-accurate -- you can increment at any interval of your choosing for synchronizing but behavior of reversing time is undefined.

Returns:

none.