--- a/labs/openlayers/lib/OpenLayers/Handler/Point.js +++ b/labs/openlayers/lib/OpenLayers/Handler/Point.js @@ -1,1 +1,374 @@ - +/* 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/Handler.js + * @requires OpenLayers/Geometry/Point.js + */ + +/** + * Class: OpenLayers.Handler.Point + * Handler to draw a point on the map. Point is displayed on mouse down, + * moves on mouse move, and is finished on mouse up. The handler triggers + * callbacks for 'done', 'cancel', and 'modify'. The modify callback is + * called with each change in the sketch and will receive the latest point + * drawn. Create a new instance with the <OpenLayers.Handler.Point> + * constructor. + * + * Inherits from: + * - <OpenLayers.Handler> + */ +OpenLayers.Handler.Point = OpenLayers.Class(OpenLayers.Handler, { + + /** + * Property: point + * {<OpenLayers.Feature.Vector>} The currently drawn point + */ + point: null, + + /** + * Property: layer + * {<OpenLayers.Layer.Vector>} The temporary drawing layer + */ + layer: null, + + /** + * APIProperty: multi + * {Boolean} Cast features to multi-part geometries before passing to the + * layer. Default is false. + */ + multi: false, + + /** + * Property: drawing + * {Boolean} A point is being drawn + */ + drawing: false, + + /** + * Property: mouseDown + * {Boolean} The mouse is down + */ + mouseDown: false, + + /** + * Property: lastDown + * {<OpenLayers.Pixel>} Location of the last mouse down + */ + lastDown: null, + + /** + * Property: lastUp + * {<OpenLayers.Pixel>} + */ + lastUp: null, + + /** + * APIProperty: persist + * {Boolean} Leave the feature rendered until destroyFeature is called. + * Default is false. If set to true, the feature remains rendered until + * destroyFeature is called, typically by deactivating the handler or + * starting another drawing. + */ + persist: false, + + /** + * Property: layerOptions + * {Object} Any optional properties to be set on the sketch layer. + */ + layerOptions: null, + + /** + * Constructor: OpenLayers.Handler.Point + * Create a new point handler. + * + * Parameters: + * control - {<OpenLayers.Control>} The control that owns this handler + * callbacks - {Object} An object with a properties whose values are + * functions. Various callbacks described below. + * options - {Object} An optional object with properties to be set on the + * handler + * + * Named callbacks: + * create - Called when a sketch is first created. Callback called with + * the creation point geometry and sketch feature. + * modify - Called with each move of a vertex with the vertex (point) + * geometry and the sketch feature. + * done - Called when the point drawing is finished. The callback will + * recieve a single argument, the point geometry. + * cancel - Called when the handler is deactivated while drawing. The + * cancel callback will receive a geometry. + */ + initialize: function(control, callbacks, options) { + if(!(options && options.layerOptions && options.layerOptions.styleMap)) { + this.style = OpenLayers.Util.extend(OpenLayers.Feature.Vector.style['default'], {}); + } + + OpenLayers.Handler.prototype.initialize.apply(this, arguments); + }, + + /** + * APIMethod: activate + * turn on the handler + */ + activate: function() { + if(!OpenLayers.Handler.prototype.activate.apply(this, arguments)) { + return false; + } + // create temporary vector layer for rendering geometry sketch + // TBD: this could be moved to initialize/destroy - setting visibility here + var options = OpenLayers.Util.extend({ + displayInLayerSwitcher: false, + // indicate that the temp vector layer will never be out of range + // without this, resolution properties must be specified at the + // map-level for this temporary layer to init its resolutions + // correctly + calculateInRange: OpenLayers.Function.True + }, this.layerOptions); + this.layer = new OpenLayers.Layer.Vector(this.CLASS_NAME, options); + this.map.addLayer(this.layer); + return true; + }, + + /** + * Method: createFeature + * Add temporary features + * + * Parameters: + * pixel - {<OpenLayers.Pixel>} A pixel location on the map. + */ + createFeature: function(pixel) { + var lonlat = this.map.getLonLatFromPixel(pixel); + this.point = new OpenLayers.Feature.Vector( + new OpenLayers.Geometry.Point(lonlat.lon, lonlat.lat) + ); + this.callback("create", [this.point.geometry, this.point]); + this.point.geometry.clearBounds(); + this.layer.addFeatures([this.point], {silent: true}); + }, + + /** + * APIMethod: deactivate + * turn off the handler + */ + deactivate: function() { + if(!OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) { + return false; + } + // call the cancel callback if mid-drawing + if(this.drawing) { + this.cancel(); + } + this.destroyFeature(); + // If a layer's map property is set to null, it means that that layer + // isn't added to the map. Since we ourself added the layer to the map + // in activate(), we can assume that if this.layer.map is null it means + // that the layer has been destroyed (as a result of map.destroy() for + // example. + if (this.layer.map != null) { + this.layer.destroy(false); + } + this.layer = null; + return true; + }, + + /** + * Method: destroyFeature + * Destroy the temporary geometries + */ + destroyFeature: function() { + if(this.layer) { + this.layer.destroyFeatures(); + } + this.point = null; + }, + + /** + * Method: finalize + * Finish the geometry and call the "done" callback. + * + * Parameters: + * cancel - {Boolean} Call cancel instead of done callback. Default is + * false. + */ + finalize: function(cancel) { + var key = cancel ? "cancel" : "done"; + this.drawing = false; + this.mouseDown = false; + this.lastDown = null; + this.lastUp = null; + this.callback(key, [this.geometryClone()]); + if(cancel || !this.persist) { + this.destroyFeature(); + } + }, + + /** + * APIMethod: cancel + * Finish the geometry and call the "cancel" callback. + */ + cancel: function() { + this.finalize(true); + }, + + /** + * Method: click + * Handle clicks. Clicks are stopped from propagating to other listeners + * on map.events or other dom elements. + * + * Parameters: + * evt - {Event} The browser event + * + * Returns: + * {Boolean} Allow event propagation + */ + click: function(evt) { + OpenLayers.Event.stop(evt); + return false; + }, + + /** + * Method: dblclick + * Handle double-clicks. Double-clicks are stopped from propagating to other + * listeners on map.events or other dom elements. + * + * Parameters: + * evt - {Event} The browser event + * + * Returns: + * {Boolean} Allow event propagation + */ + dblclick: function(evt) { + OpenLayers.Event.stop(evt); + return false; + }, + + /** + * Method: modifyFeature + * Modify the existing geometry given a pixel location. + * + * Parameters: + * pixel - {<OpenLayers.Pixel>} A pixel location on the map. + */ + modifyFeature: function(pixel) { + var lonlat = this.map.getLonLatFromPixel(pixel); + this.point.geometry.x = lonlat.lon; + this.point.geometry.y = lonlat.lat; + this.callback("modify", [this.point.geometry, this.point]); + this.point.geometry.clearBounds(); + this.drawFeature(); + }, + + /** + * Method: drawFeature + * Render features on the temporary layer. + */ + drawFeature: function() { + this.layer.drawFeature(this.point, this.style); + }, + + /** + * Method: getGeometry + * Return the sketch geometry. If <multi> is true, this will return + * a multi-part geometry. + * + * Returns: + * {<OpenLayers.Geometry.Point>} + */ + getGeometry: function() { + var geometry = this.point && this.point.geometry; + if(geometry && this.multi) { + geometry = new OpenLayers.Geometry.MultiPoint([geometry]); + } + return geometry; + }, + + /** + * Method: geometryClone + * Return a clone of the relevant geometry. + * + * Returns: + * {<OpenLayers.Geometry>} + */ + geometryClone: function() { + var geom = this.getGeometry(); + return geom && geom.clone(); + }, + + /** + * Method: mousedown + * Handle mouse down. Adjust the geometry and redraw. + * Return determines whether to propagate the event on the map. + * + * Parameters: + * evt - {Event} The browser event + * + * Returns: + * {Boolean} Allow event propagation + */ + mousedown: function(evt) { + // check keyboard modifiers + if(!this.checkModifiers(evt)) { + return true; + } + // ignore double-clicks + if(this.lastDown && this.lastDown.equals(evt.xy)) { + return true; + } + this.drawing = true; + if(this.lastDown == null) { + if(this.persist) { + this.destroyFeature(); + } + this.createFeature(evt.xy); + } else { + this.modifyFeature(evt.xy); + } + this.lastDown = evt.xy; + return false; + }, + + /** + * Method: mousemove + * Handle mouse move. Adjust the geometry and redraw. + * Return determines whether to propagate the event on the map. + * + * Parameters: + * evt - {Event} The browser event + * + * Returns: + * {Boolean} Allow event propagation + */ + mousemove: function (evt) { + if(this.drawing) { + this.modifyFeature(evt.xy); + } + return true; + }, + + /** + * Method: mouseup + * Handle mouse up. Send the latest point in the geometry to the control. + * Return determines whether to propagate the event on the map. + * + * Parameters: + * evt - {Event} The browser event + * + * Returns: + * {Boolean} Allow event propagation + */ + mouseup: function (evt) { + if(this.drawing) { + this.finalize(); + return false; + } else { + return true; + } + }, + + CLASS_NAME: "OpenLayers.Handler.Point" +}); +