Yahoo! UI Library

Event Utility  2.8.0r4

Yahoo! UI Library > event > YAHOO.util.CustomEvent
Search:
 
Filters

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 ( )
Returns: void

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 )
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 If true, the obj passed in becomes the execution context of the listener. If an object, that object becomes the execution context.
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. Defaults to the custom event.
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 © 2009 Yahoo! Inc. All rights reserved.