Yahoo! UI Library

Event Utility  2.6.0

Yahoo! UI Library > event > YAHOO.util.Event

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

ADJ_SCOPE - static final int

Adjusted scope, 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

legacyEvents - private static object

Cache of DOM0 event handlers to work around issues with DOM2 events in Safari

legacyHandlers - private static object

Listener stack for DOM0 events

legacyMap - private static object

Lookup table for legacy events

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 scope 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 2000@amp;20 ms, so it will poll for 40 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 scope correction and cleanup, int constant

Methods

_addListener

private static Boolean _addListener ( el , sType , fn , obj , override , 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
override <Boolean|object> If true, the obj passed in becomes the execution scope of the listener. If an object, this object becomes the execution scope.
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.

_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

_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

_removeListener

private static boolean _removeListener ( el , sType , fn , capture )
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.
capture <boolen> capture or bubble phase
Returns: boolean
true if the unbind was successful, false otherwise.

_simpleAdd

private static void _simpleAdd ( el , sType , fn , capture )
Adds a DOM event directly without the caching, cleanup, scope 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 , override )
Appends a blur event handler. (The focusout event is used for Internet Explorer, the focusout, capture-event for Opera, WebKit, and Gecko.)
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
override <Boolean|object> If true, the obj passed in becomes the execution scope of the listener. If an object, this object becomes the execution scope.
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.

addFocusListener

static Boolean addFocusListener ( el , fn , obj , override )
Appends a focus event handler. (The focusin event is used for Internet Explorer, the focus, capture-event for Opera, WebKit, and Gecko.)
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
override <Boolean|object> If true, the obj passed in becomes the execution scope of the listener. If an object, this object becomes the execution scope.
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.

addListener

static Boolean addListener ( el , sType , fn , obj , override )
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
override <Boolean|object> If true, the obj passed in becomes the execution scope of the listener. If an object, this object becomes the execution scope.
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

fireLegacyEvent

private static void fireLegacyEvent ( )
When using legacy events, the handler is routed to this object so we can fire our custom listener stack.
Returns: void

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

getLegacyIndex

private static void getLegacyIndex ( )
Returns the legacy event index that matches the supplied signature
Returns: void

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 scope   scope: (boolean) the derived scope based on the adjust parameter   scope: (capture) the capture parameter supplied to addListener   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 ( p_id , p_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:
p_id <string||string[]> the id of the element, or an array of ids to look for.
p_fn <function> what to execute when the element is found.
p_obj <object> an optional object to be passed back as a parameter to p_fn.
p_override <boolean|object> If set to true, p_fn will execute in the scope of p_obj, if set to an object it will execute in the scope 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

onContentReady

static void onContentReady ( p_id , p_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:
p_id <string> the id of the element to look for.
p_fn <function> what to execute when the element is ready.
p_obj <object> an optional object to be passed back as a parameter to p_fn.
p_override <boolean|object> If set to true, p_fn will execute in the scope of p_obj. If an object, p_fn will exectute in the scope of that object
Returns: void

onDOMReady

static void onDOMReady ( p_fn , p_obj , p_scope )
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:
p_fn <function> what to execute when the element is found.
p_obj <object> an optional object to be passed back as a parameter to p_fn.
p_scope <boolean|object> If set to true, p_fn will execute in the scope of p_obj, if set to an object it will execute in the scope of that object
Returns: void

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

removeFocusListener

static boolean removeFocusListener ( el , fn )
Removes a focus 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.
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.

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

useLegacyEvent

private static void useLegacyEvent ( )
Logic that determines when we should automatically use legacy events instead of DOM2 events. Currently this is limited to old Safari browsers with a broken preventDefault
Returns: void

Events

DOMReadyEvent

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

Modules

Classes

Files

Properties

Methods

Events

Copyright © 2008 Yahoo! Inc. All rights reserved.