openlayers/lib/OpenLayers/Handler/Keyboard.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  * @requires OpenLayers/Handler.js
   7  * @requires OpenLayers/Events.js
   8  */
   9
  10 /**
  11  * Class: OpenLayers.handler.Keyboard
  12  * A handler for keyboard events.  Create a new instance with the
  13  *     <OpenLayers.Handler.Keyboard> constructor.
  14  *
  15  * Inherits from:
  16  *  - <OpenLayers.Handler>
  17  */
  18 OpenLayers.Handler.Keyboard = OpenLayers.Class(OpenLayers.Handler, {
  19
  20     /* http://www.quirksmode.org/js/keys.html explains key x-browser
  21         key handling quirks in pretty nice detail */
  22
  23     /**
  24      * Constant: KEY_EVENTS
  25      * keydown, keypress, keyup
  26      */
  27     KEY_EVENTS: ["keydown", "keyup"],
  28
  29     /**
  30     * Property: eventListener
  31     * {Function}
  32     */
  33     eventListener: null,
  34
  35     /**
  36      * Constructor: OpenLayers.Handler.Keyboard
  37      * Returns a new keyboard handler.
  38      *
  39      * Parameters:
  40      * control - {<OpenLayers.Control>} The control that is making use of
  41      *     this handler.  If a handler is being used without a control, the
  42      *     handlers setMap method must be overridden to deal properly with
  43      *     the map.
  44      * callbacks - {Object} An object containing a single function to be
  45      *     called when the drag operation is finished. The callback should
  46      *     expect to recieve a single argument, the pixel location of the event.
  47      *     Callbacks for 'keydown', 'keypress', and 'keyup' are supported.
  48      * options - {Object} Optional object whose properties will be set on the
  49      *     handler.
  50      */
  51     initialize: function(control, callbacks, options) {
  52         OpenLayers.Handler.prototype.initialize.apply(this, arguments);
  53         // cache the bound event listener method so it can be unobserved later
  54         this.eventListener = OpenLayers.Function.bindAsEventListener(
  55             this.handleKeyEvent, this
  56         );
  57     },
  58
  59     /**
  60      * Method: destroy
  61      */
  62     destroy: function() {
  63         this.deactivate();
  64         this.eventListener = null;
  65         OpenLayers.Handler.prototype.destroy.apply(this, arguments);
  66     },
  67
  68     /**
  69      * Method: activate
  70      */
  71     activate: function() {
  72         if (OpenLayers.Handler.prototype.activate.apply(this, arguments)) {
  73             for (var i=0, len=this.KEY_EVENTS.length; i<len; i++) {
  74                 OpenLayers.Event.observe(
  75                     document, this.KEY_EVENTS[i], this.eventListener);
  76             }
  77             return true;
  78         } else {
  79             return false;
  80         }
  81     },
  82
  83     /**
  84      * Method: deactivate
  85      */
  86     deactivate: function() {
  87         var deactivated = false;
  88         if (OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) {
  89             for (var i=0, len=this.KEY_EVENTS.length; i<len; i++) {
  90                 OpenLayers.Event.stopObserving(
  91                     document, this.KEY_EVENTS[i], this.eventListener);
  92             }
  93             deactivated = true;
  94         }
  95         return deactivated;
  96     },
  97
  98     /**
  99      * Method: handleKeyEvent
 100      */
 101     handleKeyEvent: function (evt) {
 102         if (this.checkModifiers(evt)) {
 103             this.callback(evt.type, [evt]);
 104         }
 105     },
 106
 107     CLASS_NAME: "OpenLayers.Handler.Keyboard"
 108 });