Class: EventDispatcher

Methods

This base class defines the on , once , and off methods of objects that can dispatch events.

Methods

Name Description
addEventListener (type, listener, context) Deprecated.
off (type, handler, context) → {Object} Removes an event handler or handlers.
on (type, handler, context) → { EventDispatcher } Adds an event handler function for one or more events.
once (type, handler, context) → {Object} Adds an event handler function for one or more events.
removeEventListener (type, listener, context) Deprecated.

addEventListener (type, listener, context)

Parameters:
Name Type Description
type String The string identifying the type of event.
listener function The function to be invoked when the object dispatches the event.
context Object (Optional) Defines the value of this in the event handler function.

Deprecated — use on() or once() instead.

This method registers a method as an event listener for a specific event.

If a handler is not registered for an event, the event is ignored locally. If the event listener function does not exist, the event is ignored locally.

Throws an exception if the listener name is invalid.

See:

off (type, handler, context) → {Object}

Removes an event handler or handlers.

If you pass in one event name and a handler method, the handler is removed for that event: 

obj.off("eventName", eventHandler);

If you pass in multiple event names and a handler method, the handler is removed for those events: 

obj.off("eventName1 eventName2", eventHandler);

If you pass in an event name (or names) and no handler method, all handlers are removed for those events: 

obj.off("event1Name event2Name");

If you pass in no arguments, all event handlers are removed for all events dispatched by the object: 

obj.off();

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler: 

obj.off(
   {
      eventName1: event1Handler,
      eventName2: event2Handler
   });
Parameters:
Name Type Description
type String (Optional) The string identifying the type of event. You can use a space to specify multiple events, as in "accessAllowed accessDenied accessDialogClosed". If you pass in no type value (or other arguments), all event handlers are removed for the object.
handler function (Optional) The event handler function to remove. The handler must be the same function object as was passed into on() . Be careful with helpers like bind() that return a new function when called. If you pass in no handler , all event handlers are removed for the specified event type .
context Object (Optional) If you specify a context , the event handler is removed for all specified events and handlers that use the specified context. (The context must match the context passed into on() .)
See:
Returns:
The object that dispatched the event.

on (type, handler, context) → { EventDispatcher }

Adds an event handler function for one or more events.

The following code adds an event handler for one event:

obj.on("eventName", function (event) {
    // This is the event handler.
});

If you pass in multiple event names and a handler method, the handler is registered for each of those events: 

obj.on("eventName1 eventName2",
       function (event) {
           // This is the event handler.
       });

You can also pass in a third context parameter (which is optional) to define the value of this in the handler method: 

obj.on("eventName",
       function (event) {
           // This is the event handler.
       },
       obj);

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler: 

obj.on(
   {
      eventName1: function (event) {
              // This is the handler for eventName1.
          },
      eventName2:  function (event) {
              // This is the handler for eventName2.
          }
   },
   obj);

If you do not add a handler for an event, the event is ignored locally.

Parameters:
Name Type Description
type String The string identifying the type of event. You can specify multiple event names in this string, separating them with a space. The event handler will process each of the events.
handler function The handler function to process the event. This function takes the event object as a parameter.
context Object (Optional) Defines the value of this in the event handler function.
See:
Returns:
The EventDispatcher object.

once (type, handler, context) → {Object}

Adds an event handler function for one or more events. Once the handler is called, the specified handler method is removed as a handler for this event. (When you use the on() method to add an event handler, the handler is not removed when it is called.) The once() method is the equivilent of calling the on() method and calling off() the first time the handler is invoked.

The following code adds a one-time event handler for one event: 

obj.once("eventName", function (event) {
   // This is the event handler.
});

If you pass in multiple event names and a handler method, the handler is registered for each of those events: 

obj.once("eventName1 eventName2"
         function (event) {
             // This is the event handler.
         });

You can also pass in a third context parameter (which is optional) to define the value of this in the handler method: 

obj.once("eventName",
         function (event) {
             // This is the event handler.
         },
         obj);

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler: 

obj.once(
   {
      eventName1: function (event) {
                 // This is the event handler for eventName1.
          },
      eventName2:  function (event) {
                 // This is the event handler for eventName1.
          }
   },
   obj);
Parameters:
Name Type Description
type String The string identifying the type of event. You can specify multiple event names in this string, separating them with a space. The event handler will process the first occurence of the events. After the first event, the handler is removed (for all specified events).
handler function The handler function to process the event. This function takes the event object as a parameter.
context Object (Optional) Defines the value of this in the event handler function.
See:
Returns:
The object that dispatched the event.

removeEventListener (type, listener, context)

Parameters:
Name Type Description
type String The string identifying the type of event.
listener function The event listener function to remove.
context Object (Optional) If you specify a context , the event handler is removed for all specified events and event listeners that use the specified context. (The context must match the context passed into addEventListener() .)

Deprecated — use off() instead.

Removes an event listener for a specific event.

Throws an exception if the listener name is invalid.

See: