# Interface goog.events.Listenable

code »

A listenable interface. A listenable is an object with the ability to dispatch/broadcast events to "event listeners" registered via listen/listenOnce. The interface allows for an event propagation mechanism similar to one offered by native browser event targets, such as capture/bubble mechanism, stopping propagation, and preventing default actions. Capture/bubble mechanism depends on the ancestor tree constructed via `#getParentEventTarget`; this tree must be directed acyclic graph. The meaning of default action(s) in preventDefault is specific to a particular use case. Implementations that do not support capture/bubble or can not have a parent listenable can simply not implement any ability to set the parent listenable (and have `#getParentEventTarget` return null). Implementation of this class can be used with or independently from goog.events. Implementation must call `#addImplementation(implClass)`.

Show:Public Protected Private

## Instance Methods

code »dispatchEvent ( e ) ⇒ `boolean`

Dispatches an event (or event like object) and calls all listeners listening for events of this type. The type of the event is decided by the type property on the event object. If any of the listeners returns false OR calls preventDefault then this function will return false. If one of the capture listeners calls stopPropagation, then the bubble listeners won't fire.

Parameters

e: `goog.events.EventLike`
  Event object.

Returns

If anyone called preventDefault on the event object (or if any of the listeners returns false) this will also return false.

code »`<EVENTOBJ>` fireListeners ( type, capture, eventObject ) ⇒ `boolean`

Fires all registered listeners in this listenable for the given type and capture mode, passing them the given eventObject. This does not perform actual capture/bubble. Only implementors of the interface should be using this.

Parameters

type: `(string|!goog.events.EventId.<EVENTOBJ>)`
  The type of the listeners to fire.
capture: `boolean`
  The capture mode of the listeners to fire.
eventObject: `EVENTOBJ`
  The event object to fire.

Returns

Whether all listeners succeeded without attempting to prevent default behavior. If any listener returns false or called goog.events.Event#preventDefault, this returns false.

code »`<SCOPE, EVENTOBJ>` getListener ( type, listener, capture, opt_listenerScope ) ⇒ `goog.events.ListenableKey`

Gets the goog.events.ListenableKey for the event or null if no such listener is in use.

Parameters

type: `(string|!goog.events.EventId.<EVENTOBJ>)`
  The name of the event without the 'on' prefix.
listener: `function(this: SCOPE, EVENTOBJ): (boolean|undefined)`
  The listener function to get.
capture: `boolean`
  Whether the listener is a capturing listener.
opt_listenerScope: `SCOPE=`
  Object in whose scope to call the listener.

Returns

the found listener or null if not found.

code »`<EVENTOBJ>` getListeners ( type, capture ) ⇒ `!Array.<goog.events.ListenableKey>`

Gets all listeners in this listenable for the given type and capture mode.

Parameters

type: `(string|!goog.events.EventId)`
  The type of the listeners to fire.
capture: `boolean`
  The capture mode of the listeners to fire.

Returns

An array of registered listeners.

code »getParentEventTarget ( ) ⇒ `goog.events.Listenable`

Returns the parent of this event target to use for capture/bubble mechanism. NOTE(user): The name reflects the original implementation of custom event target (`goog.events.EventTarget`). We decided that changing the name is not worth it.

Returns

The parent EventTarget or null if there is no parent.

code »`<EVENTOBJ>` hasListener ( opt_type, opt_capture ) ⇒ `boolean`

Whether there is any active listeners matching the specified signature. If either the type or capture parameters are unspecified, the function will match on the remaining criteria.

Parameters

opt_type: `(string|!goog.events.EventId.<EVENTOBJ>)=`
  Event type.
opt_capture: `boolean=`
  Whether to check for capture or bubble listeners.

Returns

Whether there is any active listeners matching the requested type and/or capture phase.

code »`<SCOPE, EVENTOBJ>` listen ( type, listener, opt_useCapture, opt_listenerScope ) ⇒ `goog.events.ListenableKey`

Adds an event listener. A listener can only be added once to an object and if it is added again the key for the listener is returned. Note that if the existing listener is a one-off listener (registered via listenOnce), it will no longer be a one-off listener after a call to listen().

Parameters

type: `(string|!goog.events.EventId.<EVENTOBJ>)`
  The event type id.
listener: `function(this: SCOPE, EVENTOBJ): (boolean|undefined)`
  Callback method.
opt_useCapture: `boolean=`
  Whether to fire in capture phase (defaults to false).
opt_listenerScope: `SCOPE=`
  Object in whose scope to call the listener.

Returns

Unique key for the listener.

code »`<SCOPE, EVENTOBJ>` listenOnce ( type, listener, opt_useCapture, opt_listenerScope ) ⇒ `goog.events.ListenableKey`

Adds an event listener that is removed automatically after the listener fired once. If an existing listener already exists, listenOnce will do nothing. In particular, if the listener was previously registered via listen(), listenOnce() will not turn the listener into a one-off listener. Similarly, if there is already an existing one-off listener, listenOnce does not modify the listeners (it is still a once listener).

Parameters

type: `(string|!goog.events.EventId.<EVENTOBJ>)`
  The event type id.
listener: `function(this: SCOPE, EVENTOBJ): (boolean|undefined)`
  Callback method.
opt_useCapture: `boolean=`
  Whether to fire in capture phase (defaults to false).
opt_listenerScope: `SCOPE=`
  Object in whose scope to call the listener.

Returns

Unique key for the listener.

code »removeAllListeners ( opt_type ) ⇒ `number`

Removes all listeners from this listenable. If type is specified, it will only remove listeners of the particular type. otherwise all registered listeners will be removed.

Parameters

opt_type: `string=`
  Type of event to remove, default is to remove all types.

Returns

Number of listeners removed.

code »`<SCOPE, EVENTOBJ>` unlisten ( type, listener, opt_useCapture, opt_listenerScope ) ⇒ `boolean`

Removes an event listener which was added with listen() or listenOnce().

Parameters

type: `(string|!goog.events.EventId.<EVENTOBJ>)`
  The event type id.
listener: `function(this: SCOPE, EVENTOBJ): (boolean|undefined)`
  Callback method.
opt_useCapture: `boolean=`
  Whether to fire in capture phase (defaults to false).
opt_listenerScope: `SCOPE=`
  Object in whose scope to call the listener.

Returns

Whether any listener was removed.

code »unlistenByKey ( key ) ⇒ `boolean`

Removes an event listener which was added with listen() by the key returned by listen().

Parameters

key: `goog.events.ListenableKey`
  The key returned by listen() or listenOnce().

Returns

Whether any listener was removed.

## Global Functions

code »goog.events.Listenable.addImplementation ( cls )

Marks a given class (constructor) as an implementation of Listenable, do that we can query that fact at runtime. The class must have already implemented the interface.

Parameters

cls: `!Function`
  The class constructor. The corresponding class must have already implemented the interface.

code »goog.events.Listenable.isImplementedBy ( obj ) ⇒ `boolean`

Parameters

obj: `Object`
  The object to check.

Returns

Whether a given instance implements Listenable. The class/superclass of the instance must call addImplementation.

## Global Properties

code »goog.events.Listenable.IMPLEMENTED_BY_PROP : `string`

An expando property to indicate that an object implements goog.events.Listenable. See addImplementation/isImplementedBy.