# Yahoo! UI Library

### event-custom 3.1.1

Yahoo! UI Library > event-custom > CustomEvent
Search:
Filters Show Private Show Protected Show Deprecated

## Class CustomEvent

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

### Constructor

CustomEvent `( type , o )`

Parameters:
  `type <String>` The type of event, which is passed to the callback when the event fires
  `o <object>` configuration object

### Properties

#### afters - `Subscriber{}`

'After' subscribers

#### async - `boolean`

fireOnce listeners will fire syncronously unless async is set to true
Default Value: false

#### broadcast - `int`

If 0, this event does not broadcast. If 1, the YUI instance is notified every time this event fires. If 2, the YUI instance and the YUI global (if event is enabled on the global) are notified every time this event fires.

#### bubbles - `boolean`

Specifies whether or not a subscriber can stop the event propagation via stopPropagation(), stopImmediatePropagation(), or halt() Events can only bubble if emitFacade is true.
Default Value: true

#### context - `object`

The context the the event will fire from by default. Defaults to the YUI instance.

#### defaultFn - `Function`

The default function to execute after event listeners have fire, but only if the default action was not prevented.

#### emitFacade - `boolean`

If set to true, the custom event will deliver an EventFacade object that is similar to a DOM event object.
Default Value: false

#### fired - `boolean`

This event has fired if true
Default Value: false;

#### firedWith - `Array`

An array containing the arguments the custom event was last fired with.

#### fireOnce - `boolean`

This event should only fire one time if true, and if it has fired, any new subscribers should be notified immediately.
Default Value: false;

#### host - `EventTarget`

Specifies the host for this custom event. This is used to enable event bubbling

#### monitored - `boolean`

Monitor when an event is attached or detached.

#### preventable - `boolean`

Specifies whether or not this event's default function can be cancelled by a subscriber by executing preventDefault() on the event facade
Default Value: true

#### prevented - `int`

Flag for preventDefault that is modified during fire(). if it is not 0, the default behavior for this event

#### preventedFn - `Function`

The function to execute if a subscriber calls preventDefault

#### queuable - `boolean`

Specifies whether this event should be queued when the host is actively processing an event. This will effect exectution order of the callbacks for the various events.
Default Value: false

#### signature - `int`

Supports multiple options for listener signatures in order to port YUI 2 apps.
Default Value: 9

#### silent - `boolean`

By default all custom events are logged in the debug build, set silent to true to disable debug outpu for this event.

#### stopped - `int`

Flag for stopPropagation that is modified during fire() 1 means to stop propagation to bubble targets. 2 means to also stop additional subscribers on this target.

#### stoppedFn - `Function`

The function to execute if a subscriber calls stopPropagation or stopImmediatePropagation

#### subscribers - `Subscriber{}`

The subscribers to this event

#### type - `string`

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

### Methods

#### _delete

`private void _delete ( subscriber )`

Parameters:
  `subscriber <object>` object

#### _notify

`private void _notify ( s , args )`
Notify a single subscriber

Parameters:
  `s <Subscriber>` the subscriber
  `args <Array>` the arguments array to apply to the listener

#### after

`EventHandle after ( fn , context , arg* )`
Listen for this event after the normal subscribers have been notified and the default behavior has been applied. If a normal subscriber prevents the default behavior, it also prevents after listeners from firing.

Parameters:
  `fn <Function>` The function to execute
  `context <object>` optional execution context.
  `arg* <mixed>` 0..n additional arguments to supply to the subscriber when the event fires.

Returns: `EventHandle`
  handle Unsubscribe handle

#### applyConfig

`void applyConfig ( o , force )`
Apply configuration properties. Only applies the CONFIG whitelist

Parameters:
  `o <object>` hash of properties to apply
  `force <boolean>` if true, properties that exist on the event will be overwritten.

#### detach

`int detach ( fn , context )`
Detach listeners.

Parameters:
  `fn <Function>` The subscribed function to remove, if not supplied all will be removed
  `context <Object>` The context object passed to subscribe.

Returns: `int`
  returns the number of subscribers unsubscribed

#### detachAll

`int detachAll ( )`
Removes all listeners

Returns: `int`
  The number of listeners unsubscribed

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

#### getSubs

`Array getSubs ( )`
Get all of the subscribers to this event and any sibling event

Returns: `Array`
  first item is the on subscribers, second the after

#### getSubscriber

`Subscriber getSubscriber ( fn , ctx )`
Returns the first subscriber that matches the provided function and/or context. Both function and context parameters are optional. Omitting either will return the first match on the other parameter, and omitting both will return the first subscriber.

Parameters:
  `fn <Function>` Optional. The subscribed callback function
  `ctx <Object>` Optional. The context override for the callback

Returns: `Subscriber`
  or null

#### halt

`void halt ( immediate )`
Stops the event propagation and prevents the default event behavior.

Parameters:
  `immediate <boolean>` if true additional listeners on the current target will not be executed

#### log

`void log ( msg , cat )`
Logger abstraction to centralize the application of the silent flag

Parameters:
  `msg <string>` message to log
  `cat <string>` log category

#### monitor

`EventHandle monitor ( what )`
Monitor the event state for the subscribed event. The first parameter is what should be monitored, the rest are the normal parameters when subscribing to an event.

Parameters:
  `what <string>` what to monitor ('detach', 'attach', 'publish')

Returns: `EventHandle`
  return value from the monitor event subscription

#### on

`EventHandle on ( fn , context , arg* )`
Listen for this event

Parameters:
  `fn <Function>` The function to execute
  `context <object>` optional execution context.
  `arg* <mixed>` 0..n additional arguments to supply to the subscriber when the event fires.

Returns: `EventHandle`
  An object with a detach method to detch the handler(s)

#### preventDefault

`void preventDefault ( )`
Prevents the execution of this event's defaultFn

#### stopImmediatePropagation

`void stopImmediatePropagation ( )`
Stops propagation to bubble targets, and prevents any remaining subscribers on the current target from executing.

#### stopPropagation

`void stopPropagation ( )`
Stop propagation to bubble targets

#### subscribe

`EventHandle subscribe ( fn )`
Listen for this event

Parameters:
  `fn <Function>` The function to execute

Returns: `EventHandle`
  Unsubscribe handle

Deprecated use on

#### unsubscribe

`int|undefined unsubscribe ( fn , context )`
Detach listeners.

Parameters:
  `fn <Function>` The subscribed function to remove, if not supplied all will be removed
  `context <Object>` The context object passed to subscribe.

Returns: `int|undefined`
  returns the number of subscribers unsubscribed

Deprecated use detach

#### unsubscribeAll

`int unsubscribeAll ( )`
Removes all listeners

Returns: `int`
  The number of listeners unsubscribed

Deprecated use detachAll

Copyright © 2010 Yahoo! Inc. All rights reserved.