# Yahoo! UI Library

### event-custom 3.3.0

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

## Class EventTarget

Known Subclasses:
  AsyncQueue

EventTarget provides the implementation for any object to publish, subscribe and fire to custom events, and also alows other EventTargets to target the object with events sourced from the other object. EventTarget is designed to be used with Y.augment to wrap EventCustom in an interface that allows events to be listened to and fired by name. This makes it possible for implementing code to subscribe to an event that either has not been created yet, or will not be created at all.

### Methods

#### _getType

`private void _getType ( )`
If the instance has a prefix attribute and the event type is not prefixed, the instance prefix is applied to the supplied type.

#### _monitor

`private void _monitor ( )`
This is the entry point for the event monitoring system. You can monitor 'attach', 'detach', 'fire', and 'publish'. When configured, these events generate an event. click -> click_attach, click_detach, click_publish -- these can be subscribed to like other events to monitor the event system. Inividual published events can have monitoring turned on or off (publish can't be turned off before it it published) by setting the events 'monitor' config.

#### _parseType

`private void _parseType ( )`
Returns an array with the detach key (if provided), and the prefixed event name from _getType Y.on('detachcategory| menu:click', fn)

#### addTarget

`void addTarget ( o )`
Registers another EventTarget as a bubble target. Bubble order is determined by the order registered. Multiple targets can be specified. Events can only bubble if emitFacade is true. Included in the event-custom-complex submodule.

Parameters:
  `o <EventTarget>` the target to add

#### after

`after ( type , fn , context , arg* )`
Subscribe to a custom event hosted by this object. The supplied callback will execute after any listeners add via the subscribe method, and after the default function, if configured for the event, has executed.

Parameters:
  `type <string>` The type of the event
  `fn <Function>` The callback
  `context <object>` optional execution context.
  `arg* <mixed>` 0..n additional arguments to supply to the subscriber

Returns: ``
  the event target or a detach handle per 'chain' config

#### before

`before ( )`
Executes the callback before a DOM event, custom event or method. If the first argument is a function, it is assumed the target is a method. For DOM and custom events, this is an alias for Y.on. For DOM and custom events: type, callback, context, 0-n arguments For methods: callback, object (method host), methodName, context, 0-n arguments

Returns: ``
  detach handle

#### bubble

`boolean bubble ( evt )`
Propagate an event. Requires the event-custom-complex module.

Parameters:
  `evt <CustomEvent>` the custom event to propagate

Returns: `boolean`
  the aggregated return value from Event.Custom.fire

#### detach

`EventTarget detach ( type , fn , context )`
Detach one or more listeners the from the specified event

Parameters:
  `type <string|Object>` Either the handle to the subscriber or the type of event. If the type is not specified, it will attempt to remove the listener from all hosted events.
  `fn <Function>` The subscribed function to unsubscribe, if not supplied, all subscribers will be removed.
  `context <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: `EventTarget`
  the host

#### detachAll

`void detachAll ( type )`
Removes all listeners from the specified event. If the event type is not specified, all listeners from all hosted custom events will be removed.

Parameters:
  `type <string>` The type, or name of the event

#### fire

`EventTarget fire ( type , arguments )`
Fire a custom event by name. The callback functions will be executed from the context specified when the event was created, and with the following parameters. If the custom event object hasn't been created, then the event hasn't been published and it has no subscribers. For performance sake, we immediate exit in this case. This means the event won't bubble, so if the intention is that a bubble target be notified, the event must be published on this object first. The first argument is the event type, and any additional arguments are passed to the listeners as parameters. If the first of these is an object literal, and the event is configured to emit an event facade, that object is mixed into the event facade and the facade is provided in place of the original object.

Parameters:
  `type <String|Object>` The type of the event, or an object that contains a 'type' property.
  `arguments <Object*>` an arbitrary set of parameters to pass to the handler. If the first of these is an object literal and the event is configured to emit an event facade, the event facade will replace that parameter after the properties the object literal contains are copied to the event facade.

Returns: `EventTarget`
  the event host

#### getEvent

`CustomEvent getEvent ( type , prefixed )`
Returns the custom event of the provided type has been created, a falsy value otherwise

Parameters:
  `type <string>` the type, or name of the event
  `prefixed <string>` if true, the type is prefixed already

Returns: `CustomEvent`
  the custom event or null

#### getTargets

`getTargets ( )`
Returns an array of bubble targets for this object.

Returns: ``
  EventTarget[]

#### on

`on ( type , fn , context , arg* )`
Subscribe to a custom event hosted by this object

Parameters:
  `type <string>` The type of the event
  `fn <Function>` The callback
  `context <object>` optional execution context.
  `arg* <mixed>` 0..n additional arguments to supply to the subscriber

Returns: ``
  the event target or a detach handle per 'chain' config

#### once

`once ( type , fn , context , arg* )`
Listen to a custom event hosted by this object one time. This is the equivalent to `on` except the listener is immediatelly detached when it is executed.

Parameters:
  `type <string>` The type of the event
  `fn <Function>` The callback
  `context <object>` optional execution context.
  `arg* <mixed>` 0..n additional arguments to supply to the subscriber

Returns: ``
  the event target or a detach handle per 'chain' config

#### parseType

`Array parseType ( type , [pre=this._yuievt.config.prefix] )`
Takes the type parameter passed to 'on' and parses out the various pieces that could be included in the type. If the event type is passed without a prefix, it will be expanded to include the prefix one is supplied or the event target is configured with a default prefix.

Parameters:
  `type <string>` the type
  `[pre=this._yuievt.config.prefix] <string>` the prefix

Returns: `Array`
  an array containing: the detach category, if supplied, the prefixed event type, whether or not this is an after listener, the supplied event type

#### publish

`CustomEvent publish ( type , opts )`
Creates a new custom event of the specified type. If a custom event by that name already exists, it will not be re-created. In either case the custom event is returned.

Parameters:
  `type <string>` the type, or name of the event
  `opts <object>` optional config params. Valid properties are:
  - 'broadcast': whether or not the YUI instance and YUI global are notified when the event is fired (false)
  - 'bubbles': whether or not this event bubbles (true) Events can only bubble if emitFacade is true.
  - 'context': the default execution context for the listeners (this)
  - 'defaultFn': the default function to execute when this event fires if preventDefault was not called
  - 'emitFacade': whether or not this event emits a facade (false)
  - 'prefix': the prefix for this targets events, e.g., 'menu' in 'menu:click'
  - 'fireOnce': if an event is configured to fire once, new subscribers after the fire will be notified immediately.
  - 'async': fireOnce event listeners will fire synchronously if the event has already fired unless async is true.
  - 'preventable': whether or not preventDefault() has an effect (true)
  - 'preventedFn': a function that is executed when preventDefault is called
  - 'queuable': whether or not this event can be queued during bubbling (false)
  - 'silent': if silent is true, debug messages are not provided for this event.
  - 'stoppedFn': a function that is executed when stopPropagation is called
  - 'monitored': specifies whether or not this event should send notifications about when the event has been attached, detached, or published.
  - 'type': the event type (valid option if not provided as the first parameter to publish)

Returns: `CustomEvent`
  the custom event

#### removeTarget

`void removeTarget ( o )`
Removes a bubble target

Parameters:
  `o <EventTarget>` the target to remove

#### subscribe

`void subscribe ( )`
subscribe to an event
Deprecated use on

#### unsubscribe

`void unsubscribe ( )`
detach a listener
Deprecated use detach

#### unsubscribeAll

`void unsubscribeAll ( type )`
Removes all listeners from the specified event. If the event type is not specified, all listeners from all hosted custom events will be removed.

Parameters:
  `type <string>` The type, or name of the event

Deprecated use detachAll

Copyright © 2011 Yahoo! Inc. All rights reserved.