OpenLayers.Event

Utility functions for event handling.

Summary
OpenLayers.EventUtility functions for event handling.
Properties
observers{Object} A hashtable cache of the event observers.
Constants
KEY_SPACE{int}
KEY_BACKSPACE{int}
KEY_TAB{int}
KEY_RETURN{int}
KEY_ESC{int}
KEY_LEFT{int}
KEY_UP{int}
KEY_RIGHT{int}
KEY_DOWN{int}
KEY_DELETE{int}
Functions
elementCross browser event element detection.
isSingleTouchDetermine whether event was caused by a single touch
isMultiTouchDetermine whether event was caused by a multi touch
isLeftClickDetermine whether event was caused by a left click.
isRightClickDetermine whether event was caused by a right mouse click.
stopStops an event from propagating.
preventDefaultCancels the event if it is cancelable, without stopping further propagation of the event.
findElement
observe
stopObservingElementGiven the id of an element to stop observing, cycle through the element’s cached observers, calling stopObserving on each one, skipping those entries which can no longer be removed.
_removeElementObservers
stopObserving
unloadCacheCycle through all the element entries in the events cache and call stopObservingElement on each.
OpenLayers.Events
Constants
BROWSER_EVENTS{Array(String)} supported events
Properties
listeners{Object} Hashtable of Array(Function): events listener functions
object{Object} the code object issuing application events
element{DOMElement} the DOM element receiving browser events
eventHandler{Function} bound event handler attached to elements
fallThrough{Boolean}
includeXY{Boolean} Should the .xy property automatically be created for browser mouse events? 
extensions{Object} Event extensions registered with this instance.
extensionCount{Object} Keys are event types (like in listeners), values are the number of extension listeners for each event type.
Functions
clearMouseListenerA version of clearMouseCache that is bound to this instance so that it can be used with OpenLayers.Event.observe and OpenLayers.Event.stopObserving.
Constructor
OpenLayers.EventsConstruct an OpenLayers.Events object.
Functions
destroy
addEventTypeDeprecated.
attachToElement
onConvenience method for registering listeners with a common scope.
registerRegister an event on the events object.
registerPrioritySame as register() but adds the new listener to the front of the events queue instead of to the end.
unConvenience method for unregistering listeners with a common scope.
unregister
removeRemove all listeners for a given event type.
triggerEventTrigger a specified registered event.
handleBrowserEventBasically just a wrapper to the triggerEvent() function, but takes care to set a property ‘xy’ on the event with the current mouse position.
getTouchClientXYWebKit has a few bugs for clientX/clientY.
clearMouseCacheClear cached data about the mouse position.
getMousePosition
addMsTouchListener
addMsTouchListenerStart
addMsTouchListenerMove
addMsTouchListenerEnd

Properties

observers

{Object} A hashtable cache of the event observers.  Keyed by element._eventCacheID

Constants

KEY_SPACE

{int}

KEY_BACKSPACE

{int}

KEY_TAB

{int}

KEY_RETURN

{int}

KEY_ESC

{int}

KEY_LEFT

{int}

KEY_UP

{int}

KEY_RIGHT

{int}

KEY_DOWN

{int}

KEY_DELETE

{int}

Functions

element

element: function(event)

Cross browser event element detection.

Parameters

event{Event}

Returns

{DOMElement} The element that caused the event

isSingleTouch

isSingleTouch: function(event)

Determine whether event was caused by a single touch

Parameters

event{Event}

Returns

{Boolean}

isMultiTouch

isMultiTouch: function(event)

Determine whether event was caused by a multi touch

Parameters

event{Event}

Returns

{Boolean}

isLeftClick

isLeftClick: function(event)

Determine whether event was caused by a left click.

Parameters

event{Event}

Returns

{Boolean}

isRightClick

isRightClick: function(event)

Determine whether event was caused by a right mouse click.

Parameters

event{Event}

Returns

{Boolean}

stop

stop: function(event,
allowDefault)

Stops an event from propagating.

Parameters

event{Event}
allowDefault{Boolean} If true, we stop the event chain but still allow the default browser behaviour (text selection, radio-button clicking, etc).  Default is false.

preventDefault

preventDefault: function(event)

Cancels the event if it is cancelable, without stopping further propagation of the event.

Parameters

event{Event}

findElement

findElement: function(event,
tagName)

Parameters

event{Event}
tagName{String}

Returns

{DOMElement} The first node with the given tagName, starting from the node the event was triggered on and traversing the DOM upwards

observe

observe: function(elementParam,
name,
observer,
useCapture)

Parameters

elementParam{DOMElement || String}
name{String}
observer{function}
useCapture{Boolean}

stopObservingElement

stopObservingElement: function(elementParam)

Given the id of an element to stop observing, cycle through the element’s cached observers, calling stopObserving on each one, skipping those entries which can no longer be removed.

parameters

elementParam{DOMElement || String}

_removeElementObservers

_removeElementObservers: function(elementObservers)

Parameters

elementObservers{Array(Object)} Array of (element, name, observer, usecapture) objects, taken directly from hashtable

stopObserving

stopObserving: function(elementParam,
name,
observer,
useCapture)

Parameters

elementParam{DOMElement || String}
name{String}
observer{function}
useCapture{Boolean}

Returns

{Boolean} Whether or not the event observer was removed

unloadCache

unloadCache: function()

Cycle through all the element entries in the events cache and call stopObservingElement on each.

OpenLayers.Events

Summary
Constants
BROWSER_EVENTS{Array(String)} supported events
Properties
listeners{Object} Hashtable of Array(Function): events listener functions
object{Object} the code object issuing application events
element{DOMElement} the DOM element receiving browser events
eventHandler{Function} bound event handler attached to elements
fallThrough{Boolean}
includeXY{Boolean} Should the .xy property automatically be created for browser mouse events? 
extensions{Object} Event extensions registered with this instance.
extensionCount{Object} Keys are event types (like in listeners), values are the number of extension listeners for each event type.
Functions
clearMouseListenerA version of clearMouseCache that is bound to this instance so that it can be used with OpenLayers.Event.observe and OpenLayers.Event.stopObserving.
Constructor
OpenLayers.EventsConstruct an OpenLayers.Events object.
Functions
destroy
addEventTypeDeprecated.
attachToElement
onConvenience method for registering listeners with a common scope.
registerRegister an event on the events object.
registerPrioritySame as register() but adds the new listener to the front of the events queue instead of to the end.
unConvenience method for unregistering listeners with a common scope.
unregister
removeRemove all listeners for a given event type.
triggerEventTrigger a specified registered event.
handleBrowserEventBasically just a wrapper to the triggerEvent() function, but takes care to set a property ‘xy’ on the event with the current mouse position.
getTouchClientXYWebKit has a few bugs for clientX/clientY.
clearMouseCacheClear cached data about the mouse position.
getMousePosition
addMsTouchListener
addMsTouchListenerStart
addMsTouchListenerMove
addMsTouchListenerEnd

Constants

BROWSER_EVENTS

{Array(String)} supported events

Properties

listeners

{Object} Hashtable of Array(Function): events listener functions

object

{Object} the code object issuing application events

element

{DOMElement} the DOM element receiving browser events

eventHandler

{Function} bound event handler attached to elements

fallThrough

{Boolean}

includeXY

{Boolean} Should the .xy property automatically be created for browser mouse events?  In general, this should be false.  If it is true, then mouse events will automatically generate a ‘.xy’ property on the event object that is passed.  (Prior to OpenLayers 2.7, this was true by default.)  Otherwise, you can call the getMousePosition on the relevant events handler on the object available via the ‘evt.object’ property of the evt object.  So, for most events, you can call: function named(evt) { this.xy = this.object.events.getMousePosition(evt) }

This option typically defaults to false for performance reasons

when creating an events object whose primary purpose is to manage relatively positioned mouse events within a div, it may make sense to set it to true.

This option is also used to control whether the events object caches offsets.  If this is false, it will not: the reason for this is that it is only expected to be called many times if the includeXY property is set to true.  If you set this to true, you are expected to clear the offset cache manually (using this.clearMouseCache()) if: the border of the element changes the location of the element in the page changes

extensions

{Object} Event extensions registered with this instance.  Keys are event types, values are {OpenLayers.Events.*} extension instances or {Boolean} for events that an instantiated extension provides in addition to the one it was created for.

Extensions create an event in addition to browser events, which usually fires when a sequence of browser events is completed.  Extensions are automatically instantiated when a listener is registered for an event provided by an extension.

Extensions are created in the OpenLayers.Events namespace using OpenLayers.Class, and named after the event they provide.  The constructor receives the target OpenLayers.Events instance as argument.  Extensions that need to capture browser events before they propagate can register their listeners events using register, with {extension: true} as 4th argument.

If an extension creates more than one event, an alias for each event type should be created and reference the same class.  The constructor should set a reference in the target’s extensions registry to itself.

Below is a minimal extension that provides the “foostart” and “fooend” event types, which replace the native “click” event type if clicked on an element with the css class “foo”:

OpenLayers.Events.foostart = OpenLayers.Class({
    initialize: function(target) {
        this.target = target;
        this.target.register("click", this, this.doStuff, {extension: true});
        // only required if extension provides more than one event type
        this.target.extensions["foostart"] = true;
        this.target.extensions["fooend"] = true;
    },
    destroy: function() {
        var target = this.target;
        target.unregister("click", this, this.doStuff);
        delete this.target;
        // only required if extension provides more than one event type
        delete target.extensions["foostart"];
        delete target.extensions["fooend"];
    },
    doStuff: function(evt) {
        var propagate = true;
        if (OpenLayers.Event.element(evt).className === "foo") {
            propagate = false;
            var target = this.target;
            target.triggerEvent("foostart");
            window.setTimeout(function() {
                target.triggerEvent("fooend");
            }, 1000);
        }
        return propagate;
    }
});
// only required if extension provides more than one event type
OpenLayers.Events.fooend = OpenLayers.Events.foostart;

extensionCount

{Object} Keys are event types (like in listeners), values are the number of extension listeners for each event type.

Functions

clearMouseListener

A version of clearMouseCache that is bound to this instance so that it can be used with OpenLayers.Event.observe and OpenLayers.Event.stopObserving.

Constructor

OpenLayers.Events

Construct an OpenLayers.Events object.

Parameters

object{Object} The js object to which this Events object is being added
element{DOMElement} A dom element to respond to browser events
eventTypes{Array(String)} Deprecated.  Array of custom application events.  A listener may be registered for any named event, regardless of the values provided here.
fallThrough{Boolean} Allow events to fall through after these have been handled?
options{Object} Options for the events object.

Functions

destroy

destroy: function ()

addEventType

addEventType: function(eventName)

Deprecated.  Any event can be triggered without adding it first.

Parameters

eventName{String}

attachToElement

attachToElement: function (element)

Parameters

element{HTMLDOMElement} a DOM element to attach browser events to

on

on: function(object)

Convenience method for registering listeners with a common scope.  Internally, this method calls register as shown in the examples below.

Example use

// register a single listener for the "loadstart" event
events.on({"loadstart": loadStartListener});

// this is equivalent to the following
events.register("loadstart", undefined, loadStartListener);

// register multiple listeners to be called with the same `this` object
events.on({
    "loadstart": loadStartListener,
    "loadend": loadEndListener,
    scope: object
});

// this is equivalent to the following
events.register("loadstart", object, loadStartListener);
events.register("loadend", object, loadEndListener);

Parameters

object{Object}

register

register: function (type,
obj,
func,
priority)

Register an event on the events object.

When the event is triggered, the ‘func’ function will be called, in the context of ‘obj’.  Imagine we were to register an event, specifying an OpenLayers.Bounds Object as ‘obj’.  When the event is triggered, the context in the callback function will be our Bounds object.  This means that within our callback function, we can access the properties and methods of the Bounds object through the “this” variable.  So our callback could execute something like:

leftStr = "Left: " + this.left;

or

centerStr = "Center: " + this.getCenterLonLat();

Parameters

type{String} Name of the event to register
obj{Object} The object to bind the context to for the callback#.  If no object is specified, default is the Events’s ‘object’ property.
func{Function} The callback function.  If no callback is specified, this function does nothing.
priority{Boolean|Object} If true, adds the new listener to the front of the events queue instead of to the end.

Valid options for priority

extension{Boolean} If true, then the event will be registered as extension event.  Extension events are handled before all other events.

registerPriority

registerPriority: function (type,
obj,
func)

Same as register() but adds the new listener to the front of the events queue instead of to the end.

TODO: get rid of this in 3.0Decide whether listeners should be called in the order they were registered or in reverse order.

Parameters

type{String} Name of the event to register
obj{Object} The object to bind the context to for the callback#.  If no object is specified, default is the Events’s ‘object’ property.
func{Function} The callback function.  If no callback is specified, this function does nothing.

un

un: function(object)

Convenience method for unregistering listeners with a common scope.  Internally, this method calls unregister as shown in the examples below.

Example use

// unregister a single listener for the "loadstart" event
events.un({"loadstart": loadStartListener});

// this is equivalent to the following
events.unregister("loadstart", undefined, loadStartListener);

// unregister multiple listeners with the same `this` object
events.un({
    "loadstart": loadStartListener,
    "loadend": loadEndListener,
    scope: object
});

// this is equivalent to the following
events.unregister("loadstart", object, loadStartListener);
events.unregister("loadend", object, loadEndListener);

unregister

unregister: function (type,
obj,
func)

Parameters

type{String}
obj{Object} If none specified, defaults to this.object
func{Function}

remove

remove: function(type)

Remove all listeners for a given event type.  If type is not registered, does nothing.

Parameters

type{String}

triggerEvent

triggerEvent: function (type,
evt)

Trigger a specified registered event.

Parameters

type{String}
evt{Event || Object} will be passed to the listeners.

Returns

{Boolean} The last listener return.  If a listener returns false, the chain of listeners will stop getting called.

handleBrowserEvent

handleBrowserEvent: function (evt)

Basically just a wrapper to the triggerEvent() function, but takes care to set a property ‘xy’ on the event with the current mouse position.

Parameters

evt{Event}

getTouchClientXY

getTouchClientXY: function (evt)

WebKit has a few bugs for clientX/clientY.  This method detects them and calculate the correct values.

Parameters

evt{Touch} a Touch object from a TouchEvent

Returns

{Object} An object with only clientX and clientY properties with the calculated values.

clearMouseCache

clearMouseCache: function()

Clear cached data about the mouse position.  This should be called any time the element that events are registered on changes position within the page.

getMousePosition

getMousePosition: function (evt)

Parameters

evt{Event}

Returns

{OpenLayers.Pixel} The current xy coordinate of the mouse, adjusted for offsets

addMsTouchListener

addMsTouchListener: function (element,
type,
handler)

Parameters

element{DOMElement} The DOM element to register the listener on
type{String} The event type
handler{Function} the handler

addMsTouchListenerStart

addMsTouchListenerStart: function(element,
type,
handler)

Parameters

element{DOMElement} The DOM element to register the listener on
type{String} The event type
handler{Function} the handler

addMsTouchListenerMove

addMsTouchListenerMove: function (element,
type,
handler)

Parameters

element{DOMElement} The DOM element to register the listener on
type{String} The event type
handler{Function} the handler

addMsTouchListenerEnd

addMsTouchListenerEnd: function (element,
type,
handler)

Parameters

element{DOMElement} The DOM element to register the listener on
type{String} The event type
handler{Function} the handler
element: function(event)
Cross browser event element detection.
isSingleTouch: function(event)
Determine whether event was caused by a single touch
isMultiTouch: function(event)
Determine whether event was caused by a multi touch
isLeftClick: function(event)
Determine whether event was caused by a left click.
isRightClick: function(event)
Determine whether event was caused by a right mouse click.
stop: function(event,
allowDefault)
Stops an event from propagating.
preventDefault: function(event)
Cancels the event if it is cancelable, without stopping further propagation of the event.
findElement: function(event,
tagName)
observe: function(elementParam,
name,
observer,
useCapture)
stopObservingElement: function(elementParam)
Given the id of an element to stop observing, cycle through the element’s cached observers, calling stopObserving on each one, skipping those entries which can no longer be removed.
_removeElementObservers: function(elementObservers)
stopObserving: function(elementParam,
name,
observer,
useCapture)
unloadCache: function()
Cycle through all the element entries in the events cache and call stopObservingElement on each.
{Object} Hashtable of Array(Function): events listener functions
clearMouseCache: function()
Clear cached data about the mouse position.
destroy: function ()
addEventType: function(eventName)
Deprecated.
attachToElement: function (element)
on: function(object)
Convenience method for registering listeners with a common scope.
register: function (type,
obj,
func,
priority)
Register an event on the events object.
registerPriority: function (type,
obj,
func)
Same as register() but adds the new listener to the front of the events queue instead of to the end.
un: function(object)
Convenience method for unregistering listeners with a common scope.
unregister: function (type,
obj,
func)
remove: function(type)
Remove all listeners for a given event type.
triggerEvent: function (type,
evt)
Trigger a specified registered event.
handleBrowserEvent: function (evt)
Basically just a wrapper to the triggerEvent() function, but takes care to set a property ‘xy’ on the event with the current mouse position.
getTouchClientXY: function (evt)
WebKit has a few bugs for clientX/clientY.
getMousePosition: function (evt)
addMsTouchListener: function (element,
type,
handler)
addMsTouchListenerStart: function(element,
type,
handler)
addMsTouchListenerMove: function (element,
type,
handler)
addMsTouchListenerEnd: function (element,
type,
handler)
Construct an OpenLayers.Events object.
Base class used to construct all other classes.
This class represents a screen coordinate, in x and y coordinates
Close