Yahoo! UI Library

event-custom  3.3.0pr1

Yahoo! UI Library > event-custom > EventTarget
Search:
 
Filters

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

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 © 2010 Yahoo! Inc. All rights reserved.