[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/Console.js |
---|
| 8 | */ |
---|
| 9 | |
---|
| 10 | /** |
---|
| 11 | * Class: OpenLayers.Control |
---|
| 12 | * Controls affect the display or behavior of the map. They allow everything |
---|
| 13 | * from panning and zooming to displaying a scale indicator. Controls by |
---|
| 14 | * default are added to the map they are contained within however it is |
---|
| 15 | * possible to add a control to an external div by passing the div in the |
---|
| 16 | * options parameter. |
---|
| 17 | * |
---|
| 18 | * Example: |
---|
| 19 | * The following example shows how to add many of the common controls |
---|
| 20 | * to a map. |
---|
| 21 | * |
---|
| 22 | * > var map = new OpenLayers.Map('map', { controls: [] }); |
---|
| 23 | * > |
---|
| 24 | * > map.addControl(new OpenLayers.Control.PanZoomBar()); |
---|
| 25 | * > map.addControl(new OpenLayers.Control.MouseToolbar()); |
---|
| 26 | * > map.addControl(new OpenLayers.Control.LayerSwitcher({'ascending':false})); |
---|
| 27 | * > map.addControl(new OpenLayers.Control.Permalink()); |
---|
| 28 | * > map.addControl(new OpenLayers.Control.Permalink('permalink')); |
---|
| 29 | * > map.addControl(new OpenLayers.Control.MousePosition()); |
---|
| 30 | * > map.addControl(new OpenLayers.Control.OverviewMap()); |
---|
| 31 | * > map.addControl(new OpenLayers.Control.KeyboardDefaults()); |
---|
| 32 | * |
---|
| 33 | * The next code fragment is a quick example of how to intercept |
---|
| 34 | * shift-mouse click to display the extent of the bounding box |
---|
| 35 | * dragged out by the user. Usually controls are not created |
---|
| 36 | * in exactly this manner. See the source for a more complete |
---|
| 37 | * example: |
---|
| 38 | * |
---|
| 39 | * > var control = new OpenLayers.Control(); |
---|
| 40 | * > OpenLayers.Util.extend(control, { |
---|
| 41 | * > draw: function () { |
---|
| 42 | * > // this Handler.Box will intercept the shift-mousedown |
---|
| 43 | * > // before Control.MouseDefault gets to see it |
---|
| 44 | * > this.box = new OpenLayers.Handler.Box( control, |
---|
| 45 | * > {"done": this.notice}, |
---|
| 46 | * > {keyMask: OpenLayers.Handler.MOD_SHIFT}); |
---|
| 47 | * > this.box.activate(); |
---|
| 48 | * > }, |
---|
| 49 | * > |
---|
| 50 | * > notice: function (bounds) { |
---|
| 51 | * > OpenLayers.Console.userError(bounds); |
---|
| 52 | * > } |
---|
| 53 | * > }); |
---|
| 54 | * > map.addControl(control); |
---|
| 55 | * |
---|
| 56 | */ |
---|
| 57 | OpenLayers.Control = OpenLayers.Class({ |
---|
| 58 | |
---|
| 59 | /** |
---|
| 60 | * Property: id |
---|
| 61 | * {String} |
---|
| 62 | */ |
---|
| 63 | id: null, |
---|
| 64 | |
---|
| 65 | /** |
---|
| 66 | * Property: map |
---|
| 67 | * {<OpenLayers.Map>} this gets set in the addControl() function in |
---|
| 68 | * OpenLayers.Map |
---|
| 69 | */ |
---|
| 70 | map: null, |
---|
| 71 | |
---|
| 72 | /** |
---|
| 73 | * Property: div |
---|
| 74 | * {DOMElement} |
---|
| 75 | */ |
---|
| 76 | div: null, |
---|
| 77 | |
---|
| 78 | /** |
---|
| 79 | * Property: type |
---|
| 80 | * {Number} Controls can have a 'type'. The type determines the type of |
---|
| 81 | * interactions which are possible with them when they are placed in an |
---|
| 82 | * <OpenLayers.Control.Panel>. |
---|
| 83 | */ |
---|
| 84 | type: null, |
---|
| 85 | |
---|
| 86 | /** |
---|
| 87 | * Property: allowSelection |
---|
| 88 | * {Boolean} By deafault, controls do not allow selection, because |
---|
| 89 | * it may interfere with map dragging. If this is true, OpenLayers |
---|
| 90 | * will not prevent selection of the control. |
---|
| 91 | * Default is false. |
---|
| 92 | */ |
---|
| 93 | allowSelection: false, |
---|
| 94 | |
---|
| 95 | /** |
---|
| 96 | * Property: displayClass |
---|
| 97 | * {string} This property is used for CSS related to the drawing of the |
---|
| 98 | * Control. |
---|
| 99 | */ |
---|
| 100 | displayClass: "", |
---|
| 101 | |
---|
| 102 | /** |
---|
| 103 | * Property: title |
---|
| 104 | * {string} This property is used for showing a tooltip over the |
---|
| 105 | * Control. |
---|
| 106 | */ |
---|
| 107 | title: "", |
---|
| 108 | |
---|
| 109 | /** |
---|
| 110 | * APIProperty: autoActivate |
---|
| 111 | * {Boolean} Activate the control when it is added to a map. Default is |
---|
| 112 | * false. |
---|
| 113 | */ |
---|
| 114 | autoActivate: false, |
---|
| 115 | |
---|
| 116 | /** |
---|
| 117 | * Property: active |
---|
| 118 | * {Boolean} The control is active. |
---|
| 119 | */ |
---|
| 120 | active: null, |
---|
| 121 | |
---|
| 122 | /** |
---|
| 123 | * Property: handler |
---|
| 124 | * {<OpenLayers.Handler>} null |
---|
| 125 | */ |
---|
| 126 | handler: null, |
---|
| 127 | |
---|
| 128 | /** |
---|
| 129 | * APIProperty: eventListeners |
---|
| 130 | * {Object} If set as an option at construction, the eventListeners |
---|
| 131 | * object will be registered with <OpenLayers.Events.on>. Object |
---|
| 132 | * structure must be a listeners object as shown in the example for |
---|
| 133 | * the events.on method. |
---|
| 134 | */ |
---|
| 135 | eventListeners: null, |
---|
| 136 | |
---|
| 137 | /** |
---|
| 138 | * Property: events |
---|
| 139 | * {<OpenLayers.Events>} Events instance for triggering control specific |
---|
| 140 | * events. |
---|
| 141 | */ |
---|
| 142 | events: null, |
---|
| 143 | |
---|
| 144 | /** |
---|
| 145 | * Constant: EVENT_TYPES |
---|
| 146 | * {Array(String)} Supported application event types. Register a listener |
---|
| 147 | * for a particular event with the following syntax: |
---|
| 148 | * (code) |
---|
| 149 | * control.events.register(type, obj, listener); |
---|
| 150 | * (end) |
---|
| 151 | * |
---|
| 152 | * Listeners will be called with a reference to an event object. The |
---|
| 153 | * properties of this event depends on exactly what happened. |
---|
| 154 | * |
---|
| 155 | * All event objects have at least the following properties: |
---|
| 156 | * object - {Object} A reference to control.events.object (a reference |
---|
| 157 | * to the control). |
---|
| 158 | * element - {DOMElement} A reference to control.events.element (which |
---|
| 159 | * will be null unless documented otherwise). |
---|
| 160 | * |
---|
| 161 | * Supported map event types: |
---|
| 162 | * activate - Triggered when activated. |
---|
| 163 | * deactivate - Triggered when deactivated. |
---|
| 164 | */ |
---|
| 165 | EVENT_TYPES: ["activate", "deactivate"], |
---|
| 166 | |
---|
| 167 | /** |
---|
| 168 | * Constructor: OpenLayers.Control |
---|
| 169 | * Create an OpenLayers Control. The options passed as a parameter |
---|
| 170 | * directly extend the control. For example passing the following: |
---|
| 171 | * |
---|
| 172 | * > var control = new OpenLayers.Control({div: myDiv}); |
---|
| 173 | * |
---|
| 174 | * Overrides the default div attribute value of null. |
---|
| 175 | * |
---|
| 176 | * Parameters: |
---|
| 177 | * options - {Object} |
---|
| 178 | */ |
---|
| 179 | initialize: function (options) { |
---|
| 180 | // We do this before the extend so that instances can override |
---|
| 181 | // className in options. |
---|
| 182 | this.displayClass = |
---|
| 183 | this.CLASS_NAME.replace("OpenLayers.", "ol").replace(/\./g, ""); |
---|
| 184 | |
---|
| 185 | OpenLayers.Util.extend(this, options); |
---|
| 186 | |
---|
| 187 | this.events = new OpenLayers.Events(this, null, this.EVENT_TYPES); |
---|
| 188 | if(this.eventListeners instanceof Object) { |
---|
| 189 | this.events.on(this.eventListeners); |
---|
| 190 | } |
---|
| 191 | if (this.id == null) { |
---|
| 192 | this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_"); |
---|
| 193 | } |
---|
| 194 | }, |
---|
| 195 | |
---|
| 196 | /** |
---|
| 197 | * Method: destroy |
---|
| 198 | * The destroy method is used to perform any clean up before the control |
---|
| 199 | * is dereferenced. Typically this is where event listeners are removed |
---|
| 200 | * to prevent memory leaks. |
---|
| 201 | */ |
---|
| 202 | destroy: function () { |
---|
| 203 | if(this.events) { |
---|
| 204 | if(this.eventListeners) { |
---|
| 205 | this.events.un(this.eventListeners); |
---|
| 206 | } |
---|
| 207 | this.events.destroy(); |
---|
| 208 | this.events = null; |
---|
| 209 | } |
---|
| 210 | this.eventListeners = null; |
---|
| 211 | |
---|
| 212 | // eliminate circular references |
---|
| 213 | if (this.handler) { |
---|
| 214 | this.handler.destroy(); |
---|
| 215 | this.handler = null; |
---|
| 216 | } |
---|
| 217 | if(this.handlers) { |
---|
| 218 | for(var key in this.handlers) { |
---|
| 219 | if(this.handlers.hasOwnProperty(key) && |
---|
| 220 | typeof this.handlers[key].destroy == "function") { |
---|
| 221 | this.handlers[key].destroy(); |
---|
| 222 | } |
---|
| 223 | } |
---|
| 224 | this.handlers = null; |
---|
| 225 | } |
---|
| 226 | if (this.map) { |
---|
| 227 | this.map.removeControl(this); |
---|
| 228 | this.map = null; |
---|
| 229 | } |
---|
| 230 | }, |
---|
| 231 | |
---|
| 232 | /** |
---|
| 233 | * Method: setMap |
---|
| 234 | * Set the map property for the control. This is done through an accessor |
---|
| 235 | * so that subclasses can override this and take special action once |
---|
| 236 | * they have their map variable set. |
---|
| 237 | * |
---|
| 238 | * Parameters: |
---|
| 239 | * map - {<OpenLayers.Map>} |
---|
| 240 | */ |
---|
| 241 | setMap: function(map) { |
---|
| 242 | this.map = map; |
---|
| 243 | if (this.handler) { |
---|
| 244 | this.handler.setMap(map); |
---|
| 245 | } |
---|
| 246 | }, |
---|
| 247 | |
---|
| 248 | /** |
---|
| 249 | * Method: draw |
---|
| 250 | * The draw method is called when the control is ready to be displayed |
---|
| 251 | * on the page. If a div has not been created one is created. Controls |
---|
| 252 | * with a visual component will almost always want to override this method |
---|
| 253 | * to customize the look of control. |
---|
| 254 | * |
---|
| 255 | * Parameters: |
---|
| 256 | * px - {<OpenLayers.Pixel>} The top-left pixel position of the control |
---|
| 257 | * or null. |
---|
| 258 | * |
---|
| 259 | * Returns: |
---|
| 260 | * {DOMElement} A reference to the DIV DOMElement containing the control |
---|
| 261 | */ |
---|
| 262 | draw: function (px) { |
---|
| 263 | if (this.div == null) { |
---|
| 264 | this.div = OpenLayers.Util.createDiv(this.id); |
---|
| 265 | this.div.className = this.displayClass; |
---|
| 266 | if (!this.allowSelection) { |
---|
| 267 | this.div.className += " olControlNoSelect"; |
---|
| 268 | this.div.setAttribute("unselectable", "on", 0); |
---|
| 269 | this.div.onselectstart = OpenLayers.Function.False; |
---|
| 270 | } |
---|
| 271 | if (this.title != "") { |
---|
| 272 | this.div.title = this.title; |
---|
| 273 | } |
---|
| 274 | } |
---|
| 275 | if (px != null) { |
---|
| 276 | this.position = px.clone(); |
---|
| 277 | } |
---|
| 278 | this.moveTo(this.position); |
---|
| 279 | return this.div; |
---|
| 280 | }, |
---|
| 281 | |
---|
| 282 | /** |
---|
| 283 | * Method: moveTo |
---|
| 284 | * Sets the left and top style attributes to the passed in pixel |
---|
| 285 | * coordinates. |
---|
| 286 | * |
---|
| 287 | * Parameters: |
---|
| 288 | * px - {<OpenLayers.Pixel>} |
---|
| 289 | */ |
---|
| 290 | moveTo: function (px) { |
---|
| 291 | if ((px != null) && (this.div != null)) { |
---|
| 292 | this.div.style.left = px.x + "px"; |
---|
| 293 | this.div.style.top = px.y + "px"; |
---|
| 294 | } |
---|
| 295 | }, |
---|
| 296 | |
---|
| 297 | /** |
---|
| 298 | * Method: activate |
---|
| 299 | * Explicitly activates a control and it's associated |
---|
| 300 | * handler if one has been set. Controls can be |
---|
| 301 | * deactivated by calling the deactivate() method. |
---|
| 302 | * |
---|
| 303 | * Returns: |
---|
| 304 | * {Boolean} True if the control was successfully activated or |
---|
| 305 | * false if the control was already active. |
---|
| 306 | */ |
---|
| 307 | activate: function () { |
---|
| 308 | if (this.active) { |
---|
| 309 | return false; |
---|
| 310 | } |
---|
| 311 | if (this.handler) { |
---|
| 312 | this.handler.activate(); |
---|
| 313 | } |
---|
| 314 | this.active = true; |
---|
| 315 | if(this.map) { |
---|
| 316 | OpenLayers.Element.addClass( |
---|
| 317 | this.map.viewPortDiv, |
---|
| 318 | this.displayClass.replace(/ /g, "") + "Active" |
---|
| 319 | ); |
---|
| 320 | } |
---|
| 321 | this.events.triggerEvent("activate"); |
---|
| 322 | return true; |
---|
| 323 | }, |
---|
| 324 | |
---|
| 325 | /** |
---|
| 326 | * Method: deactivate |
---|
| 327 | * Deactivates a control and it's associated handler if any. The exact |
---|
| 328 | * effect of this depends on the control itself. |
---|
| 329 | * |
---|
| 330 | * Returns: |
---|
| 331 | * {Boolean} True if the control was effectively deactivated or false |
---|
| 332 | * if the control was already inactive. |
---|
| 333 | */ |
---|
| 334 | deactivate: function () { |
---|
| 335 | if (this.active) { |
---|
| 336 | if (this.handler) { |
---|
| 337 | this.handler.deactivate(); |
---|
| 338 | } |
---|
| 339 | this.active = false; |
---|
| 340 | if(this.map) { |
---|
| 341 | OpenLayers.Element.removeClass( |
---|
| 342 | this.map.viewPortDiv, |
---|
| 343 | this.displayClass.replace(/ /g, "") + "Active" |
---|
| 344 | ); |
---|
| 345 | } |
---|
| 346 | this.events.triggerEvent("deactivate"); |
---|
| 347 | return true; |
---|
| 348 | } |
---|
| 349 | return false; |
---|
| 350 | }, |
---|
| 351 | |
---|
| 352 | CLASS_NAME: "OpenLayers.Control" |
---|
| 353 | }); |
---|
| 354 | |
---|
| 355 | /** |
---|
| 356 | * Constant: OpenLayers.Control.TYPE_BUTTON |
---|
| 357 | */ |
---|
| 358 | OpenLayers.Control.TYPE_BUTTON = 1; |
---|
| 359 | |
---|
| 360 | /** |
---|
| 361 | * Constant: OpenLayers.Control.TYPE_TOGGLE |
---|
| 362 | */ |
---|
| 363 | OpenLayers.Control.TYPE_TOGGLE = 2; |
---|
| 364 | |
---|
| 365 | /** |
---|
| 366 | * Constant: OpenLayers.Control.TYPE_TOOL |
---|
| 367 | */ |
---|
| 368 | OpenLayers.Control.TYPE_TOOL = 3; |
---|