Yahoo! UI Library

event  3.3.0pr1

Yahoo! UI Library > event > SyntheticEvent
Search:
 
Filters

Class SyntheticEvent

Wrapper class for the integration of new events into the YUI event infrastructure. Don't instantiate this object directly, use Y.Event.define(type, config). See that method for details.

Properties that MAY or SHOULD be specified in the configuration are noted below and in the description of Y.Event.define.

Constructor

SyntheticEvent ( cfg )
Parameters:
cfg <Object> Implementation pieces and configuration

Properties

preventDups - {Boolean}

Implementers MAY override this property.

Whether to prevent multiple subscriptions to this event that are classified as being the same. By default, this means the subscribed callback is the same function. See the subMatch method. Setting this to true will impact performance for high volume events.

Default Value: false

Methods

_deleteSub

private void _deleteSub ( sub )
Alternate _delete() method for the CustomEvent object created to manage SyntheticEvent subscriptions.
Parameters:
sub <Subscription> the subscription to clean up

_detach

private void _detach ( args )
Removes the subscription(s) from the internal subscription dispatch mechanism. See SyntheticEvent._deleteSub.
Parameters:
args <Array> The arguments passed to node.detach(...)

_getNotifier

private SyntheticEvent.Notifier _getNotifier ( node , args , extra , filter )
Creates a new Notifier object for use by this event's on(...) or delegate(...) implementation.
Parameters:
node <Node> the Node hosting the event
args <Array> the subscription arguments passed to either Y.on(...) or Y.delegate(...) after running through processArgs(args) to normalize the argument signature
extra <any> Extra data parsed from processArgs(args)
filter <String|Function> the selector string or function filter passed to Y.delegate(...) (not present when called from Y.on(...))

_init

protected void _init ( )
Construction logic for the event.

_on

private EventHandle _on ( args , delegate )
Sets up the boilerplate for detaching the event and facilitating the execution of subscriber callbacks.
Parameters:
args <Array> array of arguments passed to Y.on(...) or Y.delegate(...)
delegate <Boolean> true if called from Y.delegate(...)
Returns: EventHandle
the detach handle for this subscription

_unregisterSub

private void _unregisterSub ( sub )
Removes the subscription from the Notifier registry.
Parameters:
sub <Subscription> the subscription

delegate

void delegate ( node , sub , notifier , filter )

Implementers SHOULD provide this method definition.

Implementation logic for subscriptions done via node.delegate(type, fn, filter) or Y.delegate(type, fn, container, filter). Like with on() above, this function should monitor the environment for the event being fired, and trigger subscription execution by calling notifier.fire(e).

This function receives a fourth argument, which is the filter used to identify which Node's are of interest to the subscription. The filter will be either a boolean function that accepts a target Node for each hierarchy level as the event bubbles, or a selector string. To translate selector strings into filter functions, use Y.delegate.compileFilter(filter).

Parameters:
node <Node> the node the subscription is being applied to
sub <Subscription> the object to track this subscription
notifier <SyntheticEvent.Notifier> call notifier.fire(..) to trigger the execution of the subscribers
filter <String|Function> Selector string or function that accepts an event object and returns null, a Node, or an array of Nodes matching the criteria for processing.

detach

void detach ( node , sub , notifier )

Implementers SHOULD provide this method definition.

Implementation logic for detaching subscriptions done via node.on(type, fn). This function should clean up any subscriptions made in the on() phase.

Parameters:
node <Node> the node the subscription was applied to
sub <Subscription> the object tracking this subscription
notifier <SyntheticEvent.Notifier> the Notifier used to trigger the execution of the subscribers

detachDelegate

void detachDelegate ( node , sub , notifier , filter )

Implementers SHOULD provide this method definition.

Implementation logic for detaching subscriptions done via node.delegate(type, fn, filter) or Y.delegate(type, fn, container, filter). This function should clean up any subscriptions made in the delegate() phase.

Parameters:
node <Node> the node the subscription was applied to
sub <Subscription> the object tracking this subscription
notifier <SyntheticEvent.Notifier> the Notifier used to trigger the execution of the subscribers
filter <String|Function> Selector string or function that accepts an event object and returns null, a Node, or an array of Nodes matching the criteria for processing.

getRegistry

protected static Array getRegistry ( node , type , create )
Returns the array of subscription handles for a node for the given event type. Passing true as the third argument will create a registry entry in the event system's DOM map to host the array if one doesn't yet exist.
Parameters:
node <Node> the node
type <String> the event
create <Boolean> create a registration entry to host a new array if one doesn't exist.

getSubs

Array getSubs ( node , args , filter , first )
Returns the detach handles of subscriptions on a node that satisfy a search/filter function. By default, the filter used is the subMatch method.
Parameters:
node <Node> the node hosting the event
args <Array> the array of original subscription args passed to Y.on(...) (before processArgs
filter <Function> function used to identify a subscription for inclusion in the returned array
first <Boolean> stop after the first match (used to check for duplicate subscriptions)
Returns: Array
detach handles for the matching subscriptions

on

void on ( node , sub , notifier )

Implementers SHOULD provide this method definition.

Implementation logic for subscriptions done via node.on(type, fn) or Y.on(type, fn, target). This function should set up the monitor(s) that will eventually fire the event. Typically this involves subscribing to at least one DOM event. It is recommended to store detach handles from any DOM subscriptions to make for easy cleanup in the detach method. Typically these handles are added to the sub object. Also for SyntheticEvents that leverage a single DOM subscription under the hood, it is recommended to pass the DOM event object to notifier.fire(e). (The event name on the object will be updated).
Parameters:
node <Node> the node the subscription is being applied to
sub <Subscription> the object to track this subscription
notifier <SyntheticEvent.Notifier> call notifier.fire(..) to trigger the execution of the subscribers

processArgs

any processArgs ( args , delegate )

Implementers MAY provide this method definition.

Implement this function if the event supports a different subscription signature. This function is used by both on() and delegate(). The second parameter indicates that the event is being subscribed via delegate().

Implementations must remove extra arguments from the args list before returning. The required args for on() subscriptions are

[type, callback, target, context, argN...]

The required args for delegate() subscriptions are

[type, callback, target, filter, context, argN...]

The return value from this function will be stored on the subscription in the '_extra' property for reference elsewhere.

Parameters:
args <Array> parmeters passed to Y.on(..) or Y.delegate(..)
delegate <Boolean> true if the subscription is from Y.delegate

subMatch

Boolean subMatch ( sub , args )

Implementers MAY override this to define what constitutes a "same" subscription. Override implementations should consider the lack of a comparator as a match, so calling getSubs() with no arguments will return all subs.

Compares a set of subscription arguments against a Subscription object to determine if they match. The default implementation compares the callback function against the second argument passed to Y.on(...) or node.detach(...) etc.

Parameters:
sub <Subscription> the existing subscription
args <Array> the calling arguments passed to Y.on(...) etc.
Returns: Boolean
true if the sub can be described by the args present

Properties

Copyright © 2010 Yahoo! Inc. All rights reserved.