Yahoo! UI Library

event  3.1.0

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 void Event.define ( type , cfg )

Static method to register a synthetic event definition and implementation in the DOM Event subsystem.

Pass either a string type and configuration object as separate parameters or a configuration object that includes a type property as a single parameter.

The configuration object should include implementation methods for on and detach. This is the full list of configuration properties:

type
Required if using the Y.Event.define( config ) signature. The name of the synthetic event. What goes node.on(HERE, callback ).
on
function ( node, subscription, fireEvent ) 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 information on the subscription object. When the criteria have been met to fire the synthetic event, call fireEvent.fire().
detach
function ( node, subscription, fireEvent ) The implementation logic for cleaning up a detached subscription. E.g. detach any DOM subscriptions done in on.
publishConfig
(Object) The configuration object that will be used to instantiate the underlying CustomEvent. By default, the event is defined with emitFacade: true so subscribers will receive a DOM-like event object.
processArgs
function ( argArray ) Optional method to extract any additional arguments from the subscription signature. Using this allows on signatures like node.on( "hover", overCallback, outCallback ). Be sure that the args passed in is pruned of any additional arguments using, for example, argArray.splice(2,1);. Data returned from the function will be stored on the subscription object passed to on and detach under subscription._extra.
Parameters:
type <String> Name given to the synthetic event
cfg <Object> configuration object. Pass this as the first parameter if it includes the type property.

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 , p_obj , p_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.
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 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

startInterval

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