# Yahoo! UI Library

### Event Utility 2.2.2

Yahoo! UI Library > event > YAHOO.util.CustomEvent

## 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 , oScope , silent , signature )`

Parameters:
  `type <String>` The type of event, which is passed to the callback when the event fires
  `oScope <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.

### Properties

#### scope `- object`

The scope the 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: <optional> 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: <optional> 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 outpu 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 ( )`

Returns: `void`

#### fire

`boolean fire ( 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: `boolean`
  false if one of the subscribers returned false, true otherwise

#### subscribe

`void subscribe ( fn , obj , 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`

#### toString

`void toString ( )`

Returns: `void`

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

Copyright © 2007 Yahoo! Inc. All rights reserved.