Yahoo! UI Library

event  3.0.0pr2

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

_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

loadComplete - private static boolean

True after the onload event has fired

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

webkitKeymap - private object

webkit key remapping required for Safari < 3.1

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

_load

private static void _load ( )
hook up any deferred listeners
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

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> 1..n ar
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.

click

static void click ( target , options )
Simulates a click on a particular element.
Parameters:
target <HTMLElement> The element to click on.
options <Object> Additional event options (use DOM standard names).
Returns: void

dblclick

static void dblclick ( target , options )
Simulates a double click on a particular element.
Parameters:
target <HTMLElement> The element to double click on.
options <Object> Additional event options (use DOM standard names).
Returns: void

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)

keydown

static void keydown ( target , options )
Simulates a keydown event on a particular element.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

keypress

static void keypress ( target , options )
Simulates a keypress on a particular element.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

keyup

static void keyup ( target , options )
Simulates a keyup event on a particular element.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

mousedown

static void mousedown ( target , options )
Simulates a mousedown on a particular element.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

mousemove

static void mousemove ( target , options )
Simulates a mousemove on a particular element.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

mouseout

static void mouseout ( target , options )
Simulates a mouseout event on a particular element. Use "relatedTarget" on the options object to specify where the mouse moved to. Quirks: Firefox less than 2.0 doesn't set relatedTarget properly, so toElement is assigned in its place. IE doesn't allow toElement to be be assigned, so relatedTarget is assigned in its place. Both of these concessions allow YAHOO.util.Event.getRelatedTarget() to work correctly in both browsers.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

mouseover

static void mouseover ( target , options )
Simulates a mouseover event on a particular element. Use "relatedTarget" on the options object to specify where the mouse moved from. Quirks: Firefox less than 2.0 doesn't set relatedTarget properly, so fromElement is assigned in its place. IE doesn't allow fromElement to be be assigned, so relatedTarget is assigned in its place. Both of these concessions allow YAHOO.util.Event.getRelatedTarget() to work correctly in both browsers.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

mouseup

static void mouseup ( target , options )
Simulates a mouseup on a particular element.
Parameters:
target <HTMLElement> The element to act on.
options <Object> Additional event options (use DOM standard names).
Returns: void

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

resolve

private void resolve ( )
Returns a wrapped node. Intended to be used on event targets, so it will return the node's parent if the target is a text node
Returns: void

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.
Returns: void

simulateKeyEvent

private static void simulateKeyEvent ( target , type , bubbles , cancelable , view , ctrlKey , altKey , shiftKey , metaKey , keyCode , charCode )
Note: Intentionally not for YUIDoc generation. Simulates a key event using the given event information to populate the generated event object. This method does browser-equalizing calculations to account for differences in the DOM and IE event models as well as different browser quirks. Note: keydown causes Safari 2.x to crash.
Parameters:
target <HTMLElement> The target of the given event.
type <String> The type of event to fire. This can be any one of the following: keyup, keydown, and keypress.
bubbles <Boolean> (Optional) Indicates if the event can be bubbled up. DOM Level 3 specifies that all key events bubble by default. The default is true.
cancelable <Boolean> (Optional) Indicates if the event can be canceled using preventDefault(). DOM Level 3 specifies that all key events can be cancelled. The default is true.
view <Window> (Optional) The view containing the target. This is typically the window object. The default is window.
ctrlKey <Boolean> (Optional) Indicates if one of the CTRL keys is pressed while the event is firing. The default is false.
altKey <Boolean> (Optional) Indicates if one of the ALT keys is pressed while the event is firing. The default is false.
shiftKey <Boolean> (Optional) Indicates if one of the SHIFT keys is pressed while the event is firing. The default is false.
metaKey <Boolean> (Optional) Indicates if one of the META keys is pressed while the event is firing. The default is false.
keyCode <int> (Optional) The code for the key that is in use. The default is 0.
charCode <int> (Optional) The Unicode code for the character associated with the key being used. The default is 0.
Returns: void

startInterval

private static void startInterval ( )
Returns: void
Copyright © 2008 Yahoo! Inc. All rights reserved.