--- a/labs/openlayers/lib/OpenLayers/Control/GetFeature.js +++ b/labs/openlayers/lib/OpenLayers/Control/GetFeature.js @@ -1,1 +1,596 @@ - +/* 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/Control.js + * @requires OpenLayers/Handler/Click.js + * @requires OpenLayers/Handler/Box.js + * @requires OpenLayers/Handler/Hover.js + * @requires OpenLayers/Filter/Spatial.js + */ + +/** + * Class: OpenLayers.Control.GetFeature + * Gets vector features for locations underneath the mouse cursor. Can be + * configured to act on click, hover or dragged boxes. Uses an + * <OpenLayers.Protocol> that supports spatial filters to retrieve + * features from a server and fires events that notify applications of the + * selected features. + * + * Inherits from: + * - <OpenLayers.Control> + */ +OpenLayers.Control.GetFeature = OpenLayers.Class(OpenLayers.Control, { + + /** + * APIProperty: protocol + * {<OpenLayers.Protocol>} Required. The protocol used for fetching + * features. + */ + protocol: null, + + /** + * APIProperty: multipleKey + * {String} An event modifier ('altKey' or 'shiftKey') that temporarily sets + * the <multiple> property to true. Default is null. + */ + multipleKey: null, + + /** + * APIProperty: toggleKey + * {String} An event modifier ('altKey' or 'shiftKey') that temporarily sets + * the <toggle> property to true. Default is null. + */ + toggleKey: null, + + /** + * Property: modifiers + * {Object} The event modifiers to use, according to the current event + * being handled by this control's handlers + */ + modifiers: null, + + /** + * APIProperty: multiple + * {Boolean} Allow selection of multiple geometries. Default is false. + */ + multiple: false, + + /** + * APIProperty: click + * {Boolean} Use a click handler for selecting/unselecting features. If + * both <click> and <box> are set to true, the click handler takes + * precedence over the box handler if a box with zero extent was + * selected. Default is true. + */ + click: true, + + /** + * APIProperty: single + * {Boolean} Tells whether select by click should select a single + * feature. If set to false, all matching features are selected. + * If set to true, only the best matching feature is selected. + * This option has an effect only of the <click> option is set + * to true. Default is true. + */ + single: true, + + /** + * APIProperty: clickout + * {Boolean} Unselect features when clicking outside any feature. + * Applies only if <click> is true. Default is true. + */ + clickout: true, + + /** + * APIProperty: toggle + * {Boolean} Unselect a selected feature on click. Applies only if + * <click> is true. Default is false. + */ + toggle: false, + + /** + * APIProperty: clickTolerance + * {Integer} Tolerance for the filter query in pixels. This has the + * same effect as the tolerance parameter on WMS GetFeatureInfo + * requests. Will be ignored for box selections. Applies only if + * <click> or <hover> is true. Default is 5. Note that this not + * only affects requests on click, but also on hover. + */ + clickTolerance: 5, + + /** + * APIProperty: hover + * {Boolean} Send feature requests on mouse moves. Default is false. + */ + hover: false, + + /** + * APIProperty: box + * {Boolean} Allow feature selection by drawing a box. If set to + * true set <click> to false to disable the click handler and + * rely on the box handler only, even for "zero extent" boxes. + * See the description of the <click> option for additional + * information. Default is false. + */ + box: false, + + /** + * APIProperty: maxFeatures + * {Integer} Maximum number of features to return from a query in single mode + * if supported by the <protocol>. This set of features is then used to + * determine the best match client-side. Default is 10. + */ + maxFeatures: 10, + + /** + * Property: features + * {Object} Hash of {<OpenLayers.Feature.Vector>}, keyed by fid, holding + * the currently selected features + */ + features: null, + + /** + * Proeprty: hoverFeature + * {<OpenLayers.Feature.Vector>} The feature currently selected by the + * hover handler + */ + hoverFeature: null, + + /** + * APIProperty: handlerOptions + * {Object} Additional options for the handlers used by this control. This + * is a hash with the keys "click", "box" and "hover". + */ + handlerOptions: null, + + /** + * Property: handlers + * {Object} Object with references to multiple <OpenLayers.Handler> + * instances. + */ + handlers: null, + + /** + * Property: hoverResponse + * {<OpenLayers.Protocol.Response>} The response object associated with + * the currently running hover request (if any). + */ + hoverResponse: null, + + /** + * Property: filterType + * {<String>} The type of filter to use when sending off a request. + * Possible values: + * OpenLayers.Filter.Spatial.<BBOX|INTERSECTS|WITHIN|CONTAINS> + * Defaults to: OpenLayers.Filter.Spatial.BBOX + */ + filterType: OpenLayers.Filter.Spatial.BBOX, + + /** + * Constant: EVENT_TYPES + * + * Supported event types: + * beforefeatureselected - Triggered when <click> is true before a + * feature is selected. The event object has a feature property with + * the feature about to select + * featureselected - Triggered when <click> is true and a feature is + * selected. The event object has a feature property with the + * selected feature + * beforefeaturesselected - Triggered when <click> is true before a + * set of features is selected. The event object is an array of + * feature properties with the features about to be selected. + * Return false after receiving this event to discontinue processing + * of all featureselected events and the featuresselected event. + * featuresselected - Triggered when <click> is true and a set of + * features is selected. The event object is an array of feature + * properties of the selected features + * featureunselected - Triggered when <click> is true and a feature is + * unselected. The event object has a feature property with the + * unselected feature + * clickout - Triggered when when <click> is true and no feature was + * selected. + * hoverfeature - Triggered when <hover> is true and the mouse has + * stopped over a feature + * outfeature - Triggered when <hover> is true and the mouse moves + * moved away from a hover-selected feature + */ + EVENT_TYPES: ["featureselected", "featuresselected", "featureunselected", + "clickout", "beforefeatureselected", "beforefeaturesselected", + "hoverfeature", "outfeature"], + + /** + * Constructor: OpenLayers.Control.GetFeature + * Create a new control for fetching remote features. + * + * Parameters: + * options - {Object} A configuration object which at least has to contain + * a <protocol> property + */ + initialize: function(options) { + // concatenate events specific to vector with those from the base + this.EVENT_TYPES = + OpenLayers.Control.GetFeature.prototype.EVENT_TYPES.concat( + OpenLayers.Control.prototype.EVENT_TYPES + ); + + options.handlerOptions = options.handlerOptions || {}; + + OpenLayers.Control.prototype.initialize.apply(this, [options]); + + this.features = {}; + + this.handlers = {}; + + if(this.click) { + this.handlers.click = new OpenLayers.Handler.Click(this, + {click: this.selectClick}, this.handlerOptions.click || {}); + } + + if(this.box) { + this.handlers.box = new OpenLayers.Handler.Box( + this, {done: this.selectBox}, + OpenLayers.Util.extend(this.handlerOptions.box, { + boxDivClassName: "olHandlerBoxSelectFeature" + }) + ); + } + + if(this.hover) { + this.handlers.hover = new OpenLayers.Handler.Hover( + this, {'move': this.cancelHover, 'pause': this.selectHover}, + OpenLayers.Util.extend(this.handlerOptions.hover, { + 'delay': 250 + }) + ); + } + }, + + /** + * Method: activate + * Activates the control. + * + * Returns: + * {Boolean} The control was effectively activated. + */ + activate: function () { + if (!this.active) { + for(var i in this.handlers) { + this.handlers[i].activate(); + } + } + return OpenLayers.Control.prototype.activate.apply( + this, arguments + ); + }, + + /** + * Method: deactivate + * Deactivates the control. + * + * Returns: + * {Boolean} The control was effectively deactivated. + */ + deactivate: function () { + if (this.active) { + for(var i in this.handlers) { + this.handlers[i].deactivate(); + } + } + return OpenLayers.Control.prototype.deactivate.apply( + this, arguments + ); + }, + + /** + * Method: selectClick + * Called on click + * + * Parameters: + * evt - {<OpenLayers.Event>} + */ + selectClick: function(evt) { + var bounds = this.pixelToBounds(evt.xy); + + this.setModifiers(evt); + this.request(bounds, {single: this.single}); + }, + + /** + * Method: selectBox + * Callback from the handlers.box set up when <box> selection is on + * + * Parameters: + * position - {<OpenLayers.Bounds>} + */ + selectBox: function(position) { + var bounds; + if (position instanceof OpenLayers.Bounds) { + var minXY = this.map.getLonLatFromPixel( + new OpenLayers.Pixel(position.left, position.bottom) + ); + var maxXY = this.map.getLonLatFromPixel( + new OpenLayers.Pixel(position.right, position.top) + ); + bounds = new OpenLayers.Bounds( + minXY.lon, minXY.lat, maxXY.lon, maxXY.lat + ); + + } else { + if(this.click) { + // box without extent - let the click handler take care of it + return; + } + bounds = this.pixelToBounds(position); + } + this.setModifiers(this.handlers.box.dragHandler.evt); + this.request(bounds); + }, + + /** + * Method selectHover + * Callback from the handlers.hover set up when <hover> selection is on + * + * Parameters: + * evt {Object} - event object with an xy property + */ + selectHover: function(evt) { + var bounds = this.pixelToBounds(evt.xy); + this.request(bounds, {single: true, hover: true}); + }, + + /** + * Method: cancelHover + * Callback from the handlers.hover set up when <hover> selection is on + */ + cancelHover: function() { + if (this.hoverResponse) { + this.protocol.abort(this.hoverResponse); + this.hoverResponse = null; + + OpenLayers.Element.removeClass(this.map.viewPortDiv, "olCursorWait"); + } + }, + + /** + * Method: request + * Sends a GetFeature request to the WFS + * + * Parameters: + * bounds - {<OpenLayers.Bounds>} bounds for the request's BBOX filter + * options - {Object} additional options for this method. + * + * Supported options include: + * single - {Boolean} A single feature should be returned. + * Note that this will be ignored if the protocol does not + * return the geometries of the features. + * hover - {Boolean} Do the request for the hover handler. + */ + request: function(bounds, options) { + options = options || {}; + var filter = new OpenLayers.Filter.Spatial({ + type: this.filterType, + value: bounds + }); + + // Set the cursor to "wait" to tell the user we're working. + OpenLayers.Element.addClass(this.map.viewPortDiv, "olCursorWait"); + + var response = this.protocol.read({ + maxFeatures: options.single == true ? this.maxFeatures : undefined, + filter: filter, + callback: function(result) { + if(result.success()) { + if(result.features.length) { + if(options.single == true) { + this.selectBestFeature(result.features, + bounds.getCenterLonLat(), options); + } else { + this.select(result.features); + } + } else if(options.hover) { + this.hoverSelect(); + } else { + this.events.triggerEvent("clickout"); + if(this.clickout) { + this.unselectAll(); + } + } + } + // Reset the cursor. + OpenLayers.Element.removeClass(this.map.viewPortDiv, "olCursorWait"); + }, + scope: this + }); + if(options.hover == true) { + this.hoverResponse = response; + } + }, + + /** + * Method: selectBestFeature + * Selects the feature from an array of features that is the best match + * for the click position. + * + * Parameters: + * features - {Array(<OpenLayers.Feature.Vector>)} + * clickPosition - {<OpenLayers.LonLat>} + * options - {Object} additional options for this method + * + * Supported options include: + * hover - {Boolean} Do the selection for the hover handler. + */ + selectBestFeature: function(features, clickPosition, options) { + options = options || {}; + if(features.length) { + var point = new OpenLayers.Geometry.Point(clickPosition.lon, + clickPosition.lat); + var feature, resultFeature, dist; + var minDist = Number.MAX_VALUE; + for(var i=0; i<features.length; ++i) { + feature = features[i]; + if(feature.geometry) { + dist = point.distanceTo(feature.geometry, {edge: false}); + if(dist < minDist) { + minDist = dist; + resultFeature = feature; + if(minDist == 0) { + break; + } + } + } + } + + if(options.hover == true) { + this.hoverSelect(resultFeature); + } else { + this.select(resultFeature || features); + } + } + }, + + /** + * Method: setModifiers + * Sets the multiple and toggle modifiers according to the current event + * + * Parameters: + * evt {<OpenLayers.Event>} + */ + setModifiers: function(evt) { + this.modifiers = { + multiple: this.multiple || (this.multipleKey && evt[this.multipleKey]), + toggle: this.toggle || (this.toggleKey && evt[this.toggleKey]) + }; + }, + + /** + * Method: select + * Add feature to the hash of selected features and trigger the + * featureselected and featuresselected events. + * + * Parameters: + * features - {<OpenLayers.Feature.Vector>} or an array of features + */ + select: function(features) { + if(!this.modifiers.multiple && !this.modifiers.toggle) { + this.unselectAll(); + } + if(!(features instanceof Array)) { + features = [features]; + } + + var cont = this.events.triggerEvent("beforefeaturesselected", { + features: features + }); + if(cont !== false) { + var selectedFeatures = []; + var feature; + for(var i=0, len=features.length; i<len; ++i) { + feature = features[i]; + if(this.features[feature.fid || feature.id]) { + if(this.modifiers.toggle) { + this.unselect(this.features[feature.fid || feature.id]); + } + } else { + cont = this.events.triggerEvent("beforefeatureselected", { + feature: feature + }); + if(cont !== false) { + this.features[feature.fid || feature.id] = feature; + selectedFeatures.push(feature); + + this.events.triggerEvent("featureselected", + {feature: feature}); + } + } + } + this.events.triggerEvent("featuresselected", { + features: selectedFeatures + }); + } + }, + + /** + * Method: hoverSelect + * Sets/unsets the <hoverFeature> + * + * Parameters: + * feature - {<OpenLayers.Feature.Vector>} the feature to hover-select. + * If none is provided, the current <hoverFeature> will be nulled and + * the outfeature event will be triggered. + */ + hoverSelect: function(feature) { + var fid = feature ? feature.fid || feature.id : null; + var hfid = this.hoverFeature ? + this.hoverFeature.fid || this.hoverFeature.id : null; + + if(hfid && hfid != fid) { + this.events.triggerEvent("outfeature", + {feature: this.hoverFeature}); + this.hoverFeature = null; + } + if(fid && fid != hfid) { + this.events.triggerEvent("hoverfeature", {feature: feature}); + this.hoverFeature = feature; + } + }, + + /** + * Method: unselect + * Remove feature from the hash of selected features and trigger the + * featureunselected event. + * + * Parameters: + * feature - {<OpenLayers.Feature.Vector>} + */ + unselect: function(feature) { + delete this.features[feature.fid || feature.id]; + this.events.triggerEvent("featureunselected", {feature: feature}); + }, + + /** + * Method: unselectAll + * Unselect all selected features. + */ + unselectAll: function() { + // we'll want an option to supress notification here + for(var fid in this.features) { + this.unselect(this.features[fid]); + } + }, + + /** + * Method: setMap + * Set the map property for the control. + * + * Parameters: + * map - {<OpenLayers.Map>} + */ + setMap: function(map) { + for(var i in this.handlers) { + this.handlers[i].setMap(map); + } + OpenLayers.Control.prototype.setMap.apply(this, arguments); + }, + + /** + * Method: pixelToBounds + * Takes a pixel as argument and creates bounds after adding the + * <clickTolerance>. + * + * Parameters: + * pixel - {<OpenLayers.Pixel>} + */ + pixelToBounds: function(pixel) { + var llPx = pixel.add(-this.clickTolerance/2, this.clickTolerance/2); + var urPx = pixel.add(this.clickTolerance/2, -this.clickTolerance/2); + var ll = this.map.getLonLatFromPixel(llPx); + var ur = this.map.getLonLatFromPixel(urPx); + return new OpenLayers.Bounds(ll.lon, ll.lat, ur.lon, ur.lat); + }, + + CLASS_NAME: "OpenLayers.Control.GetFeature" +}); +