# Namespace goog.events

code »

## Interfaces

goog.events.Listenable
  A listenable interface.
goog.events.ListenableKey
  An interface that describes a single registered listener.

## Classes

goog.events.BrowserEvent
  Accepts a browser event object and creates a patched, cross browser event object.
goog.events.Event
  A base class for event objects, so that they can support preventDefault and stopPropagation.
goog.events.EventId
  A templated class that is used when registering for events.
goog.events.EventTarget
  An implementation of `goog.events.Listenable` with full W3C EventTarget-like support (capture/bubble mechanism, stopping event propagation, preventing default actions).
goog.events.Listener
  Simple class that stores information about a listener
goog.events.ListenerMap
  Creates a new listener map.

## Enumerations

goog.events.BrowserFeature
  Enum of browser capabilities.
goog.events.CaptureSimulationMode
  No Description.
goog.events.EventType
  Constants for event names.
goog.events.KeyCodes
  Key codes for common characters.

Show:Public Protected Private

## Type Definitions

code »goog.events.EventLike : `(string|Object|goog.events.Event|goog.events.EventId)`
A typedef for event like objects that are dispatchable via the goog.events.dispatchEvent function. strings are treated as the type for a goog.events.Event. Objects are treated as an extension of a new goog.events.Event with the type property of the object being used as the type of the Event.
code »goog.events.Key : `(number|goog.events.ListenableKey)`
No description.
code »goog.events.ListenableType : `(EventTarget|goog.events.Listenable)`
No description.

## Global Functions

code »goog.events.dispatchEvent ( src, 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

src: `goog.events.Listenable`
  The event target.
e: `goog.events.EventLike`
  Event object.

Returns

If anyone called preventDefault on the event object (or if any of the handlers returns false) this will also return false. If there are no handlers, or if all handlers return true, this returns true.

code »goog.events.expose ( e ) ⇒ `string`

Provides a nice string showing the normalized event objects public members

Parameters

e: `Object`
  Event Object.

Returns

String of the public members of the normalized event object.

code »goog.events.fireListener ( listener, eventObject ) ⇒ `boolean`

Fires a listener with a set of arguments

Parameters

listener: `goog.events.Listener`
  The listener object to call.
eventObject: `Object`
  The event object to pass to the listener.

Returns

Result of listener.

code »goog.events.fireListeners ( obj, type, capture, eventObject ) ⇒ `boolean`

Fires an object's listeners of a particular type and phase

Parameters

obj: `Object`
  Object whose listeners to call.
type: `(string|!goog.events.EventId)`
  Event type.
capture: `boolean`
  Which event phase.
eventObject: `Object`
  Event object to be passed to listener.

Returns

True if all listeners returned true else false.

code »goog.events.fireListeners_ ( obj, type, capture, eventObject ) ⇒ `boolean`

Fires an object's listeners of a particular type and phase.

Parameters

obj: `Object`
  Object whose listeners to call.
type: `(string|!goog.events.EventId)`
  Event type.
capture: `boolean`
  Which event phase.
eventObject: `Object`
  Event object to be passed to listener.

Returns

True if all listeners returned true else false.

code »`<EVENTOBJ>` goog.events.getListener ( src, type, listener, opt_capt, opt_handler ) ⇒ `goog.events.ListenableKey`

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

Parameters

src: `(EventTarget|goog.events.Listenable)`
  The target from which to get listeners.
type: `(?string|!goog.events.EventId.<EVENTOBJ>)`
  The type of the event.
listener: `(function(EVENTOBJ): ?|{handleEvent: function(?): ?}|null)`
  The listener function to get.
opt_capt: `boolean=`
  In DOM-compliant browsers, this determines whether the listener is fired during the capture or bubble phase of the event.
opt_handler: `Object=`
  Element in whose scope to call the listener.

Returns

the found listener or null if not found.

code »goog.events.getListenerMap_ ( src ) ⇒ `goog.events.ListenerMap`

Parameters

src: `EventTarget`
  The source object.

Returns

A listener map for the given source object, or null if none exists.

code »goog.events.getListeners ( obj, type, capture ) ⇒ `Array.<goog.events.Listener>`

Gets the listeners for a given object, type and capture phase.

Parameters

obj: `Object`
  Object to get listeners for.
type: `(string|!goog.events.EventId)`
  Event type.
capture: `boolean`
  Capture phase?.

Returns

Array of listener objects.

code »goog.events.getOnString_ ( type ) ⇒ `string`

Returns a string with on prepended to the specified type. This is used for IE which expects "on" to be prepended. This function caches the string in order to avoid extra allocations in steady state.

Parameters

type: `string`
  Event type.

Returns

The type string with 'on' prepended.

code »goog.events.getProxy ( ) ⇒ `!Function`

Helper function for returning a proxy function.

Returns

A new or reused function object.

code »goog.events.getTotalListenerCount ( ) ⇒ `number`
Deprecated: This returns estimated count, now that Closure no longer stores a central listener registry. We still return an estimation to keep existing listener-related tests passing. In the near future, this function will be removed.

Gets the total number of listeners currently in the system.

Returns

Number of listeners.

code »goog.events.getUniqueId ( identifier ) ⇒ `string`

Creates a unique event id.

Parameters

identifier: `string`
  The identifier.

Returns

A unique identifier.

code »goog.events.getVendorPrefixedName_ ( eventName ) ⇒ `string`

Returns a prefixed event name for the current browser.

Parameters

eventName: `string`
  The name of the event.

Returns

The prefixed event name.

code »goog.events.handleBrowserEvent_ ( listener, opt_evt ) ⇒ `boolean`

Handles an event and dispatches it to the correct listeners. This function is a proxy for the real listener the user specified.

Parameters

listener: `goog.events.Listener`
  The listener object.
opt_evt: `Event=`
  Optional event object that gets passed in via the native event handlers.

Returns

Result of the event handler.

code »goog.events.hasListener ( obj, opt_type, opt_capture ) ⇒ `boolean`

Returns whether an event target has 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

obj: `(EventTarget|goog.events.Listenable)`
  Target to get listeners for.
opt_type: `(string|!goog.events.EventId)=`
  Event type.
opt_capture: `boolean=`
  Whether to check for capture or bubble-phase listeners.

Returns

Whether an event target has one or more listeners matching the requested type and/or capture phase.

code »goog.events.isMarkedIeEvent_ ( e ) ⇒ `boolean`

This is used to check if an IE event has already been handled by the Closure system so we do not do the Closure pass twice for a bubbling event.

Parameters

e: `Event`
  The IE browser event.

Returns

True if the event object has been marked.

code »`<T, EVENTOBJ>` goog.events.listen ( src, type, listener, opt_capt, opt_handler ) ⇒ `goog.events.Key`

Adds an event listener for a specific event on a native event target (such as a DOM element) or an object that has implemented `goog.events.Listenable`. 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

src: `(EventTarget|goog.events.Listenable)`
  The node to listen to events on.
type: `(string|Array.<string>|!goog.events.EventId.<EVENTOBJ>|!Array)`
  Event type or array of event types.
listener: `(function(this: T, EVENTOBJ): ?|{handleEvent: function(?): ?}|null)`
  Callback method, or an object with a handleEvent function. WARNING: passing an Object is now softly deprecated.
opt_capt: `boolean=`
  Whether to fire in capture phase (defaults to false).
opt_handler: `T=`
  Element in whose scope to call the listener.

Returns

Unique key for the listener.

code »`<T, EVENTOBJ>` goog.events.listenOnce ( src, type, listener, opt_capt, opt_handler ) ⇒ `goog.events.Key`

Adds an event listener for a specific event on a native event target (such as a DOM element) or an object that has implemented `goog.events.Listenable`. After the event has fired the event listener is removed from the target. 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

src: `(EventTarget|goog.events.Listenable)`
  The node to listen to events on.
type: `(string|Array.<string>|!goog.events.EventId.<EVENTOBJ>|!Array)`
  Event type or array of event types.
listener: `(function(this: T, EVENTOBJ): ?|{handleEvent: function(?): ?}|null)`
  Callback method.
opt_capt: `boolean=`
  Fire in capture phase?.
opt_handler: `T=`
  Element in whose scope to call the listener.

Returns

Unique key for the listener.

code »`<T>` goog.events.listenWithWrapper ( src, wrapper, listener, opt_capt, opt_handler )

Adds an event listener with a specific event wrapper on a DOM Node or an object that has implemented `goog.events.Listenable`. A listener can only be added once to an object.

Parameters

src: `(EventTarget|goog.events.Listenable)`
  The target to listen to events on.
wrapper: `goog.events.EventWrapper`
  Event wrapper to use.
listener: `(function(this: T, ?): ?|{handleEvent: function(?): ?}|null)`
  Callback method, or an object with a handleEvent function.
opt_capt: `boolean=`
  Whether to fire in capture phase (defaults to false).
opt_handler: `T=`
  Element in whose scope to call the listener.

code »goog.events.listen_ ( src, type, listener, callOnce, opt_capt, opt_handler ) ⇒ `goog.events.ListenableKey`

Adds an event listener for a specific event on a native event target. 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 a one-off listener will not change an existing listener, if any. On the other hand a normal listener will change existing one-off listener to become a normal listener.

Parameters

src: `EventTarget`
  The node to listen to events on.
type: `(string|!goog.events.EventId)`
  Event type.
listener: `!Function`
  Callback function.
callOnce: `boolean`
  Whether the listener is a one-off listener or otherwise.
opt_capt: `boolean=`
  Whether to fire in capture phase (defaults to false).
opt_handler: `Object=`
  Element in whose scope to call the listener.

Returns

Unique key for the listener.

code »goog.events.markIeEvent_ ( e )

This is used to mark the IE event object so we do not do the Closure pass twice for a bubbling event.

Parameters

e: `Event`
  The IE browser event.

code »goog.events.protectBrowserEventEntryPoint ( errorHandler )

Installs exception protection for the browser event entry point using the given error handler.

Parameters

errorHandler: `goog.debug.ErrorHandler`
  Error handler with which to protect the entry point.

code »goog.events.removeAll ( obj, opt_type ) ⇒ `number`

Removes all listeners from an object. You can also optionally remove listeners of a particular type.

Parameters

obj: `(Object|undefined)`
  Object to remove listeners from. Must be an EventTarget or a goog.events.Listenable.
opt_type: `(string|!goog.events.EventId)=`
  Type of event to remove. Default is all types.

Returns

Number of listeners removed.

code »goog.events.removeAllNativeListeners ( ) ⇒ `number`
Deprecated: This doesn't do anything, now that Closure no longer stores a central listener registry.

Removes all native listeners registered via goog.events. Native listeners are listeners on native browser objects (such as DOM elements). In particular, goog.events.Listenable and goog.events.EventTarget listeners will NOT be removed.

Returns

Number of listeners removed.

code »`<EVENTOBJ>` goog.events.unlisten ( src, type, listener, opt_capt, opt_handler ) ⇒ `?boolean`

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

Parameters

src: `(EventTarget|goog.events.Listenable)`
  The target to stop listening to events on.
type: `(string|Array.<string>|!goog.events.EventId.<EVENTOBJ>|!Array)`
  Event type or array of event types to unlisten to.
listener: `(function(?): ?|{handleEvent: function(?): ?}|null)`
  The listener function to remove.
opt_capt: `boolean=`
  In DOM-compliant browsers, this determines whether the listener is fired during the capture or bubble phase of the event.
opt_handler: `Object=`
  Element in whose scope to call the listener.

Returns

indicating whether the listener was there to remove.

code »goog.events.unlistenByKey ( key ) ⇒ `boolean`

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

Parameters

key: `goog.events.Key`
  The key returned by listen() for this event listener.

Returns

indicating whether the listener was there to remove.

code »goog.events.unlistenWithWrapper ( src, wrapper, listener, opt_capt, opt_handler )

Removes an event listener which was added with listenWithWrapper().

Parameters

src: `(EventTarget|goog.events.Listenable)`
  The target to stop listening to events on.
wrapper: `goog.events.EventWrapper`
  Event wrapper to use.
listener: `(function(?): ?|{handleEvent: function(?): ?}|null)`
  The listener function to remove.
opt_capt: `boolean=`
  In DOM-compliant browsers, this determines whether the listener is fired during the capture or bubble phase of the event.
opt_handler: `Object=`
  Element in whose scope to call the listener.

code »goog.events.wrapListener ( listener ) ⇒ `!Function`

Parameters

listener: `(Object|Function)`
  The listener function or an object that contains handleEvent method.

Returns

Either the original function or a function that calls obj.handleEvent. If the same listener is passed to this function more than once, the same function is guaranteed to be returned.

## Global Properties

code »goog.events.LISTENER_MAP_PROP_ : `string`

Property name on a native event target for the listener map associated with the event target.

code »goog.events.LISTENER_WRAPPER_PROP_ : `string`

Expando property for listener function wrapper for Object with handleEvent.

code »goog.events.listenerCountEstimate_ : `number`

Estimated count of total native listeners.

code »goog.events.onStringMap_ : `{}`

Map of computed "on<eventname>" strings for IE event types. Caching this removes an extra object allocation in goog.events.listen which improves IE6 performance.

code »goog.events.onString_ : `string`

String used to prepend to IE event types.

code »goog.events.uniqueIdCounter_ : `number`

Counter to create unique event ids.

## Compiler Constants

code »goog.events.CAPTURE_SIMULATION_MODE : `number`