Print Friendly

# Class YAHOO.util.CustomEvent

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

The CustomEvent class lets you define events for your application that can be subscribed to by one or more independent component.

## Public Properties

Property | Defined By
--- | ---
| FLAT<static> : int | CustomEvent
<static> Subscriber listener sigature constant. The FLAT type returns two parameters: the first argument passe...
| LIST<static> : int | CustomEvent
<static> Subscriber listener sigature constant. The LIST type returns three parameters: the event type, the ar...
| scope : object | CustomEvent
The scope the the event will fire from by default. Defaults to the window obj
| signature : int | CustomEvent
Custom events support two styles of arguments provided to the event subscribers. YAHOO.util.CustomEvent.LIST: pa...
| silent : boolean | CustomEvent
By default all custom events are logged in the debug build, set silent to true to disable logging for this event.
| subscribers : Subscriber[] | CustomEvent
The subscribers to this event
| type : string | CustomEvent
The type of event, returned to subscribers when the event fires

## Public Methods

Method | Defined By
--- | ---
| CustomEvent() | CustomEvent
| fire(`Object* arguments`) : void | CustomEvent
Notifies the subscribers. The callback functions will be executed from the scope specified when the event was create...
| subscribe(`Function fn`, `Object obj`, `boolean|Object override`) : void | CustomEvent
Subscribes the caller to this event
| toString() : void | CustomEvent
| unsubscribe(`Function fn`, [`Object obj`]) : boolean | CustomEvent
Unsubscribes the caller from this event
| unsubscribeAll() : void | CustomEvent
Removes all listeners

## Public Events

Event | Defined By
--- | ---
| subscribeEvent : (`Function fn`, `Object obj`, `boolean|Object override`) | CustomEvent
Custom events provide a custom event that fires whenever there is a new subscriber to the event. This provides an op...

## Property Details

### FLAT<static>

`public int FLAT<static>`
<static> Subscriber listener sigature constant. The FLAT type returns two parameters: the first argument passed to fire and the optional custom object
This property is defined by CustomEvent.

### LIST<static>

`public int LIST<static>`
<static> Subscriber listener sigature constant. The LIST type returns three parameters: the event type, the array of args passed to fire, and the optional custom object
This property is defined by CustomEvent.

### scope

`public object scope`
The scope the the event will fire from by default. Defaults to the window obj
This property is defined by CustomEvent.

### signature

`public int signature`
Custom events support two styles of arguments provided to the event subscribers.

- YAHOO.util.CustomEvent.LIST:
  - param1: event name
  - param2: array of arguments sent to fire
  - param3: a custom object supplied by the subscriber
- YAHOO.util.CustomEvent.FLAT
  - param1: the first argument passed to fire. If you need to pass multiple parameters, use and array or object literal
  - param2: a custom object supplied by the subscriber

This property is defined by CustomEvent.

### silent

`public boolean silent`
By default all custom events are logged in the debug build, set silent to true to disable logging for this event.
This property is defined by CustomEvent.

### subscribers

`public Subscriber[] subscribers`
The subscribers to this event
This property is defined by CustomEvent.

### type

`public string type`
The type of event, returned to subscribers when the event fires
This property is defined by CustomEvent.

## Constructor Details

### CustomEvent

`public function CustomEvent()`
Parameters:

- None.

## Method Details

### fire

`public function fire(`Object* arguments`)`
Notifies the subscribers. The callback functions will be executed from the scope specified when the event was created, and with the following parameters:

- The type of event
- All of the arguments fire() was executed with as an array
- The custom object (if any) that was passed into the subscribe() method

Parameters:

- `arguments` : Object*
  an arbitrary set of parameters to pass to the handler.

Returns:

- `void`

This method is defined by CustomEvent.

### subscribe

`public function subscribe(`Function fn`, `Object obj`, `boolean|Object override`)`
Subscribes the caller to this event
Parameters:

- `fn` : Function
  The function to execute
- `obj` : Object
  An object to be passed along when the event fires
- `override` : boolean|Object
  If true, the obj passed in becomes the execution scope of the listener. if an object, that object becomes the the execution scope.

Returns:

- `void`

This method is defined by CustomEvent.

### toString

`public function toString()`
Parameters:

- None.

Returns:

- `void`

This method is defined by CustomEvent.

### unsubscribe

`public function unsubscribe(`Function fn`, [`Object obj`])`
Unsubscribes the caller from this event
Parameters:

- `fn` : Function
  The function to execute
- `obj` : Object
  The custom object passed to subscribe (optional)

Returns:

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

This method is defined by CustomEvent.

### unsubscribeAll

`public function unsubscribeAll()`
Removes all listeners
Parameters:

- None.

Returns:

- `void`

This method is defined by CustomEvent.

## Event Details

### subscribeEvent

`public event subscribeEvent`
Custom events provide a custom event that fires whenever there is a new subscriber to the event. This provides an opportunity to handle the case where there is a non-repeating event that has already fired has a new subscriber.
Subscribers will be called with the following parameters:

- `fn` : Function
  The function to execute
- `obj` : Object
  An object to be passed along when the event fires
- `override` : boolean|Object
  If true, the obj passed in becomes the execution scope of the listener. if an object, that object becomes the the execution scope.

This event is defined by CustomEvent.

Copyright © 2006 Jack Slocum. All rights reserved.