Yahoo! UI Library

event  3.3.0pr1

Yahoo! UI Library > event > Event
Search:
 
Filters

static Class Event

The event utility provides functions to add and remove event listeners, event cleansing. It also tries to automatically remove listeners it registers during the unload event.

Properties

_avail - private static object

onAvailable listeners

_dri - private static object

document readystate poll handle

_el_events - private static object

Custom event wrapper map DOM events. Key is Element uid stamp. Each item is a hash of custom event wrappers as provided in the _wrappers collection. This provides the infrastructure for getListeners.

_interval - private static object

poll handle

_loadComplete - private static boolean

True after the onload event has fired

_retryCount - private static object

The number of times to poll after window.onload. This number is increased if additional late-bound handlers are requested after the page load.

_wrappers - private static Y.Event.Custom

Custom event wrappers for DOM events. Key is 'event:' + Element uid stamp + event type

DOMReady - static boolean

True when the document is initially usable

lastError - static Error

addListener/removeListener can throw errors in unexpected scenarios. These errors are suppressed, the method returns false, and this property is set

POLL_INTERVAL - static final int

The poll interval in milliseconds

POLL_RETRYS - static final int

The number of times we should look for elements that are not in the DOM at the time the event is requested after the document has been loaded. The default is 1000@amp;40 ms, so it will poll for 40 seconds or until all outstanding handlers are bound (whichever comes first).

Methods

_isValidCollection

private static boolean _isValidCollection ( o )
We want to be able to use getElementsByTagName as a collection to attach a group of events to. Unfortunately, different browsers return different types of collections. This function tests to determine if the object is array-like. It will also fail if the object is an array, but is empty.
Parameters:
o <object> the object to test
Returns: boolean
true if the object is array-like and populated
Deprecated was not meant to be used directly

_load

private static void _load ( )
hook up any deferred listeners

_poll

private static void _poll ( )
Polling function that runs before the onload event fires, attempting to attach to DOM Nodes as soon as they are available

_unload

private static void _unload ( )
Removes all listeners registered by pe.event. Called automatically during the unload event.

attach

static EventHandle attach ( type , fn , el , context , args )
Adds an event listener
Parameters:
type <String> The type of event to append
fn <Function> The method the event invokes
el <String|HTMLElement|Array|NodeList> An id, an element reference, or a collection of ids and/or elements to assign the listener to.
context <Object> optional context object
args <Boolean|object> 0..n arguments to pass to the callback
Returns: EventHandle
an object to that can be used to detach the listener

detach

static boolean detach ( type , fn , el )
Removes an event listener. Supports the signature the event was bound with, but the preferred way to remove listeners is using the handle that is returned when using Y.on
Parameters:
type <String> the type of event to remove.
fn <Function> the method the event invokes. If fn is undefined, then all event handlers for the type of event are removed.
el <String|HTMLElement|Array|NodeList|EventHandle> An event handle, an id, an element reference, or a collection of ids and/or elements to remove the listener from.
Returns: boolean
true if the unbind was successful, false otherwise.

Event.define

static SyntheticEvent Event.define ( type , config , force )

Defines a new event in the DOM event system. Implementers are responsible for monitoring for a scenario whereby the event is fired. A notifier object is provided to the functions identified below. When the criteria defining the event are met, call notifier.fire( [args] ); to execute event subscribers.

The first parameter is the name of the event. The second parameter is a configuration object which define the behavior of the event system when the new event is subscribed to or detached from. The methods that should be defined in this configuration object are on, detach, delegate, and detachDelegate. You are free to define any other methods or properties needed to define your event. Be aware, however, that since the object is used to subclass SyntheticEvent, you should avoid method names used by SyntheticEvent unless your intention is to override the default behavior.

This is a list of properties and methods that you can or should specify in the configuration object:

on
function (node, subscription, notifier) The implementation logic for subscription. Any special setup you need to do to create the environment for the event being fired--E.g. native DOM event subscriptions. Store subscription related objects and state on the subscription object. When the criteria have been met to fire the synthetic event, call notifier.fire(e). See Notifier's fire() method for details about what to pass as parameters.
detach
function (node, subscription, notifier) The implementation logic for cleaning up a detached subscription. E.g. detach any DOM subscriptions added in on.
delegate
function (node, subscription, notifier, filter) The implementation logic for subscription via Y.delegate or node.delegate. The filter is typically either a selector string or a function. You can use Y.delegate.compileFilter(selectorString) to create a filter function from a selector string if needed. The filter function expects an event object as input and should output either null, a matching Node, or an array of matching Nodes. Otherwise, this acts like on DOM event subscriptions. Store subscription related objects and information on the subscription object. When the criteria have been met to fire the synthetic event, call notifier.fire(e) as noted above.
detachDelegate
function (node, subscription, notifier) The implementation logic for cleaning up a detached delegate subscription. E.g. detach any DOM delegate subscriptions added in delegate.
publishConfig
(Object) The configuration object that will be used to instantiate the underlying CustomEvent. See Notifier's fire method for details.
processArgs

function (argArray, fromDelegate) Optional method to extract any additional arguments from the subscription signature. Using this allows on or delegate signatures like node.on("hover", overCallback, outCallback).

When processing an atypical argument signature, make sure the args array is returned to the normal signature before returning from the function. For example, in the "hover" example above, the outCallback needs to be spliced out of the array. The expected signature of the args array for on() subscriptions is:

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

And for delegate():

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

where target is the node the event is being subscribed for. You can see these signatures documented for Y.on() and Y.delegate() respectively.

Whatever gets returned from the function will be stored on the subscription object under subscription._extra.

subMatch

function (sub, args) 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:
type <String> the name of the event
config <Object> the prototype definition for the new event (see above)
force <Boolean> override an existing event (use with caution)
Returns: SyntheticEvent
the subclass implementation instance created to handle event subscriptions of this type

generateId

static string generateId ( el )
Generates an unique ID for the element if it does not already have one.
Parameters:
el <object> the element to create the id for
Returns: string
the resulting id of the element

getEvent

static Event getEvent ( e , el )
Finds the event in the window object, the caller's arguments, or in the arguments of another method in the callstack. This is executed automatically for events registered through the event manager, so the implementer should not normally need to execute this function at all.
Parameters:
e <Event> the event parameter from the handler
el <HTMLElement> the element the listener was attached to
Returns: Event
the event

getListeners

static Y.Custom.Event getListeners ( el , type )
Returns all listeners attached to the given element via addListener. Optionally, you can specify a specific type of event to return.
Parameters:
el <HTMLElement|string> the element or element id to inspect
type <string> optional type of listener to return. If left out, all listeners will be returned
Returns: Y.Custom.Event
the custom event wrapper for the DOM event(s)

nativeAdd

private static void nativeAdd ( el , type , fn , capture )
Adds a DOM event directly without the caching, cleanup, context adj, etc
Parameters:
el <HTMLElement> the element to bind the handler to
type <string> the type of event handler
fn <function> the callback to invoke
capture <boolen> capture or bubble phase

nativeRemove

private static void nativeRemove ( el , type , fn , capture )
Basic remove listener
Parameters:
el <HTMLElement> the element to bind the handler to
type <string> the type of event handler
fn <function> the callback to invoke
capture <boolen> capture or bubble phase

onAvailable

static void onAvailable ( id , fn , p_obj , p_override , checkContent )
Executes the supplied callback when the item with the supplied id is found. This is meant to be used to execute behavior as soon as possible as the page loads. If you use this after the initial page load it will poll for a fixed time for the element. The number of times it will poll and the frequency are configurable. By default it will poll for 10 seconds.

The callback is executed with a single parameter: the custom object parameter, if provided.

Parameters:
id <string||string[]> the id of the element, or an array of ids to look for.
fn <function> what to execute when the element is found.
p_obj <object> an optional object to be passed back as a parameter to fn.
p_override <boolean|object> If set to true, fn will execute in the context of p_obj, if set to an object it will execute in the context of that object
checkContent <boolean> check child node readiness (onContentReady)
Deprecated Use Y.on("available")

onContentReady

static void onContentReady ( id , fn , obj , override )
Works the same way as onAvailable, but additionally checks the state of sibling elements to determine if the content of the available element is safe to modify.

The callback is executed with a single parameter: the custom object parameter, if provided.

Parameters:
id <string> the id of the element to look for.
fn <function> what to execute when the element is ready.
obj <object> an optional object to be passed back as a parameter to fn.
override <boolean|object> If set to true, fn will execute in the context of p_obj. If an object, fn will exectute in the context of that object
Deprecated Use Y.on("contentready")

purgeElement

static void purgeElement ( el , recurse , type )
Removes all listeners attached to the given element via addListener. Optionally, the node's children can also be purged. Optionally, you can specify a specific type of event to remove.
Parameters:
el <HTMLElement> the element to purge
recurse <boolean> recursively purge this element's children as well. Use with caution.
type <string> optional type of listener to purge. If left out, all listeners will be removed

simulate

static void simulate ( target , type , options )
Simulates the event with the given name on a target.
Parameters:
target <HTMLElement> The DOM element that's the target of the event.
type <String> The type of event to simulate (i.e., "click").
options <Object> (Optional) Extra options to copy onto the event object.

startInterval

private static void startInterval ( )
Copyright © 2010 Yahoo! Inc. All rights reserved.