API: event YAHOO.util.CustomEvent (YUI Library)

# Yahoo! UI Library

### Event Utility 2.9.0

Yahoo! UI Library > event > YAHOO.util.CustomEvent
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.util.CustomEvent

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

### Constructor

YAHOO.util.CustomEvent `( type , context , silent , signature , fireOnce )`

Parameters:
  `type <String>` The type of event, which is passed to the callback when the event fires
  `context <Object>` The context the event will fire from. "this" will refer to this object in the callback. Default value: the window object. The listener can override this.
  `silent <boolean>` pass true to prevent the event from writing to the debugsystem
  `signature <int>` the signature that the custom event subscriber will receive. YAHOO.util.CustomEvent.LIST or YAHOO.util.CustomEvent.FLAT. The default is YAHOO.util.CustomEvent.LIST.
  `fireOnce <boolean>` If configured to fire once, the custom event will only notify subscribers a single time regardless of how many times the event is fired. In addition, new subscribers will be notified immediately if the event has already been fired.

### Properties

#### fired - `boolean`

Indicates whether or not this event has ever been fired.
Default Value: false

#### firedWith - `Array`

For fireOnce events the arguments the event was fired with are stored so that new subscribers get the proper payload.

#### fireOnce - `boolean`

If configured to fire once, the custom event will only notify subscribers a single time regardless of how many times the event is fired. In addition, new subscribers will be notified immediately if the event has already been fired.
Default Value: false

#### lastError - `Error`

In order to make it possible to execute the rest of the subscriber stack when one thows an exception, the subscribers exceptions are caught. The most recent exception is stored in this property

#### scope - `object`

The context the event will fire from by default. Defaults to the window obj.

#### signature - `int`

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

#### silent - `boolean`

By default all custom events are logged in the debug build. Set silent to true to disable debug output for this event.

#### subscribers - `Subscriber[]`

The subscribers to this event

#### type - `string`

The type of event, returned to subscribers when the event fires

#### YAHOO.util.CustomEvent.FLAT - `static int`

Subscriber listener sigature constant. The FLAT type returns two parameters: the first argument passed to fire and the optional custom object

#### YAHOO.util.CustomEvent.LIST - `static int`

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

### Methods

#### _delete

`private void _delete ( )`

#### fire

`boolean fire ( arguments )`
Notifies the subscribers. The callback functions will be executed from the context 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: `boolean`
  false if one of the subscribers returned false, true otherwise

#### subscribe

`void subscribe ( fn , obj , overrideContext )`
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.
  `overrideContext <boolean|Object>` If true, the obj passed in becomes the execution. context of the listener. If an object, that object becomes the execution context.

#### toString

`void toString ( )`

#### unsubscribe

`boolean unsubscribe ( fn , obj )`
Unsubscribes subscribers.

Parameters:
  `fn <Function>` The subscribed function to remove, if not supplied all will be removed
  `obj <Object>` The custom object passed to subscribe. This is optional, but if supplied will be used to disambiguate multiple listeners that are the same (e.g., you subscribe many object using a function that lives on the prototype)

Returns: `boolean`
  True if the subscriber was found and detached.

#### unsubscribeAll

`int unsubscribeAll ( )`
Removes all listeners

Returns: `int`
  The number of listeners unsubscribed

### Events

#### subscribeEvent

`subscribeEvent ( fn , obj , override )`
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.

Parameters:
  `fn <Function>` The function to execute
  `obj <object>`
  `override <object>` If true, the obj passed in becomes the execution context of the listener. If an object, that object becomes the execution context. Defaults to the custom event.

Copyright © 2011 Yahoo! Inc. All rights reserved.