| /* Copyright (c) 2006-2010 by OpenLayers Contributors (see authors.txt for | |
| * full list of contributors). Published under the Clear BSD license. | |
| * See http://svn.openlayers.org/trunk/openlayers/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. If a map property | |
| * is present in the options argument it will be used instead. | |
| * 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; | |
| var map = this.map || control.map; | |
| if (map) { | |
| this.setMap(map); | |
| } | |
| 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, len=events.length; i<len; 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, len=events.length; i<len; 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 (name && 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; | |