OpenLayers.Event - OpenLayers

# OpenLayers. Event

Utility functions for event handling.

Summary

OpenLayers. Event | Utility functions for event handling.
Properties |
observers | {Object} A hashtable cache of the event observers.
Constants |
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 | Cross browser event element detection.
isLeftClick | Determine whether event was caused by a left click.
isRightClick | Determine whether event was caused by a right mouse click.
stop | Stops an event from propagating.
findElement |
observe |
stopObservingElement | 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 |
stopObserving |
unloadCache | Cycle 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
eventTypes | {Array(String)} list of support application events
eventHandler | {Function} bound event handler attached to elements
fallThrough | {Boolean}
includeXY | {Boolean} Should the .xy property automatically be created for browser mouse events?
Constructor |
OpenLayers. Events | Construct an OpenLayers.Events object.
Functions |
destroy |
addEventType | Add a new event type to this events object.
attachToElement |
on | Convenience method for registering listeners with a common scope.
register | Register an event on the events object.
registerPriority | Same as register() but adds the new listener to the front of the events queue instead of to the end.
un | Convenience method for unregistering listeners with a common scope.
unregister |
remove | Remove all listeners for a given event type.
triggerEvent | Trigger a specified registered event.
handleBrowserEvent | Basically just a wrapper to the triggerEvent() function, but takes care to set a property ‘xy’ on the event with the current mouse position.
clearMouseCache | Clear cached data about the mouse position.
getMousePosition |

### Properties

### observers

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

### Constants

### 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

### 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 false

### 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
eventTypes | {Array(String)} list of support application events
eventHandler | {Function} bound event handler attached to elements
fallThrough | {Boolean}
includeXY | {Boolean} Should the .xy property automatically be created for browser mouse events?
Constructor |
OpenLayers. Events | Construct an OpenLayers.Events object.
Functions |
destroy |
addEventType | Add a new event type to this events object.
attachToElement |
on | Convenience method for registering listeners with a common scope.
register | Register an event on the events object.
registerPriority | Same as register() but adds the new listener to the front of the events queue instead of to the end.
un | Convenience method for unregistering listeners with a common scope.
unregister |
remove | Remove all listeners for a given event type.
triggerEvent | Trigger a specified registered event.
handleBrowserEvent | Basically just a wrapper to the triggerEvent() function, but takes care to set a property ‘xy’ on the event with the current mouse position.
clearMouseCache | Clear cached data about the mouse position.
getMousePosition |

### 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

### eventTypes

{Array(String)} list of support application 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

### 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)} Array of custom application events
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 | )

Add a new event type to this events object. If the event type has already been added, do nothing.

#### 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.

#### Example use

>     events.on({
>         "loadstart": loadStartListener,
>         "loadend": loadEndListener,
>         scope: object
>     });

### register

> register: function ( | type,
> | obj,
> | func | )

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.

### 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.0 | Decide 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.

#### Example use

>     events.un({
>         "loadstart": loadStartListener,
>         "loadend": loadEndListener,
>         scope: object
>     });

### 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}

#### 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}

### 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

> element: function( | event | )

Cross browser event element detection.

> 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.

> 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.

> destroy: function ()

> addEventType: function( | eventName | )

Add a new event type to this events object.

> attachToElement: function ( | element | )

> on: function( | object | )

Convenience method for registering listeners with a common scope.

> register: function ( | type,
> | obj,
> | func | )

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.

> clearMouseCache: function()

Clear cached data about the mouse position.

> getMousePosition: function ( | evt | )

This class represents a screen coordinate, in x and y coordinates
Close