1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
2 * license. See http://svn.openlayers.org/trunk/openlayers/license.txt for the
3 * full text of the license. */
6 * @requires OpenLayers/Events.js
10 * Class: OpenLayers.Handler
11 * Base class to construct a higher-level handler for event sequences. All
12 * handlers have activate and deactivate methods. In addition, they have
13 * methods named like browser events. When a handler is activated, any
14 * additional methods named like a browser event is registered as a
15 * listener for the corresponding event. When a handler is deactivated,
16 * those same methods are unregistered as event listeners.
18 * Handlers also typically have a callbacks object with keys named like
19 * the abstracted events or event sequences that they are in charge of
20 * handling. The controls that wrap handlers define the methods that
21 * correspond to these abstract events - so instead of listening for
22 * individual browser events, they only listen for the abstract events
23 * defined by the handler.
25 * Handlers are created by controls, which ultimately have the responsibility
26 * of making changes to the the state of the application. Handlers
27 * themselves may make temporary changes, but in general are expected to
28 * return the application in the same state that they found it.
30 OpenLayers.Handler = OpenLayers.Class({
39 * APIProperty: control
40 * {<OpenLayers.Control>}. The control that initialized this handler. The
41 * control is assumed to have a valid map property - that map is used
42 * in the handler's own setMap method.
53 * APIProperty: keyMask
54 * {Integer} Use bitwise operators and one or more of the OpenLayers.Handler
55 * constants to construct a keyMask. The keyMask is used by
56 * <checkModifiers>. If the keyMask matches the combination of keys
57 * down on an event, checkModifiers returns true.
61 * // handler only responds if the Shift key is down
62 * handler.keyMask = OpenLayers.Handler.MOD_SHIFT;
64 * // handler only responds if Ctrl-Shift is down
65 * handler.keyMask = OpenLayers.Handler.MOD_SHIFT |
66 * OpenLayers.Handler.MOD_CTRL;
79 * {Event} This property references the last event handled by the handler.
80 * Note that this property is not part of the stable API. Use of the
81 * evt property should be restricted to controls in the library
82 * or other applications that are willing to update with changes to
83 * the OpenLayers code.
88 * Constructor: OpenLayers.Handler
89 * Construct a handler.
92 * control - {<OpenLayers.Control>} The control that initialized this
93 * handler. The control is assumed to have a valid map property; that
94 * map is used in the handler's own setMap method.
95 * callbacks - {Object} An object whose properties correspond to abstracted
96 * events or sequences of browser events. The values for these
97 * properties are functions defined by the control that get called by
99 * options - {Object} An optional object whose properties will be set on
102 initialize: function(control, callbacks, options) {
103 OpenLayers.Util.extend(this, options);
104 this.control = control;
105 this.callbacks = callbacks;
107 this.setMap(control.map);
110 OpenLayers.Util.extend(this, options);
112 this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_");
118 setMap: function (map) {
123 * Method: checkModifiers
124 * Check the keyMask on the handler. If no <keyMask> is set, this always
125 * returns true. If a <keyMask> is set and it matches the combination
126 * of keys down on an event, this returns true.
129 * {Boolean} The keyMask matches the keys down on an event.
131 checkModifiers: function (evt) {
132 if(this.keyMask == null) {
135 /* calculate the keyboard modifier mask for this event */
137 (evt.shiftKey ? OpenLayers.Handler.MOD_SHIFT : 0) |
138 (evt.ctrlKey ? OpenLayers.Handler.MOD_CTRL : 0) |
139 (evt.altKey ? OpenLayers.Handler.MOD_ALT : 0);
141 /* if it differs from the handler object's key mask,
142 bail out of the event handler */
143 return (keyModifiers == this.keyMask);
147 * APIMethod: activate
148 * Turn on the handler. Returns false if the handler was already active.
151 * {Boolean} The handler was activated.
153 activate: function() {
157 // register for event handlers defined on this class.
158 var events = OpenLayers.Events.prototype.BROWSER_EVENTS;
159 for (var i=0, len=events.length; i<len; i++) {
160 if (this[events[i]]) {
161 this.register(events[i], this[events[i]]);
169 * APIMethod: deactivate
170 * Turn off the handler. Returns false if the handler was already inactive.
173 * {Boolean} The handler was deactivated.
175 deactivate: function() {
179 // unregister event handlers defined on this class.
180 var events = OpenLayers.Events.prototype.BROWSER_EVENTS;
181 for (var i=0, len=events.length; i<len; i++) {
182 if (this[events[i]]) {
183 this.unregister(events[i], this[events[i]]);
192 * Trigger the control's named callback with the given arguments
195 * name - {String} The key for the callback that is one of the properties
196 * of the handler's callbacks object.
197 * args - {Array(*)} An array of arguments (any type) with which to call
198 * the callback (defined by the control).
200 callback: function (name, args) {
201 if (name && this.callbacks[name]) {
202 this.callbacks[name].apply(this.control, args);
208 * register an event on the map
210 register: function (name, method) {
211 // TODO: deal with registerPriority in 3.0
212 this.map.events.registerPriority(name, this, method);
213 this.map.events.registerPriority(name, this, this.setEvent);
218 * unregister an event from the map
220 unregister: function (name, method) {
221 this.map.events.unregister(name, this, method);
222 this.map.events.unregister(name, this, this.setEvent);
227 * With each registered browser event, the handler sets its own evt
228 * property. This property can be accessed by controls if needed
229 * to get more information about the event that the handler is
232 * This allows modifier keys on the event to be checked (alt, shift,
233 * and ctrl cannot be checked with the keyboard handler). For a
234 * control to determine which modifier keys are associated with the
235 * event that a handler is currently processing, it should access
236 * (code)handler.evt.altKey || handler.evt.shiftKey ||
237 * handler.evt.ctrlKey(end).
240 * evt - {Event} The browser event.
242 setEvent: function(evt) {
249 * Deconstruct the handler.
251 destroy: function () {
252 // unregister event listeners
254 // eliminate circular references
255 this.control = this.map = null;
258 CLASS_NAME: "OpenLayers.Handler"
262 * Constant: OpenLayers.Handler.MOD_NONE
263 * If set as the <keyMask>, <checkModifiers> returns false if any key is down.
265 OpenLayers.Handler.MOD_NONE = 0;
268 * Constant: OpenLayers.Handler.MOD_SHIFT
269 * If set as the <keyMask>, <checkModifiers> returns false if Shift is down.
271 OpenLayers.Handler.MOD_SHIFT = 1;
274 * Constant: OpenLayers.Handler.MOD_CTRL
275 * If set as the <keyMask>, <checkModifiers> returns false if Ctrl is down.
277 OpenLayers.Handler.MOD_CTRL = 2;
280 * Constant: OpenLayers.Handler.MOD_ALT
281 * If set as the <keyMask>, <checkModifiers> returns false if Alt is down.
283 OpenLayers.Handler.MOD_ALT = 4;