# Yahoo! UI Library

### event 3.3.0

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 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 SyntheticEvent Event.define ( type , config , force )`

Defines a new event in the DOM event system. Implementers are responsible for monitoring for a scenario whereby the event is fired. A notifier object is provided to the functions identified below. When the criteria defining the event are met, call notifier.fire( [args] ); to execute event subscribers.

The first parameter is the name of the event. The second parameter is a configuration object which define the behavior of the event system when the new event is subscribed to or detached from. The methods that should be defined in this configuration object are `on`, `detach`, `delegate`, and `detachDelegate`. You are free to define any other methods or properties needed to define your event. Be aware, however, that since the object is used to subclass SyntheticEvent, you should avoid method names used by SyntheticEvent unless your intention is to override the default behavior.

This is a list of properties and methods that you can or should specify in the configuration object:

`on`
  `function (node, subscription, notifier)` 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 state on the `subscription` object. When the criteria have been met to fire the synthetic event, call `notifier.fire(e)`. See Notifier's `fire()` method for details about what to pass as parameters.
`detach`
  `function (node, subscription, notifier)` The implementation logic for cleaning up a detached subscription. E.g. detach any DOM subscriptions added in `on`.
`delegate`
  `function (node, subscription, notifier, filter)` The implementation logic for subscription via `Y.delegate` or `node.delegate`. The filter is typically either a selector string or a function. You can use `Y.delegate.compileFilter(selectorString)` to create a filter function from a selector string if needed. The filter function expects an event object as input and should output either null, a matching Node, or an array of matching Nodes. Otherwise, this acts like `on` 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 `notifier.fire(e)` as noted above.
`detachDelegate`
  `function (node, subscription, notifier)` The implementation logic for cleaning up a detached delegate subscription. E.g. detach any DOM delegate subscriptions added in `delegate`.
`publishConfig`
  (Object) The configuration object that will be used to instantiate the underlying CustomEvent. See Notifier's `fire` method for details.
`processArgs`

`function (argArray, fromDelegate)` Optional method to extract any additional arguments from the subscription signature. Using this allows `on` or `delegate` signatures like `node.on("hover", overCallback, outCallback)`.

When processing an atypical argument signature, make sure the args array is returned to the normal signature before returning from the function. For example, in the "hover" example above, the `outCallback` needs to be `splice`d out of the array. The expected signature of the args array for `on()` subscriptions is:

    [type, callback, target, contextOverride, argN...]

And for `delegate()`:

    [type, callback, target, filter, contextOverride, argN...]

where `target` is the node the event is being subscribed for. You can see these signatures documented for `Y.on()` and `Y.delegate()` respectively.

Whatever gets returned from the function will be stored on the `subscription` object under `subscription._extra`.

`subMatch`

  `function (sub, args)` Compares a set of subscription arguments against a Subscription object to determine if they match. The default implementation compares the callback function against the second argument passed to `Y.on(...)` or `node.detach(...)` etc.

Parameters:
  `type <String>` the name of the event
  `config <Object>` the prototype definition for the new event (see above)
  `force <Boolean>` override an existing event (use with caution)

Returns: `SyntheticEvent`
  the subclass implementation instance created to handle event subscriptions of this type

#### 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 , obj , 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.
  `obj <object>` an optional object to be passed back as a parameter to fn.
  `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

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

#### startInterval

`private static void startInterval ( )`

Copyright © 2011 Yahoo! Inc. All rights reserved.