ee1455c399
git-svn-id: http://svn.openlayers.org/tags/openlayers/release-2.5-rc4@4799 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf
285 lines
9.0 KiB
JavaScript
285 lines
9.0 KiB
JavaScript
/* Copyright (c) 2006-2007 MetaCarta, Inc., published under the BSD license.
|
|
* See http://svn.openlayers.org/trunk/openlayers/release-license.txt
|
|
* for the full text of the license. */
|
|
|
|
|
|
/**
|
|
* @requires OpenLayers/Events.js
|
|
*
|
|
* Class: OpenLayers.Handler
|
|
* Base class to construct a higher-level handler for event sequences. All
|
|
* handlers have activate and deactivate methods. In addition, they have
|
|
* methods named like browser events. When a handler is activated, any
|
|
* additional methods named like a browser event is registered as a
|
|
* listener for the corresponding event. When a handler is deactivated,
|
|
* those same methods are unregistered as event listeners.
|
|
*
|
|
* Handlers also typically have a callbacks object with keys named like
|
|
* the abstracted events or event sequences that they are in charge of
|
|
* handling. The controls that wrap handlers define the methods that
|
|
* correspond to these abstract events - so instead of listening for
|
|
* individual browser events, they only listen for the abstract events
|
|
* defined by the handler.
|
|
*
|
|
* Handlers are created by controls, which ultimately have the responsibility
|
|
* of making changes to the the state of the application. Handlers
|
|
* themselves may make temporary changes, but in general are expected to
|
|
* return the application in the same state that they found it.
|
|
*/
|
|
OpenLayers.Handler = OpenLayers.Class({
|
|
|
|
/**
|
|
* Property: id
|
|
* {String}
|
|
*/
|
|
id: null,
|
|
|
|
/**
|
|
* APIProperty: control
|
|
* {<OpenLayers.Control>}. The control that initialized this handler. The
|
|
* control is assumed to have a valid map property - that map is used
|
|
* in the handler's own setMap method.
|
|
*/
|
|
control: null,
|
|
|
|
/**
|
|
* Property: map
|
|
* {<OpenLayers.Map>}
|
|
*/
|
|
map: null,
|
|
|
|
/**
|
|
* APIProperty: keyMask
|
|
* {Integer} Use bitwise operators and one or more of the OpenLayers.Handler
|
|
* constants to construct a keyMask. The keyMask is used by
|
|
* <checkModifiers>. If the keyMask matches the combination of keys
|
|
* down on an event, checkModifiers returns true.
|
|
*
|
|
* Example:
|
|
* (code)
|
|
* // handler only responds if the Shift key is down
|
|
* handler.keyMask = OpenLayers.Handler.MOD_SHIFT;
|
|
*
|
|
* // handler only responds if Ctrl-Shift is down
|
|
* handler.keyMask = OpenLayers.Handler.MOD_SHIFT |
|
|
* OpenLayers.Handler.MOD_CTRL;
|
|
* (end)
|
|
*/
|
|
keyMask: null,
|
|
|
|
/**
|
|
* Property: active
|
|
* {Boolean}
|
|
*/
|
|
active: false,
|
|
|
|
/**
|
|
* Property: evt
|
|
* {Event} This property references the last event handled by the handler.
|
|
* Note that this property is not part of the stable API. Use of the
|
|
* evt property should be restricted to controls in the library
|
|
* or other applications that are willing to update with changes to
|
|
* the OpenLayers code.
|
|
*/
|
|
evt: null,
|
|
|
|
/**
|
|
* Constructor: OpenLayers.Handler
|
|
* Construct a handler.
|
|
*
|
|
* Parameters:
|
|
* control - {<OpenLayers.Control>} The control that initialized this
|
|
* handler. The control is assumed to have a valid map property; that
|
|
* map is used in the handler's own setMap method.
|
|
* callbacks - {Object} An object whose properties correspond to abstracted
|
|
* events or sequences of browser events. The values for these
|
|
* properties are functions defined by the control that get called by
|
|
* the handler.
|
|
* options - {Object} An optional object whose properties will be set on
|
|
* the handler.
|
|
*/
|
|
initialize: function(control, callbacks, options) {
|
|
OpenLayers.Util.extend(this, options);
|
|
this.control = control;
|
|
this.callbacks = callbacks;
|
|
if (control.map) {
|
|
this.setMap(control.map);
|
|
}
|
|
|
|
OpenLayers.Util.extend(this, options);
|
|
|
|
this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_");
|
|
},
|
|
|
|
/**
|
|
* Method: setMap
|
|
*/
|
|
setMap: function (map) {
|
|
this.map = map;
|
|
},
|
|
|
|
/**
|
|
* Method: checkModifiers
|
|
* Check the keyMask on the handler. If no <keyMask> is set, this always
|
|
* returns true. If a <keyMask> is set and it matches the combination
|
|
* of keys down on an event, this returns true.
|
|
*
|
|
* Returns:
|
|
* {Boolean} The keyMask matches the keys down on an event.
|
|
*/
|
|
checkModifiers: function (evt) {
|
|
if(this.keyMask == null) {
|
|
return true;
|
|
}
|
|
/* calculate the keyboard modifier mask for this event */
|
|
var keyModifiers =
|
|
(evt.shiftKey ? OpenLayers.Handler.MOD_SHIFT : 0) |
|
|
(evt.ctrlKey ? OpenLayers.Handler.MOD_CTRL : 0) |
|
|
(evt.altKey ? OpenLayers.Handler.MOD_ALT : 0);
|
|
|
|
/* if it differs from the handler object's key mask,
|
|
bail out of the event handler */
|
|
return (keyModifiers == this.keyMask);
|
|
},
|
|
|
|
/**
|
|
* APIMethod: activate
|
|
* Turn on the handler. Returns false if the handler was already active.
|
|
*
|
|
* Returns:
|
|
* {Boolean} The handler was activated.
|
|
*/
|
|
activate: function() {
|
|
if(this.active) {
|
|
return false;
|
|
}
|
|
// register for event handlers defined on this class.
|
|
var events = OpenLayers.Events.prototype.BROWSER_EVENTS;
|
|
for (var i = 0; i < events.length; i++) {
|
|
if (this[events[i]]) {
|
|
this.register(events[i], this[events[i]]);
|
|
}
|
|
}
|
|
this.active = true;
|
|
return true;
|
|
},
|
|
|
|
/**
|
|
* APIMethod: deactivate
|
|
* Turn off the handler. Returns false if the handler was already inactive.
|
|
*
|
|
* Returns:
|
|
* {Boolean} The handler was deactivated.
|
|
*/
|
|
deactivate: function() {
|
|
if(!this.active) {
|
|
return false;
|
|
}
|
|
// unregister event handlers defined on this class.
|
|
var events = OpenLayers.Events.prototype.BROWSER_EVENTS;
|
|
for (var i = 0; i < events.length; i++) {
|
|
if (this[events[i]]) {
|
|
this.unregister(events[i], this[events[i]]);
|
|
}
|
|
}
|
|
this.active = false;
|
|
return true;
|
|
},
|
|
|
|
/**
|
|
* Method: callback
|
|
* Trigger the control's named callback with the given arguments
|
|
*
|
|
* Parameters:
|
|
* name - {String} The key for the callback that is one of the properties
|
|
* of the handler's callbacks object.
|
|
* args - {Array(*)} An array of arguments (any type) with which to call
|
|
* the callback (defined by the control).
|
|
*/
|
|
callback: function (name, args) {
|
|
if (this.callbacks[name]) {
|
|
this.callbacks[name].apply(this.control, args);
|
|
}
|
|
},
|
|
|
|
/**
|
|
* Method: register
|
|
* register an event on the map
|
|
*/
|
|
register: function (name, method) {
|
|
// TODO: deal with registerPriority in 3.0
|
|
this.map.events.registerPriority(name, this, method);
|
|
this.map.events.registerPriority(name, this, this.setEvent);
|
|
},
|
|
|
|
/**
|
|
* Method: unregister
|
|
* unregister an event from the map
|
|
*/
|
|
unregister: function (name, method) {
|
|
this.map.events.unregister(name, this, method);
|
|
this.map.events.unregister(name, this, this.setEvent);
|
|
},
|
|
|
|
/**
|
|
* Method: setEvent
|
|
* With each registered browser event, the handler sets its own evt
|
|
* property. This property can be accessed by controls if needed
|
|
* to get more information about the event that the handler is
|
|
* processing.
|
|
*
|
|
* This allows modifier keys on the event to be checked (alt, shift,
|
|
* and ctrl cannot be checked with the keyboard handler). For a
|
|
* control to determine which modifier keys are associated with the
|
|
* event that a handler is currently processing, it should access
|
|
* (code)handler.evt.altKey || handler.evt.shiftKey ||
|
|
* handler.evt.ctrlKey(end).
|
|
*
|
|
* Parameters:
|
|
* evt - {Event} The browser event.
|
|
*/
|
|
setEvent: function(evt) {
|
|
this.evt = evt;
|
|
return true;
|
|
},
|
|
|
|
/**
|
|
* Method: destroy
|
|
* Deconstruct the handler.
|
|
*/
|
|
destroy: function () {
|
|
// unregister event listeners
|
|
this.deactivate();
|
|
// eliminate circular references
|
|
this.control = this.map = null;
|
|
},
|
|
|
|
CLASS_NAME: "OpenLayers.Handler"
|
|
});
|
|
|
|
/**
|
|
* Constant: OpenLayers.Handler.MOD_NONE
|
|
* If set as the <keyMask>, <checkModifiers> returns false if any key is down.
|
|
*/
|
|
OpenLayers.Handler.MOD_NONE = 0;
|
|
|
|
/**
|
|
* Constant: OpenLayers.Handler.MOD_SHIFT
|
|
* If set as the <keyMask>, <checkModifiers> returns false if Shift is down.
|
|
*/
|
|
OpenLayers.Handler.MOD_SHIFT = 1;
|
|
|
|
/**
|
|
* Constant: OpenLayers.Handler.MOD_CTRL
|
|
* If set as the <keyMask>, <checkModifiers> returns false if Ctrl is down.
|
|
*/
|
|
OpenLayers.Handler.MOD_CTRL = 2;
|
|
|
|
/**
|
|
* Constant: OpenLayers.Handler.MOD_ALT
|
|
* If set as the <keyMask>, <checkModifiers> returns false if Alt is down.
|
|
*/
|
|
OpenLayers.Handler.MOD_ALT = 4;
|
|
|
|
|