Events - mattbichay/test GitHub Wiki
Events are sent to elements to indicate actions that have occurred to that element. Rocket generates many events internally (these are fully specified in the [wiki:documentation/RML/Events]). The application can also send arbitrary events to elements.
When an event is dispatched to an element, it first goes through a bubble phase where the each of the element's ancestors has an opportunity to process the event and stop the propagation. The event is then sent to the target element, then goes through a capture phase where it falls back to its root ancestor.
Events are identified by a descriptive string name (such as "keydown", "blur", etc) and a dictionary of parameters that further describe the event. For example, the "keydown" event has parameters for identifying the actual key that was pressed and the state of the key modifiers.
Events can be handled internally by the elements they are sent to or by an event listener object. An event listener is able to subscribe to specific events on an element and will be notified whenever those events occur.
An event is represented by the Rocket::Core::Event structure, defined in Rocket/Core/Event.h. The public interface to an event object is:
The phase of the event, returned by GetPhase(), will be PHASE_CAPTURE if the event listener received the event during the capture phase or PHASE_BUBBLE if during the bubbling phase.
The target element, returned by GetTargetElement(), is the element the event was originally sent to. The current element, returned by GetCurrentElement(), is the element the event is currently being sent to. This may be the target element or one of the target element's ancestors.
The name of the event ("keydown", "focus", etc) is returned from GetType(). You can also use the equality operator to compare an event directly with a string.
You can fetch the parameters of the event with the templated GetParameter() function. The exact parameters of each event are detailed in the [wiki:documentation/RML/Events].
For event types that can be interrupted, a listener can call the StopPropagation() function on an event to prevent the event's progress through the event cycle.
Any object that wants to listen for events derives from Rocket::Core::EventListener, and implements the one required pure virtual function:
The ProcessEvent() function will be called every time a relevant event is sent to an element the listener is subscribed to.
To subscribe an event listener to an element, call the AddEventListener() function on the element to attach to.
The function takes the following parameters:
* ''event'': The string name of the event the listener wants to attach to, for example "keydown", "focus", etc. * ''listener'': The event listener object to attach. * ''in_capture_phase'': If true, the event listener will receive the event in the capture phase, otherwise, in the bubbling phase. See the [wiki:documentation/RML/Events RML event documentation] for more information.
To unsubscribe an event listener from an element, call the RemoveEventListener() function on the element:
The application can send an arbitrary event to an element through the DispatchEvent() function on Rocket::Core::Element.
The event will be created and sent through the standard event loop. The following example sends a "close" event to an element:
Events are instanced through an event instancer similarly to contexts. The instancer can be overridden with a custom instancer if a custom event is required; this is generally only needed to integrate a scripting language into Rocket.
A custom event inherits from Rocket::Core::Event. There are no virtual functions to be overridden.
A custom event instancer needs to be created and registered with the Rocket factory in order to have custom events instanced. A custom event instancer derives from Rocket::Core::EventInstancer and implements the required pure virtual functions:
InstanceEvent() will be called whenever the factory is called upon to instance an event. The parameters to the function are:
* ''target'': The element the event is begin targeted at.
* ''name'': The name of the event ("keydown", "focus", etc).
* ''parameters'': The parameters to the event as a dictionary.
* ''interruptible'': True if the event can be interrupted (ie, prevented from propagating throughout the entire event cycle), false if not.
If InstanceEvent() is successful, return the new event. Otherwise, return NULL (0) to indicate an instancing error.
ReleaseEvent() will be called when an event instanced through the instancer is no longer required by the system. It should be deleted appropriately.
Release() will be called when the event instancer is no longer required, usually when Rocket is shut down. The instancer should delete itself as appropriate.
To register a custom instancer with Rocket, call the RegisterEventInstancer() function on the Rocket factory (Rocket::Core::Factory) after Rocket has been initialised.
Like other instancers, the event instancer is reference counted. Remember to remove the initial reference after you register a custom instancer with the factory.
Event responses can be specified as element attributes inside RML, similarly to HTML. For example, in the following RML fragment a response is given to the "click" event.
Notice the "on" prefix before the event name of "click". All event bindings from RML are prefixed this way.
Rocket sends inline events to event listener proxy objects that are created by the application. An application must therefore register a custom event listener instancer to have an opportunity to interpret the events.
A custom event listener instancer derives from Rocket::Core::EventListenerInstancer. The following pure virtual functions must be implemented:
InstanceEventListener() will be called during RML parsing whenever the factory needs to find an event listener for an inline event. The parameter value will be the raw event response string as specified in the RML.
Release() will be called when the event instancer is no longer required, usually when Rocket is shut down. The instancer should delete itself as appropriate.