Yahoo! UI Library

Event Utility  2.2.0

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: 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 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.