API: event YAHOO.util.Event (YUI Library)

# Yahoo! UI Library

### Event Utility 2.8.0r4

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

## `static` Class YAHOO.util.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

#### _dri - `private static object`

document readystate poll handle

#### _interval - `private static object`

poll handle

#### _specialTypes - `private static object`

Map of special event types

#### ADJ_SCOPE - `static final int`

Adjusted context, either the element we are registering the event on or the custom object passed in by the listener, int constant

#### CAPTURE - `static final int`

The original capture parameter passed into addListener

#### counter - `private static object`

Counter for auto id generation

#### DOMReady - `static boolean`

True when the document is initially usable

#### EL - `static final int`

Element to bind, int constant

#### elCache DOM element cache - `private static object`

Deprecated: Elements are not cached due to issues that arise when elements are removed and re-added

#### FN - `static final int`

Function to execute, int constant

#### isIE - `private static object`

IE detection
Deprecated: use YAHOO.env.ua.ie

#### isSafari - `private static object`

Safari detection
Deprecated: use YAHOO.env.ua.webkit

#### lastError - `static Error`

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

#### listeners - `private static array`

Cache of wrapped listeners

#### loadComplete - `private static boolean`

True after the onload event has fired

#### OBJ - `static final int`

Object passed in by the user that will be returned as a parameter to the callback, int constant. Specific to unload listeners

#### onAvailStack - `private static object`

onAvailable listeners

#### OVERRIDE - `static final int`

The original context parameter passed into addListener

#### 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 500@amp;40 ms, so it will poll for 20 seconds or until all outstanding handlers are bound (whichever comes first).

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

#### throwErrors - `boolean`

Errors thrown by subscribers of custom events are caught and the error message is written to the debug console. If this property is set to true, it will also re-throw the error.
Default Value: false

#### TYPE - `static final int`

Type of event, int constant

#### unloadListeners - `private static array`

User-defined unload function that will be fired before all events are detached

#### webkit - `private static string`

webkit version
Deprecated: use YAHOO.env.ua.webkit

#### webkitKeymap - `private static final {int: int}`

Normalized keycodes for webkit/safari

#### WFN - `static final int`

Function wrapped for context correction and cleanup, int constant

### Methods

#### _addListener

`private static Boolean _addListener ( el , sType , fn , obj , overrideContext , capture )`
Appends an event handler

Parameters:
  `el <String|HTMLElement|Array|NodeList>` An id, an element reference, or a collection of ids and/or elements to assign the listener to.
  `sType <String>` The type of event to append
  `fn <Function>` The method the event invokes
  `obj <Object>` An arbitrary object that will be passed as a parameter to the handler
  `overrideContext <Boolean|object>` If true, the obj passed in becomes the execution context of the listener. If an object, this object becomes the execution context.
  `capture <boolen>` capture or bubble phase

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.

#### _createDelegate

`private static Function _createDelegate ( fn , filter , obj , overrideContext )`
Creates a delegate function used to call event listeners specified via the `YAHOO.util.Event.delegate` method.

Parameters:
  `fn <Function>` The method (event listener) to call.
  `filter <Function|string>` Function or CSS selector used to determine for what element(s) the event listener should be called.
  `obj <Object>` An arbitrary object that will be passed as a parameter to the listener.
  `overrideContext <Boolean|object>` If true, the value of the obj parameter becomes the execution context of the listener. If an object, this object becomes the execution context.

Returns: `Function`
  Function that will call the event listener specified by the `YAHOO.util.Event.delegate` method.

#### _createMouseDelegate

`private static Function _createMouseDelegate ( fn , obj , overrideContext )`
Creates a delegate function used to call mouseover and mouseleave event listeners specified via the `YAHOO.util.Event.addListener` or `YAHOO.util.Event.on` method.

Parameters:
  `fn <Function>` The method (event listener) to call
  `obj <Object>` An arbitrary object that will be passed as a parameter to the listener
  `overrideContext <Boolean|object>` If true, the value of the obj parameter becomes the execution context of the listener. If an object, this object becomes the execution context.

Returns: `Function`
  Function that will call the event listener specified by either the `YAHOO.util.Event.addListener` or `YAHOO.util.Event.on` method.

#### _getCacheIndex

`private static void _getCacheIndex ( )`
Locating the saved event handler data by function ref

Returns: `void`

#### _getScroll

`private static void _getScroll ( )`
Returns the scrollTop and scrollLeft. Used to calculate the pageX and pageY in Internet Explorer

Returns: `void`

#### _getScrollLeft

`private static void _getScrollLeft ( )`
Returns scrollLeft

Returns: `void`

#### _getScrollTop

`private static void _getScrollTop ( )`
Returns scrollTop

Returns: `void`

#### _getType

`private void _getType ( sType )`
Checks to see if the type requested is a special type (as defined by the _specialTypes hash), and (if so) returns the special type name.

Parameters:
  `sType <String>` The type to look up

Returns: `void`

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

#### _load

`private static void _load ( )`
hook up any deferred listeners

Returns: `void`

#### _ready

`private static void _ready ( )`
Fires the DOMReady event listeners the first time the document is usable.

Returns: `void`

#### _simpleAdd

`private static void _simpleAdd ( el , sType , fn , capture )`
Adds a DOM event directly without the caching, cleanup, context adj, etc

Parameters:
  `el <HTMLElement>` the element to bind the handler to
  `sType <string>` the type of event handler
  `fn <function>` the callback to invoke
  `capture <boolen>` capture or bubble phase

Returns: `void`

#### _simpleRemove

`private static void _simpleRemove ( el , sType , fn , capture )`
Basic remove listener

Parameters:
  `el <HTMLElement>` the element to bind the handler to
  `sType <string>` the type of event handler
  `fn <function>` the callback to invoke
  `capture <boolen>` capture or bubble phase

Returns: `void`

#### _tryPreloadAttach

`private static void _tryPreloadAttach ( )`
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`

#### addBlurListener

`static Boolean addBlurListener ( el , fn , obj , overrideContext )`
Attaches a focusout event listener to the specified element for the purpose of listening for the blur event on the element's descendants.

Parameters:
  `el <String|HTMLElement|Array|NodeList>` An id, an element reference, or a collection of ids and/or elements to assign the listener to.
  `fn <Function>` The method the event invokes
  `obj <Object>` An arbitrary object that will be passed as a parameter to the handler
  `overrideContext <Boolean|object>` If true, the obj passed in becomes the execution context of the listener. If an object, this object becomes the execution context.

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.

Deprecated use YAHOO.util.Event.on and specify "focusout" as the event type.

#### addFocusListener

`static Boolean addFocusListener ( el , fn , obj , overrideContext )`
Attaches a focusin event listener to the specified element for the purpose of listening for the focus event on the element's descendants.

Parameters:
  `el <String|HTMLElement|Array|NodeList>` An id, an element reference, or a collection of ids and/or elements to assign the listener to.
  `fn <Function>` The method the event invokes
  `obj <Object>` An arbitrary object that will be passed as a parameter to the handler
  `overrideContext <Boolean|object>` If true, the obj passed in becomes the execution context of the listener. If an object, this object becomes the execution context.

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.

Deprecated use YAHOO.util.Event.on and specify "focusin" as the event type.

#### addListener

`static Boolean addListener ( el , sType , fn , obj , overrideContext )`
Appends an event handler

Parameters:
  `el <String|HTMLElement|Array|NodeList>` An id, an element reference, or a collection of ids and/or elements to assign the listener to.
  `sType <String>` The type of event to append
  `fn <Function>` The method the event invokes
  `obj <Object>` An arbitrary object that will be passed as a parameter to the handler
  `overrideContext <Boolean|object>` If true, the obj passed in becomes the execution context of the listener. If an object, this object becomes the execution context.

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.

#### clearCache

`private static void clearCache ( )`
Clears the element cache

Returns: `void`

Deprecated Elements are not cached any longer

#### delegate

`static Boolean delegate ( container , type , fn , filter , obj , overrideContext )`
Appends a delegated event listener. Delegated event listeners receive three arguments by default: the DOM event, the element specified by the filtering function or CSS selector, and the container element (the element to which the event listener is bound). (Note: Using the delegate method requires the event-delegate module. Using CSS selectors as the filtering criteria for delegated event listeners requires inclusion of the Selector Utility.)

Parameters:
  `container <String|HTMLElement|Array|NodeList>` An id, an element reference, or a collection of ids and/or elements to assign the listener to.
  `type <String>` The type of event listener to append
  `fn <Function>` The method the event invokes
  `filter <Function|string>` Function or CSS selector used to determine for what element(s) the event listener should be called. When a function is specified, the function should return an HTML element. Using a CSS Selector requires the inclusion of the CSS Selector Utility.
  `obj <Object>` An arbitrary object that will be passed as a parameter to the listener
  `overrideContext <Boolean|object>` If true, the value of the obj parameter becomes the execution context of the listener. If an object, this object becomes the execution context.

Returns: `Boolean`
  Returns 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.

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

#### getCharCode

`static int getCharCode ( ev )`
Returns the charcode for an event

Parameters:
  `ev <Event>` the event

Returns: `int`
  the event's charCode

#### getEl

`private static void getEl ( )`
We cache elements bound by id because when the unload event fires, we can no longer use document.getElementById

Returns: `void`

Deprecated Elements are not cached any longer

#### getEvent

`static Event getEvent ( e , boundEl )`
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
  `boundEl <HTMLElement>` the element the listener is attached to

Returns: `Event`
  the event

#### getListeners

`static Object getListeners ( el , sType )`
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
  `sType <string>` optional type of listener to return. If left out, all listeners will be returned

Returns: `Object`
  the listener. Contains the following fields: type: (string) the type of event fn: (function) the callback supplied to addListener obj: (object) the custom object supplied to addListener adjust: (boolean|object) whether or not to adjust the default context scope: (boolean) the derived context based on the adjust parameter index: (int) its position in the Event util listener cache

#### getPageX

`static int getPageX ( ev )`
Returns the event's pageX

Parameters:
  `ev <Event>` the event

Returns: `int`
  the event's pageX

#### getPageY

`static int getPageY ( ev )`
Returns the event's pageY

Parameters:
  `ev <Event>` the event

Returns: `int`
  the event's pageY

#### getRelatedTarget

`static HTMLElement getRelatedTarget ( ev )`
Returns the event's related target

Parameters:
  `ev <Event>` the event

Returns: `HTMLElement`
  the event's relatedTarget

#### getTarget

`static HTMLElement getTarget ( ev , resolveTextNode )`
Returns the event's target element. Safari sometimes provides a text node, and this is automatically resolved to the text node's parent so that it behaves like other browsers.

Parameters:
  `ev <Event>` the event
  `resolveTextNode <boolean>` when set to true the target's parent will be returned if the target is a text node. @deprecated, the text node is now resolved automatically

Returns: `HTMLElement`
  the event's target

#### getTime

`static Date getTime ( ev )`
Returns the time of the event. If the time is not included, the event is modified using the current time.

Parameters:
  `ev <Event>` the event

Returns: `Date`
  the time of the event

#### getXY

`static [x, y] getXY ( ev )`
Returns the pageX and pageY properties as an indexed array.

Parameters:
  `ev <Event>` the event

Returns: `[x, y]`
  the pageX and pageY properties of the event

#### on

`static void on ( )`
YAHOO.util.Event.on is an alias for addListener

Returns: `void`

#### onAvailable

`static void onAvailable ( id , fn , obj , overrideContext , 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.
  `obj <object>` an optional object to be passed back as a parameter to fn.
  `overrideContext <boolean|object>` If set to true, fn will execute in the context of obj, if set to an object it will execute in the context of that object
  `checkContent <boolean>` check child node readiness (onContentReady)

Returns: `void`

#### onBlur

`static void onBlur ( )`
YAHOO.util.Event.onBlur is an alias for addBlurListener

Returns: `void`

Deprecated use YAHOO.util.Event.on and specify "focusout" as the event type.

#### onContentReady

`static void onContentReady ( id , fn , obj , overrideContext )`
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.
  `overrideContext <boolean|object>` If set to true, fn will execute in the context of obj. If an object, fn will exectute in the context of that object

Returns: `void`

#### onDOMReady

`static void onDOMReady ( fn , obj , overrideContext )`
Executes the supplied callback when the DOM is first usable. This will execute immediately if called after the DOMReady event has fired. @todo the DOMContentReady event does not fire when the script is dynamically injected into the page. This means the DOMReady custom event will never fire in FireFox or Opera when the library is injected. It _will_ fire in Safari, and the IE implementation would allow for us to fire it if the defered script is not available. We want this to behave the same in all browsers. Is there a way to identify when the script has been injected instead of included inline? Is there a way to know whether the window onload event has fired without having had a listener attached to it when it did so?

The callback is a CustomEvent, so the signature is:

type <string>, args <array>, customobject <object>

For DOMReady events, there are no fire argments, so the signature is:

"DOMReady", [], obj

Parameters:
  `fn <function>` what to execute when the element is found.
  `obj <object>` an optional object to be passed back as a parameter to fn.
  `overrideContext <boolean|object>` If set to true, fn will execute in the context of obj, if set to an object it will execute in the context of that object

Returns: `void`

#### onFocus

`static void onFocus ( )`
YAHOO.util.Event.onFocus is an alias for addFocusListener

Returns: `void`

Deprecated use YAHOO.util.Event.on and specify "focusin" as the event type.

#### preventDefault

`static void preventDefault ( ev )`
Prevents the default behavior of the event

Parameters:
  `ev <Event>` the event

Returns: `void`

#### purgeElement

`static void purgeElement ( el , recurse , sType )`
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.
  `sType <string>` optional type of listener to purge. If left out, all listeners will be removed

Returns: `void`

#### regCE

`private static void regCE ( )`
Used by old versions of CustomEvent, restored for backwards compatibility

Returns: `void`

Deprecated still here for backwards compatibility

#### removeBlurListener

`static boolean removeBlurListener ( el , fn )`
Removes a focusout event listener to the specified element for the purpose of listening for the blur event on the element's descendants.

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

Deprecated use YAHOO.util.Event.removeListener and specify "focusout" as the event type.

#### removeDelegate

`static boolean removeDelegate ( container , type , fn )`
Removes a delegated event listener.

Parameters:
  `container <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 listeners for the type of event are removed.

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

#### removeFocusListener

`static boolean removeFocusListener ( el , fn )`
Removes a focusin event listener to the specified element for the purpose of listening for the focus event on the element's descendants.

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

Deprecated use YAHOO.util.Event.removeListener and specify "focusin" as the event type.

#### removeListener

`static boolean removeListener ( el , sType , fn )`
Removes an event listener

Parameters:
  `el <String|HTMLElement|Array|NodeList>` An id, an element reference, or a collection of ids and/or elements to remove the listener from.
  `sType <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.

#### resolveTextNode

`static HTMLElement resolveTextNode ( node )`
In some cases, some browsers will return a text node inside the actual element that was targeted. This normalizes the return value for getTarget and getRelatedTarget.

Parameters:
  `node <HTMLElement>` node to resolve

Returns: `HTMLElement`
  the normized node

#### startInterval

`private static void startInterval ( )`

Returns: `void`

#### stopEvent

`static void stopEvent ( ev )`
Convenience method for stopPropagation + preventDefault

Parameters:
  `ev <Event>` the event

Returns: `void`

#### stopPropagation

`static void stopPropagation ( ev )`
Stops event propagation

Parameters:
  `ev <Event>` the event

Returns: `void`

### Events

#### DOMReadyEvent

`DOMReadyEvent ( )`
Custom event the fires when the dom is initially usable

Copyright © 2009 Yahoo! Inc. All rights reserved.