API: event YAHOO.util.EventProvider (YUI Library)

# Yahoo! UI Library

### Event Utility 2.8.1

Yahoo! UI Library > event > YAHOO.util.EventProvider
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.util.EventProvider

EventProvider is designed to be used with YAHOO.augment to wrap CustomEvents in an interface that allows events to be subscribed 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.

### Properties

#### __yui_events - `private Object[]`

Private storage of custom events

#### __yui_subscribers - `private Object[]`

Private storage of custom event subscribers

### Methods

#### createEvent

`CustomEvent createEvent ( p_type , p_config )`
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:
  `p_type <string>` the type, or name of the event
  `p_config <object>` optional config params. Valid properties are:
  - scope: defines the default execution scope. If not defined the default scope will be this instance.
  - silent: if true, the custom event will not generate log messages. This is false by default.
  - fireOnce: if true, the custom event will only notify subscribers once regardless of the number of times the event is fired. In addition, new subscribers will be executed immediately if the event has already fired. This is false by default.
  - onSubscribeCallback: specifies a callback to execute when the event has a new subscriber. This will fire immediately for each queued subscriber if any exist prior to the creation of the event.

Returns: `CustomEvent`
  the custom event

#### fireEvent

`boolean fireEvent ( p_type , arguments )`
Fire a custom event by name. The callback functions will be executed from the scope specified when the event was created, and with the following parameters:

- The first argument fire() was executed with
- The custom object (if any) that was passed into the subscribe() method

Parameters:
  `p_type <string>` the type, or name of the event
  `arguments <Object*>` an arbitrary set of parameters to pass to the handler.

Returns: `boolean`
  the return value from CustomEvent.fire

#### hasEvent

`void hasEvent ( type )`
Returns true if the custom event of the provided type has been created with createEvent.

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

#### subscribe

`void subscribe ( p_type , p_fn , p_obj , overrideContext )`
Subscribe to a CustomEvent by event type

Parameters:
  `p_type <string>` the type, or name of the event
  `p_fn <function>` the function to exectute when the event fires
  `p_obj <Object>` An object to be passed along when the event fires
  `overrideContext <boolean>` If true, the obj passed in becomes the execution scope of the listener

#### unsubscribe

`boolean unsubscribe ( p_type , p_fn , p_obj )`
Unsubscribes one or more listeners the from the specified event

Parameters:
  `p_type <string>` The type, or name of the event. If the type is not specified, it will attempt to remove the listener from all hosted events.
  `p_fn <Function>` The subscribed function to unsubscribe, if not supplied, all subscribers will be removed.
  `p_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

`void unsubscribeAll ( p_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:
  `p_type <string>` The type, or name of the event

Copyright © 2010 Yahoo! Inc. All rights reserved.