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

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

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

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

yui-ext - Copyright © 2006 Jack Slocum. | Yahoo! UI - Copyright © 2006 Yahoo! Inc.
All rights reserved.