[76] | 1 | /* Copyright (c) 2006-2010 by OpenLayers Contributors (see authors.txt for |
---|
| 2 | * full list of contributors). Published under the Clear BSD license. |
---|
| 3 | * See http://svn.openlayers.org/trunk/openlayers/license.txt for the |
---|
| 4 | * full text of the license. */ |
---|
| 5 | |
---|
| 6 | /** |
---|
| 7 | * @requires OpenLayers/Events.js |
---|
| 8 | */ |
---|
| 9 | |
---|
| 10 | /** |
---|
| 11 | * Class: OpenLayers.Handler |
---|
| 12 | * Base class to construct a higher-level handler for event sequences. All |
---|
| 13 | * handlers have activate and deactivate methods. In addition, they have |
---|
| 14 | * methods named like browser events. When a handler is activated, any |
---|
| 15 | * additional methods named like a browser event is registered as a |
---|
| 16 | * listener for the corresponding event. When a handler is deactivated, |
---|
| 17 | * those same methods are unregistered as event listeners. |
---|
| 18 | * |
---|
| 19 | * Handlers also typically have a callbacks object with keys named like |
---|
| 20 | * the abstracted events or event sequences that they are in charge of |
---|
| 21 | * handling. The controls that wrap handlers define the methods that |
---|
| 22 | * correspond to these abstract events - so instead of listening for |
---|
| 23 | * individual browser events, they only listen for the abstract events |
---|
| 24 | * defined by the handler. |
---|
| 25 | * |
---|
| 26 | * Handlers are created by controls, which ultimately have the responsibility |
---|
| 27 | * of making changes to the the state of the application. Handlers |
---|
| 28 | * themselves may make temporary changes, but in general are expected to |
---|
| 29 | * return the application in the same state that they found it. |
---|
| 30 | */ |
---|
| 31 | OpenLayers.Handler = OpenLayers.Class({ |
---|
| 32 | |
---|
| 33 | /** |
---|
| 34 | * Property: id |
---|
| 35 | * {String} |
---|
| 36 | */ |
---|
| 37 | id: null, |
---|
| 38 | |
---|
| 39 | /** |
---|
| 40 | * APIProperty: control |
---|
| 41 | * {<OpenLayers.Control>}. The control that initialized this handler. The |
---|
| 42 | * control is assumed to have a valid map property - that map is used |
---|
| 43 | * in the handler's own setMap method. |
---|
| 44 | */ |
---|
| 45 | control: null, |
---|
| 46 | |
---|
| 47 | /** |
---|
| 48 | * Property: map |
---|
| 49 | * {<OpenLayers.Map>} |
---|
| 50 | */ |
---|
| 51 | map: null, |
---|
| 52 | |
---|
| 53 | /** |
---|
| 54 | * APIProperty: keyMask |
---|
| 55 | * {Integer} Use bitwise operators and one or more of the OpenLayers.Handler |
---|
| 56 | * constants to construct a keyMask. The keyMask is used by |
---|
| 57 | * <checkModifiers>. If the keyMask matches the combination of keys |
---|
| 58 | * down on an event, checkModifiers returns true. |
---|
| 59 | * |
---|
| 60 | * Example: |
---|
| 61 | * (code) |
---|
| 62 | * // handler only responds if the Shift key is down |
---|
| 63 | * handler.keyMask = OpenLayers.Handler.MOD_SHIFT; |
---|
| 64 | * |
---|
| 65 | * // handler only responds if Ctrl-Shift is down |
---|
| 66 | * handler.keyMask = OpenLayers.Handler.MOD_SHIFT | |
---|
| 67 | * OpenLayers.Handler.MOD_CTRL; |
---|
| 68 | * (end) |
---|
| 69 | */ |
---|
| 70 | keyMask: null, |
---|
| 71 | |
---|
| 72 | /** |
---|
| 73 | * Property: active |
---|
| 74 | * {Boolean} |
---|
| 75 | */ |
---|
| 76 | active: false, |
---|
| 77 | |
---|
| 78 | /** |
---|
| 79 | * Property: evt |
---|
| 80 | * {Event} This property references the last event handled by the handler. |
---|
| 81 | * Note that this property is not part of the stable API. Use of the |
---|
| 82 | * evt property should be restricted to controls in the library |
---|
| 83 | * or other applications that are willing to update with changes to |
---|
| 84 | * the OpenLayers code. |
---|
| 85 | */ |
---|
| 86 | evt: null, |
---|
| 87 | |
---|
| 88 | /** |
---|
| 89 | * Constructor: OpenLayers.Handler |
---|
| 90 | * Construct a handler. |
---|
| 91 | * |
---|
| 92 | * Parameters: |
---|
| 93 | * control - {<OpenLayers.Control>} The control that initialized this |
---|
| 94 | * handler. The control is assumed to have a valid map property; that |
---|
| 95 | * map is used in the handler's own setMap method. If a map property |
---|
| 96 | * is present in the options argument it will be used instead. |
---|
| 97 | * callbacks - {Object} An object whose properties correspond to abstracted |
---|
| 98 | * events or sequences of browser events. The values for these |
---|
| 99 | * properties are functions defined by the control that get called by |
---|
| 100 | * the handler. |
---|
| 101 | * options - {Object} An optional object whose properties will be set on |
---|
| 102 | * the handler. |
---|
| 103 | */ |
---|
| 104 | initialize: function(control, callbacks, options) { |
---|
| 105 | OpenLayers.Util.extend(this, options); |
---|
| 106 | this.control = control; |
---|
| 107 | this.callbacks = callbacks; |
---|
| 108 | |
---|
| 109 | var map = this.map || control.map; |
---|
| 110 | if (map) { |
---|
| 111 | this.setMap(map); |
---|
| 112 | } |
---|
| 113 | |
---|
| 114 | this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_"); |
---|
| 115 | }, |
---|
| 116 | |
---|
| 117 | /** |
---|
| 118 | * Method: setMap |
---|
| 119 | */ |
---|
| 120 | setMap: function (map) { |
---|
| 121 | this.map = map; |
---|
| 122 | }, |
---|
| 123 | |
---|
| 124 | /** |
---|
| 125 | * Method: checkModifiers |
---|
| 126 | * Check the keyMask on the handler. If no <keyMask> is set, this always |
---|
| 127 | * returns true. If a <keyMask> is set and it matches the combination |
---|
| 128 | * of keys down on an event, this returns true. |
---|
| 129 | * |
---|
| 130 | * Returns: |
---|
| 131 | * {Boolean} The keyMask matches the keys down on an event. |
---|
| 132 | */ |
---|
| 133 | checkModifiers: function (evt) { |
---|
| 134 | if(this.keyMask == null) { |
---|
| 135 | return true; |
---|
| 136 | } |
---|
| 137 | /* calculate the keyboard modifier mask for this event */ |
---|
| 138 | var keyModifiers = |
---|
| 139 | (evt.shiftKey ? OpenLayers.Handler.MOD_SHIFT : 0) | |
---|
| 140 | (evt.ctrlKey ? OpenLayers.Handler.MOD_CTRL : 0) | |
---|
| 141 | (evt.altKey ? OpenLayers.Handler.MOD_ALT : 0); |
---|
| 142 | |
---|
| 143 | /* if it differs from the handler object's key mask, |
---|
| 144 | bail out of the event handler */ |
---|
| 145 | return (keyModifiers == this.keyMask); |
---|
| 146 | }, |
---|
| 147 | |
---|
| 148 | /** |
---|
| 149 | * APIMethod: activate |
---|
| 150 | * Turn on the handler. Returns false if the handler was already active. |
---|
| 151 | * |
---|
| 152 | * Returns: |
---|
| 153 | * {Boolean} The handler was activated. |
---|
| 154 | */ |
---|
| 155 | activate: function() { |
---|
| 156 | if(this.active) { |
---|
| 157 | return false; |
---|
| 158 | } |
---|
| 159 | // register for event handlers defined on this class. |
---|
| 160 | var events = OpenLayers.Events.prototype.BROWSER_EVENTS; |
---|
| 161 | for (var i=0, len=events.length; i<len; i++) { |
---|
| 162 | if (this[events[i]]) { |
---|
| 163 | this.register(events[i], this[events[i]]); |
---|
| 164 | } |
---|
| 165 | } |
---|
| 166 | this.active = true; |
---|
| 167 | return true; |
---|
| 168 | }, |
---|
| 169 | |
---|
| 170 | /** |
---|
| 171 | * APIMethod: deactivate |
---|
| 172 | * Turn off the handler. Returns false if the handler was already inactive. |
---|
| 173 | * |
---|
| 174 | * Returns: |
---|
| 175 | * {Boolean} The handler was deactivated. |
---|
| 176 | */ |
---|
| 177 | deactivate: function() { |
---|
| 178 | if(!this.active) { |
---|
| 179 | return false; |
---|
| 180 | } |
---|
| 181 | // unregister event handlers defined on this class. |
---|
| 182 | var events = OpenLayers.Events.prototype.BROWSER_EVENTS; |
---|
| 183 | for (var i=0, len=events.length; i<len; i++) { |
---|
| 184 | if (this[events[i]]) { |
---|
| 185 | this.unregister(events[i], this[events[i]]); |
---|
| 186 | } |
---|
| 187 | } |
---|
| 188 | this.active = false; |
---|
| 189 | return true; |
---|
| 190 | }, |
---|
| 191 | |
---|
| 192 | /** |
---|
| 193 | * Method: callback |
---|
| 194 | * Trigger the control's named callback with the given arguments |
---|
| 195 | * |
---|
| 196 | * Parameters: |
---|
| 197 | * name - {String} The key for the callback that is one of the properties |
---|
| 198 | * of the handler's callbacks object. |
---|
| 199 | * args - {Array(*)} An array of arguments (any type) with which to call |
---|
| 200 | * the callback (defined by the control). |
---|
| 201 | */ |
---|
| 202 | callback: function (name, args) { |
---|
| 203 | if (name && this.callbacks[name]) { |
---|
| 204 | this.callbacks[name].apply(this.control, args); |
---|
| 205 | } |
---|
| 206 | }, |
---|
| 207 | |
---|
| 208 | /** |
---|
| 209 | * Method: register |
---|
| 210 | * register an event on the map |
---|
| 211 | */ |
---|
| 212 | register: function (name, method) { |
---|
| 213 | // TODO: deal with registerPriority in 3.0 |
---|
| 214 | this.map.events.registerPriority(name, this, method); |
---|
| 215 | this.map.events.registerPriority(name, this, this.setEvent); |
---|
| 216 | }, |
---|
| 217 | |
---|
| 218 | /** |
---|
| 219 | * Method: unregister |
---|
| 220 | * unregister an event from the map |
---|
| 221 | */ |
---|
| 222 | unregister: function (name, method) { |
---|
| 223 | this.map.events.unregister(name, this, method); |
---|
| 224 | this.map.events.unregister(name, this, this.setEvent); |
---|
| 225 | }, |
---|
| 226 | |
---|
| 227 | /** |
---|
| 228 | * Method: setEvent |
---|
| 229 | * With each registered browser event, the handler sets its own evt |
---|
| 230 | * property. This property can be accessed by controls if needed |
---|
| 231 | * to get more information about the event that the handler is |
---|
| 232 | * processing. |
---|
| 233 | * |
---|
| 234 | * This allows modifier keys on the event to be checked (alt, shift, |
---|
| 235 | * and ctrl cannot be checked with the keyboard handler). For a |
---|
| 236 | * control to determine which modifier keys are associated with the |
---|
| 237 | * event that a handler is currently processing, it should access |
---|
| 238 | * (code)handler.evt.altKey || handler.evt.shiftKey || |
---|
| 239 | * handler.evt.ctrlKey(end). |
---|
| 240 | * |
---|
| 241 | * Parameters: |
---|
| 242 | * evt - {Event} The browser event. |
---|
| 243 | */ |
---|
| 244 | setEvent: function(evt) { |
---|
| 245 | this.evt = evt; |
---|
| 246 | return true; |
---|
| 247 | }, |
---|
| 248 | |
---|
| 249 | /** |
---|
| 250 | * Method: destroy |
---|
| 251 | * Deconstruct the handler. |
---|
| 252 | */ |
---|
| 253 | destroy: function () { |
---|
| 254 | // unregister event listeners |
---|
| 255 | this.deactivate(); |
---|
| 256 | // eliminate circular references |
---|
| 257 | this.control = this.map = null; |
---|
| 258 | }, |
---|
| 259 | |
---|
| 260 | CLASS_NAME: "OpenLayers.Handler" |
---|
| 261 | }); |
---|
| 262 | |
---|
| 263 | /** |
---|
| 264 | * Constant: OpenLayers.Handler.MOD_NONE |
---|
| 265 | * If set as the <keyMask>, <checkModifiers> returns false if any key is down. |
---|
| 266 | */ |
---|
| 267 | OpenLayers.Handler.MOD_NONE = 0; |
---|
| 268 | |
---|
| 269 | /** |
---|
| 270 | * Constant: OpenLayers.Handler.MOD_SHIFT |
---|
| 271 | * If set as the <keyMask>, <checkModifiers> returns false if Shift is down. |
---|
| 272 | */ |
---|
| 273 | OpenLayers.Handler.MOD_SHIFT = 1; |
---|
| 274 | |
---|
| 275 | /** |
---|
| 276 | * Constant: OpenLayers.Handler.MOD_CTRL |
---|
| 277 | * If set as the <keyMask>, <checkModifiers> returns false if Ctrl is down. |
---|
| 278 | */ |
---|
| 279 | OpenLayers.Handler.MOD_CTRL = 2; |
---|
| 280 | |
---|
| 281 | /** |
---|
| 282 | * Constant: OpenLayers.Handler.MOD_ALT |
---|
| 283 | * If set as the <keyMask>, <checkModifiers> returns false if Alt is down. |
---|
| 284 | */ |
---|
| 285 | OpenLayers.Handler.MOD_ALT = 4; |
---|
| 286 | |
---|
| 287 | |
---|