Print Friendly

# Class YAHOO.util.Event

Package: | YAHOO.util
Class: | Event
Extends: | Object
Defined In: | event.js

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.

## Public Properties

Property | Defined By
--- | ---
| ADJ_SCOPE : int | Event
<static> Adjusted scope, either the element we are registering the event on or the custom object passed in by t...
| EL : int | Event
<static> Element to bind, int constant
| FN : int | Event
<static> Function to execute, int constant
| OBJ : int | Event
<static> Object passed in by the user that will be returned as a parameter to the callback, int constant
| POLL_INTERVAL : int | Event
<static> The poll interval in milliseconds
| POLL_RETRYS : int | Event
<static> The number of times we should look for elements that are not in the DOM at the time the event is reque...
| TYPE : int | Event
<static> Type of event, int constant
| WFN : int | Event
<static> Function wrapped for scope correction and cleanup, int constant

## Public Methods

Method | Defined By
--- | ---
| addListener(`Object el`, `String sType`, `Function fn`, `Object obj`, `boolean override`) : boolean | Event
<static> Appends an event handler
| createEvent(`p_type {string}`, `p_config {object}`) : CustomEvent | Event
Creates a new custom event of the specified type. If a custom event by that name already exists, it will not be re-c...
| fireEvent(`p_type {string}`, `arguments {Object*}`) : boolean | Event
Fire a custom event by name. The callback functions will be executed from the scope specified when the event was cre...
| generateId(`el the`) : string | Event
<static> Generates an unique ID for the element if it does not already have one.
| getCharCode(`Event ev`) : int | Event
<static> Returns the charcode for an event
| getEvent(`Event e`) : Event | Event
<static> Finds the event in the window object, the caller's arguments, or in the arguments of another method in...
| getListeners(`el {HTMLElement}`, `sType {string}`) : Object | Event
<static> Returns all listeners attached to the given element via addListener. Optionally, you can specify a spe...
| getPageX(`Event ev`) : int | Event
<static> Returns the event's pageX
| getPageY(`Event ev`) : int | Event
<static> Returns the event's pageY
| getRelatedTarget(`Event ev`) : HTMLElement | Event
<static> Returns the event's related target
| getTarget(`Event ev`, `boolean resolveTextNode`) : HTMLElement | Event
Deprecated. <static> Returns the event's target element
| getTime(`Event ev`) : Date | Event
<static> Returns the time of the event. If the time is not included, the event is modified using the current t...
| getXY() : void | Event
<static> Returns the pageX and pageY properties as an indexed array.
| hasEvent(`type {string}`) : void | Event
Returns true if the custom event of the provided type has been created with createEvent.
| on() : void | Event
<static> YAHOO.util.Event.on is an alias for addListener
| onAvailable(`string p_id`, `function p_fn`, `object p_obj`, `boolean p_override`) : void | Event
<static> Executes the supplied callback when the item with the supplied id is found. This is meant to be used ...
| onContentReady(`string p_id`, `function p_fn`, `object p_obj`, `boolean p_override`) : void | Event
<static> Works the same way as onAvailable, but additionally checks the state of sibling elements to determine ...
| preventDefault(`Event ev`) : void | Event
<static> Prevents the default behavior of the event
| purgeElement(`HTMLElement el`, `boolean recurse`, `string sType`) : void | Event
<static> Removes all listeners attached to the given element via addListener. Optionally, the node's children c...
| removeListener(`Object el`, `String sType`, `Function fn`) : boolean | Event
<static> Removes an event handler
| resolveTextNode(`HTMLElement node`) : HTMLElement | Event
<static> In some cases, some browsers will return a text node inside the actual element that was targeted. Thi...
| stopEvent(`Event ev`) : void | Event
<static> Convenience method for stopPropagation + preventDefault
| stopPropagation(`Event ev`) : void | Event
<static> Stops event propagation
| subscribe(`p_type {string}`, `p_fn {function}`, `p_obj` , `p_obj {Object}`, `p_override {boolean}`) : void | Event
Subscribe to a CustomEvent by event type
| unsubscribe(`p_type {string}`, `p_fn {Function}`, [`p_obj {Object}`]) : boolean | Event
Unsubscribes the from the specified event

## Public Events

This class has no public events.

## Property Details

### ADJ_SCOPE

`public int ADJ_SCOPE`
<static> Adjusted scope, either the element we are registering the event on or the custom object passed in by the listener, int constant
This property is defined by Event.

### EL

`public int EL`
<static> Element to bind, int constant
This property is defined by Event.

### FN

`public int FN`
<static> Function to execute, int constant
This property is defined by Event.

### OBJ

`public int OBJ`
<static> Object passed in by the user that will be returned as a parameter to the callback, int constant
This property is defined by Event.

### POLL_INTERVAL

`public int POLL_INTERVAL`
<static> The poll interval in milliseconds
This property is defined by Event.

### POLL_RETRYS

`public int POLL_RETRYS`
<static> 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 200@amp;50 ms, so it will poll for 10 seconds or until all outstanding handlers are bound (whichever comes first).
This property is defined by Event.

### TYPE

`public int TYPE`
<static> Type of event, int constant
This property is defined by Event.

### WFN

`public int WFN`
<static> Function wrapped for scope correction and cleanup, int constant
This property is defined by Event.

## Method Details

### addListener

`public function addListener(`Object el`, `String sType`, `Function fn`, `Object obj`, `boolean override`)`
<static> Appends an event handler
Parameters:

- `el` : Object
  The html element to assign the event 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
  If true, the obj passed in becomes the execution scope of the listener

Returns:

- `boolean`
  True if the action was successful or defered, false if one or more of the elements could not have the event bound to it.

This method is defined by Event.

### createEvent

`public function createEvent(`p_type {string}`, `p_config {object}`)`
Creates a new custom event of the specified type. If a custom event by that name already exists, it will not be re-created. In either case the custom event is returned.
Parameters:

- `{string}` : p_type
  the type, or name of the event
- `{object}` : p_config
  optional config params. Valid properties are:
  - scope: defines the default execution scope. If not defined the default scope will be this instance.
  - silent: if true, the custom event will not generate log messages. This is false by default.
  - onSubscribeCallback: specifies a callback to execute when the event has a new subscriber. This will fire immediately for each queued subscriber if any exist prior to the creation of the event.

Returns:

- `CustomEvent`
  the custom event

This method is defined by Event.

### fireEvent

`public function fireEvent(`p_type {string}`, `arguments {Object*}`)`
Fire a custom event by name. The callback functions will be executed from the scope specified when the event was created, and with the following parameters:

- The first argument fire() was executed with
- The custom object (if any) that was passed into the subscribe() method

Parameters:

- `{string}` : p_type
  the type, or name of the event
- `{Object*}` : arguments
  an arbitrary set of parameters to pass to the handler.

Returns:

- `boolean`
  the return value from CustomEvent.fire, or null if the custom event does not exist.

This method is defined by Event.

### generateId

`public function generateId(`el the`)`
<static> Generates an unique ID for the element if it does not already have one.
Parameters:

- `the` : el
  element to create the id for

Returns:

- `string`
  the resulting id of the element

This method is defined by Event.

### getCharCode

`public function getCharCode(`Event ev`)`
<static> Returns the charcode for an event
Parameters:

- `ev` : Event
  the event

Returns:

- `int`
  the event's charCode

This method is defined by Event.

### getEvent

`public function getEvent(`Event e`)`
<static> 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

Returns:

- `Event`
  the event

This method is defined by Event.

### getListeners

`public function getListeners(`el {HTMLElement}`, `sType {string}`)`
<static> Returns all listeners attached to the given element via addListener. Optionally, you can specify a specific type of event to return.
Parameters:

- `{HTMLElement}` : el
  the element to inspect
- `{string}` : sType
  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) whether or not to adjust the default scope index: (int) its position in the Event util listener cache

This method is defined by Event.

### getPageX

`public function getPageX(`Event ev`)`
<static> Returns the event's pageX
Parameters:

- `ev` : Event
  the event

Returns:

- `int`
  the event's pageX

This method is defined by Event.

### getPageY

`public function getPageY(`Event ev`)`
<static> Returns the event's pageY
Parameters:

- `ev` : Event
  the event

Returns:

- `int`
  the event's pageY

This method is defined by Event.

### getRelatedTarget

`public function getRelatedTarget(`Event ev`)`
<static> Returns the event's related target
Parameters:

- `ev` : Event
  the event

Returns:

- `HTMLElement`
  the event's relatedTarget

This method is defined by Event.

### getTarget

`public function getTarget(`Event ev`, `boolean resolveTextNode`)`
Deprecated. <static> Returns the event's target element
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.

Returns:

- `HTMLElement`
  the event's target

This method is defined by Event.

### getTime

`public function getTime(`Event ev`)`
<static> 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

This method is defined by Event.

### getXY

`public function getXY()`
<static> Returns the pageX and pageY properties as an indexed array.
Parameters:

- None.

Returns:

- `void`

This method is defined by Event.

### hasEvent

`public function hasEvent(`type {string}`)`
Returns true if the custom event of the provided type has been created with createEvent.
Parameters:

- `{string}` : type
  the type, or name of the event

Returns:

- `void`

This method is defined by Event.

### on

`public function on()`
<static> YAHOO.util.Event.on is an alias for addListener
Parameters:

- None.

Returns:

- `void`

This method is defined by Event.

### onAvailable

`public function onAvailable(`string p_id`, `function p_fn`, `object p_obj`, `boolean p_override`)`
<static> 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.
Parameters:

- `p_id` : string
  the id of the element 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
  If set to true, p_fn will execute in the scope of p_obj

Returns:

- `void`

This method is defined by Event.

### onContentReady

`public function onContentReady(`string p_id`, `function p_fn`, `object p_obj`, `boolean p_override`)`
<static> 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.
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
  If set to true, p_fn will execute in the scope of p_obj

Returns:

- `void`

This method is defined by Event.

### preventDefault

`public function preventDefault(`Event ev`)`
<static> Prevents the default behavior of the event
Parameters:

- `ev` : Event
  the event

Returns:

- `void`

This method is defined by Event.

### purgeElement

`public function purgeElement(`HTMLElement el`, `boolean recurse`, `string sType`)`
<static> 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`

This method is defined by Event.

### removeListener

`public function removeListener(`Object el`, `String sType`, `Function fn`)`
<static> Removes an event handler
Parameters:

- `el` : Object
  the html element or the id of the element to assign the event to.
- `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.

This method is defined by Event.

### resolveTextNode

`public function resolveTextNode(`HTMLElement node`)`
<static> 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

This method is defined by Event.

### stopEvent

`public function stopEvent(`Event ev`)`
<static> Convenience method for stopPropagation + preventDefault
Parameters:

- `ev` : Event
  the event

Returns:

- `void`

This method is defined by Event.

### stopPropagation

`public function stopPropagation(`Event ev`)`
<static> Stops event propagation
Parameters:

- `ev` : Event
  the event

Returns:

- `void`

This method is defined by Event.

### subscribe

`public function subscribe(`p_type {string}`, `p_fn {function}`, `p_obj` , `p_obj {Object}`, `p_override {boolean}`)`
Subscribe to a CustomEvent by event type
Parameters:

- `{string}` : p_type
  the type, or name of the event
- `{function}` : p_fn
  the function to exectute when the event fires
- `` : p_obj
- `{Object}` : p_obj
  An object to be passed along when the event fires
- `{boolean}` : p_override
  If true, the obj passed in becomes the execution scope of the listener

Returns:

- `void`

This method is defined by Event.

### unsubscribe

`public function unsubscribe(`p_type {string}`, `p_fn {Function}`, [`p_obj {Object}`])`
Unsubscribes the from the specified event
Parameters:

- `{string}` : p_type
  The type, or name of the event
- `{Function}` : p_fn
  The function to execute
- `{Object}` : p_obj
  The custom object passed to subscribe (optional)

Returns:

- `boolean`
  true if the subscriber was found and detached.

This method is defined by Event.

Copyright © 2006 Jack Slocum. All rights reserved.