# Yahoo! UI Library

### event 3.0.0b1

Yahoo! UI Library > event > Event
Search:
Filters Show Private Show Protected Show Deprecated

## `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 2000@amp;20 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

Returns: `void`

#### _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

Returns: `void`

#### _unload

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

Returns: `void`

#### attach

`static Boolean attach ( type , fn , el , obj , args )`
Appends an event handler

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.
  `obj <Object>` An arbitrary object that will be passed as a parameter to the handler
  `args <Boolean|object>` 0..n arguments to pass to the callback

Returns: `Boolean`
  True if the action was successful or defered, false if one or more of the elements could not have the listener attached, or if the operation throws an exception.

#### detach

`static boolean detach ( el , type , fn )`
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:
  `el <String|HTMLElement|Array|NodeList>` An id, an element reference, or a collection of ids and/or elements to remove the listener from.
  `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.

Returns: `boolean`
  true if the unbind was successful, false * otherwise.

#### 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

Returns: `void`

#### 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

Returns: `void`

#### 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)

Returns: `void`

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

Returns: `void`

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

Returns: `void`

#### startInterval

`private static void startInterval ( )`

Returns: `void`

Copyright © 2009 Yahoo! Inc. All rights reserved.