openlayers/lib/OpenLayers/Handler/Hover.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the clear BSD license.
   2  * See http://svn.openlayers.org/trunk/openlayers/license.txt
   3  * for the full text of the license. */
   4
   5 /**
   6  * @requires OpenLayers/Handler.js
   7  */
   8
   9 /**
  10  * Class: OpenLayers.Handler.Hover
  11  * The hover handler is to be used to emulate mouseovers on objects
  12  *      on the map that aren't DOM elements. For example one can use
  13  *      this handler to send WMS/GetFeatureInfo requests as the user
  14  *      moves the mouve over the map.
  15  *
  16  * Inherits from:
  17  *  - <OpenLayers.Handler>
  18  */
  19 OpenLayers.Handler.Hover = OpenLayers.Class(OpenLayers.Handler, {
  20
  21     /**
  22      * APIProperty: delay
  23      * {Integer} - Number of milliseconds between mousemoves before
  24      *      the event is considered a hover. Default is 500.
  25      */
  26     delay: 500,
  27
  28     /**
  29      * APIProperty: pixelTolerance
  30      * {Integer} - Maximum number of pixels between mousemoves for
  31      *      an event to be considered a hover. Default is null.
  32      */
  33     pixelTolerance: null,
  34
  35     /**
  36      * APIProperty: stopMove
  37      * {Boolean} - Stop other listeners from being notified on mousemoves.
  38      *      Default is false.
  39      */
  40     stopMove: false,
  41
  42     /**
  43      * Property: px
  44      * {<OpenLayers.Pixel>} - The location of the last mousemove, expressed
  45      *      in pixels.
  46      */
  47     px: null,
  48
  49     /**
  50      * Property: timerId
  51      * {Number} - The id of the timer.
  52      */
  53     timerId: null,
  54
  55     /**
  56      * Constructor: OpenLayers.Handler.Hover
  57      * Construct a hover handler.
  58      *
  59      * Parameters:
  60      * control - {<OpenLayers.Control>} The control that initialized this
  61      *     handler.  The control is assumed to have a valid map property; that
  62      *     map is used in the handler's own setMap method.
  63      * callbacks - {Object} An object with keys corresponding to callbacks
  64      *     that will be called by the handler. The callbacks should
  65      *     expect to receive a single argument, the event. Callbacks for
  66      *     'move', the mouse is moving, and 'pause', the mouse is pausing,
  67      *     are supported.
  68      * options - {Object} An optional object whose properties will be set on
  69      *     the handler.
  70      */
  71     initialize: function(control, callbacks, options) {
  72         OpenLayers.Handler.prototype.initialize.apply(this, arguments);
  73     },
  74
  75     /**
  76      * Method: mousemove
  77      * Called when the mouse moves on the map.
  78      *
  79      * Parameters:
  80      * evt - {<OpenLayers.Event>}
  81      *
  82      * Returns:
  83      * {Boolean} Continue propagating this event.
  84      */
  85     mousemove: function(evt) {
  86         if(this.passesTolerance(evt.xy)) {
  87             this.clearTimer();
  88             this.callback('move', [evt]);
  89             this.px = evt.xy;
  90             // clone the evt so original properties can be accessed even
  91             // if the browser deletes them during the delay
  92             evt = OpenLayers.Util.extend({}, evt);
  93             this.timerId = window.setTimeout(
  94                 OpenLayers.Function.bind(this.delayedCall, this, evt),
  95                 this.delay
  96             );
  97         }
  98         return !this.stopMove;
  99     },
 100
 101     /**
 102      * Method: mouseout
 103      * Called when the mouse goes out of the map.
 104      *
 105      * Parameters:
 106      * evt - {<OpenLayers.Event>}
 107      *
 108      * Returns:
 109      * {Boolean} Continue propagating this event.
 110      */
 111     mouseout: function(evt) {
 112         if (OpenLayers.Util.mouseLeft(evt, this.map.div)) {
 113             this.clearTimer();
 114             this.callback('move', [evt]);
 115         }
 116         return true;
 117     },
 118
 119     /**
 120      * Method: passesTolerance
 121      * Determine whether the mouse move is within the optional pixel tolerance.
 122      *
 123      * Parameters:
 124      * px - {<OpenLayers.Pixel>}
 125      *
 126      * Returns:
 127      * {Boolean} The mouse move is within the pixel tolerance.
 128      */
 129     passesTolerance: function(px) {
 130         var passes = true;
 131         if(this.pixelTolerance && this.px) {
 132             var dpx = Math.sqrt(
 133                 Math.pow(this.px.x - px.x, 2) +
 134                 Math.pow(this.px.y - px.y, 2)
 135             );
 136             if(dpx < this.pixelTolerance) {
 137                 passes = false;
 138             }
 139         }
 140         return passes;
 141     },
 142
 143     /**
 144      * Method: clearTimer
 145      * Clear the timer and set <timerId> to null.
 146      */
 147     clearTimer: function() {
 148         if(this.timerId != null) {
 149             window.clearTimeout(this.timerId);
 150             this.timerId = null;
 151         }
 152     },
 153
 154     /**
 155      * Method: delayedCall
 156      * Triggers pause callback.
 157      *
 158      * Parameters:
 159      * evt - {<OpenLayers.Event>}
 160      */
 161     delayedCall: function(evt) {
 162         this.callback('pause', [evt]);
 163     },
 164
 165     /**
 166      * APIMethod: deactivate
 167      * Deactivate the handler.
 168      *
 169      * Returns:
 170      * {Boolean} The handler was successfully deactivated.
 171      */
 172     deactivate: function() {
 173         var deactivated = false;
 174         if(OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) {
 175             this.clearTimer();
 176             deactivated = true;
 177         }
 178         return deactivated;
 179     },
 180
 181     CLASS_NAME: "OpenLayers.Handler.Hover"
 182 });