openlayers/lib/OpenLayers/Control/DragFeature.js

   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. */
   4
   5
   6 /**
   7  * @requires OpenLayers/Control.js
   8  * @requires OpenLayers/Handler/Drag.js
   9  * @requires OpenLayers/Handler/Feature.js
  10  */
  11
  12 /**
  13  * Class: OpenLayers.Control.DragFeature
  14  * The DragFeature control moves a feature with a drag of the mouse. Create a
  15  * new control with the <OpenLayers.Control.DragFeature> constructor.
  16  *
  17  * Inherits From:
  18  *  - <OpenLayers.Control>
  19  */
  20 OpenLayers.Control.DragFeature = OpenLayers.Class(OpenLayers.Control, {
  21
  22     /**
  23      * APIProperty: geometryTypes
  24      * {Array(String)} To restrict dragging to a limited set of geometry types,
  25      *     send a list of strings corresponding to the geometry class names.
  26      */
  27     geometryTypes: null,
  28
  29     /**
  30      * APIProperty: onStart
  31      * {Function} Define this function if you want to know when a drag starts.
  32      *     The function should expect to receive two arguments: the feature
  33      *     that is about to be dragged and the pixel location of the mouse.
  34      *
  35      * Parameters:
  36      * feature - {<OpenLayers.Feature.Vector>} The feature that is about to be
  37      *     dragged.
  38      * pixel - {<OpenLayers.Pixel>} The pixel location of the mouse.
  39      */
  40     onStart: function(feature, pixel) {},
  41
  42     /**
  43      * APIProperty: onDrag
  44      * {Function} Define this function if you want to know about each move of a
  45      *     feature. The function should expect to receive two arguments: the
  46      *     feature that is being dragged and the pixel location of the mouse.
  47      *
  48      * Parameters:
  49      * feature - {<OpenLayers.Feature.Vector>} The feature that was dragged.
  50      * pixel - {<OpenLayers.Pixel>} The pixel location of the mouse.
  51      */
  52     onDrag: function(feature, pixel) {},
  53
  54     /**
  55      * APIProperty: onComplete
  56      * {Function} Define this function if you want to know when a feature is
  57      *     done dragging. The function should expect to receive two arguments:
  58      *     the feature that is being dragged and the pixel location of the
  59      *     mouse.
  60      *
  61      * Parameters:
  62      * feature - {<OpenLayers.Feature.Vector>} The feature that was dragged.
  63      * pixel - {<OpenLayers.Pixel>} The pixel location of the mouse.
  64      */
  65     onComplete: function(feature, pixel) {},
  66
  67     /**
  68      * Property: layer
  69      * {<OpenLayers.Layer.Vector>}
  70      */
  71     layer: null,
  72
  73     /**
  74      * Property: feature
  75      * {<OpenLayers.Feature.Vector>}
  76      */
  77     feature: null,
  78
  79     /**
  80      * Property: dragCallbacks
  81      * {Object} The functions that are sent to the drag handler for callback.
  82      */
  83     dragCallbacks: {},
  84
  85     /**
  86      * Property: featureCallbacks
  87      * {Object} The functions that are sent to the feature handler for callback.
  88      */
  89     featureCallbacks: {},
  90
  91     /**
  92      * Property: lastPixel
  93      * {<OpenLayers.Pixel>}
  94      */
  95     lastPixel: null,
  96
  97     /**
  98      * Constructor: OpenLayers.Control.DragFeature
  99      * Create a new control to drag features.
 100      *
 101      * Parameters:
 102      * layer - {<OpenLayers.Layer.Vector>} The layer containing features to be
 103      *     dragged.
 104      * options - {Object} Optional object whose properties will be set on the
 105      *     control.
 106      */
 107     initialize: function(layer, options) {
 108         OpenLayers.Control.prototype.initialize.apply(this, [options]);
 109         this.layer = layer;
 110         this.handlers = {
 111             drag: new OpenLayers.Handler.Drag(
 112                 this, OpenLayers.Util.extend({
 113                     down: this.downFeature,
 114                     move: this.moveFeature,
 115                     up: this.upFeature,
 116                     out: this.cancel,
 117                     done: this.doneDragging
 118                 }, this.dragCallbacks)
 119             ),
 120             feature: new OpenLayers.Handler.Feature(
 121                 this, this.layer, OpenLayers.Util.extend({
 122                     over: this.overFeature,
 123                     out: this.outFeature
 124                 }, this.featureCallbacks),
 125                 {geometryTypes: this.geometryTypes}
 126             )
 127         };
 128     },
 129
 130     /**
 131      * APIMethod: destroy
 132      * Take care of things that are not handled in superclass
 133      */
 134     destroy: function() {
 135         this.layer = null;
 136         OpenLayers.Control.prototype.destroy.apply(this, []);
 137     },
 138
 139     /**
 140      * APIMethod: activate
 141      * Activate the control and the feature handler.
 142      *
 143      * Returns:
 144      * {Boolean} Successfully activated the control and feature handler.
 145      */
 146     activate: function() {
 147         return (this.handlers.feature.activate() &&
 148                 OpenLayers.Control.prototype.activate.apply(this, arguments));
 149     },
 150
 151     /**
 152      * APIMethod: deactivate
 153      * Deactivate the control and all handlers.
 154      *
 155      * Returns:
 156      * {Boolean} Successfully deactivated the control.
 157      */
 158     deactivate: function() {
 159         // the return from the handlers is unimportant in this case
 160         this.handlers.drag.deactivate();
 161         this.handlers.feature.deactivate();
 162         this.feature = null;
 163         this.dragging = false;
 164         this.lastPixel = null;
 165         OpenLayers.Element.removeClass(
 166             this.map.viewPortDiv, this.displayClass + "Over"
 167         );
 168         return OpenLayers.Control.prototype.deactivate.apply(this, arguments);
 169     },
 170
 171     /**
 172      * Method: overFeature
 173      * Called when the feature handler detects a mouse-over on a feature.
 174      *     This activates the drag handler.
 175      *
 176      * Parameters:
 177      * feature - {<OpenLayers.Feature.Vector>} The selected feature.
 178      */
 179     overFeature: function(feature) {
 180         if(!this.handlers.drag.dragging) {
 181             this.feature = feature;
 182             this.handlers.drag.activate();
 183             this.over = true;
 184             OpenLayers.Element.addClass(this.map.viewPortDiv, this.displayClass + "Over");
 185         } else {
 186             if(this.feature.id == feature.id) {
 187                 this.over = true;
 188             } else {
 189                 this.over = false;
 190             }
 191         }
 192     },
 193
 194     /**
 195      * Method: downFeature
 196      * Called when the drag handler detects a mouse-down.
 197      *
 198      * Parameters:
 199      * pixel - {<OpenLayers.Pixel>} Location of the mouse event.
 200      */
 201     downFeature: function(pixel) {
 202         this.lastPixel = pixel;
 203         this.onStart(this.feature, pixel);
 204     },
 205
 206     /**
 207      * Method: moveFeature
 208      * Called when the drag handler detects a mouse-move.  Also calls the
 209      *     optional onDrag method.
 210      *
 211      * Parameters:
 212      * pixel - {<OpenLayers.Pixel>} Location of the mouse event.
 213      */
 214     moveFeature: function(pixel) {
 215         var res = this.map.getResolution();
 216         this.feature.geometry.move(res * (pixel.x - this.lastPixel.x),
 217                                    res * (this.lastPixel.y - pixel.y));
 218         this.layer.drawFeature(this.feature);
 219         this.lastPixel = pixel;
 220         this.onDrag(this.feature, pixel);
 221     },
 222
 223     /**
 224      * Method: upFeature
 225      * Called when the drag handler detects a mouse-up.
 226      *
 227      * Parameters:
 228      * pixel - {<OpenLayers.Pixel>} Location of the mouse event.
 229      */
 230     upFeature: function(pixel) {
 231         if(!this.over) {
 232             this.handlers.drag.deactivate();
 233         }
 234     },
 235
 236     /**
 237      * Method: doneDragging
 238      * Called when the drag handler is done dragging.
 239      *
 240      * Parameters:
 241      * pixel - {<OpenLayers.Pixel>} The last event pixel location.  If this event
 242      *     came from a mouseout, this may not be in the map viewport.
 243      */
 244     doneDragging: function(pixel) {
 245         this.onComplete(this.feature, pixel);
 246     },
 247
 248     /**
 249      * Method: outFeature
 250      * Called when the feature handler detects a mouse-out on a feature.
 251      *
 252      * Parameters:
 253      * feature - {<OpenLayers.Feature.Vector>} The feature that the mouse left.
 254      */
 255     outFeature: function(feature) {
 256         if(!this.handlers.drag.dragging) {
 257             this.over = false;
 258             this.handlers.drag.deactivate();
 259             OpenLayers.Element.removeClass(
 260                 this.map.viewPortDiv, this.displayClass + "Over"
 261             );
 262             this.feature = null;
 263         } else {
 264             if(this.feature.id == feature.id) {
 265                 this.over = false;
 266             }
 267         }
 268     },
 269
 270     /**
 271      * Method: cancel
 272      * Called when the drag handler detects a mouse-out (from the map viewport).
 273      */
 274     cancel: function() {
 275         this.handlers.drag.deactivate();
 276         this.over = false;
 277     },
 278
 279     /**
 280      * Method: setMap
 281      * Set the map property for the control and all handlers.
 282      *
 283      * Parameters:
 284      * map - {<OpenLayers.Map>} The control's map.
 285      */
 286     setMap: function(map) {
 287         this.handlers.drag.setMap(map);
 288         this.handlers.feature.setMap(map);
 289         OpenLayers.Control.prototype.setMap.apply(this, arguments);
 290     },
 291
 292     CLASS_NAME: "OpenLayers.Control.DragFeature"
 293 });