Merge pull request #222 from camptocamp/access_keyboardcontrol

KeyboardDefaults control improvements

examples/accessible.html

@@ -31,13 +31,26 @@
                 font-size:1em;
                 text-decoration:underline;
             }
+            a.accesskey {
+                color: white;
+            }
+            a.accesskey:focus {
+                color: #436976;
+            }
+            a.zoom {
+                padding-right: 20px;
+            }
         </style>
         <script src="../lib/OpenLayers.js"></script>
         <script type="text/javascript">
             var map = null;
             function init(){
                 var options = {
-                    controls: [new OpenLayers.Control.KeyboardDefaults()]
+                    controls: [
+                        new OpenLayers.Control.KeyboardDefaults({
+                            observeElement: 'map'
+                        })
+                    ]
                 };
                 map = new OpenLayers.Map('map', options);
                 var wms = new OpenLayers.Layer.WMS(
@@ -57,31 +70,37 @@
             keyboard, pan, panning, zoom, zooming, accesskey
         </div>        
 
+        <a class="accesskey"
+           href=""
+           accesskey="1"
+           onclick="document.getElementById('map').focus(); return false;">
+           Go to map
+        </a>
+
         <p id="shortdesc">
-            Demonstrate how to use the KeyboardDefaults option parameter for layer types.
+            Demonstrate the KeyboardDefaults control and how to use links
+            with Access Keys to navigate the map with the keyboard.
         </p>
 
+        <a class="zoom"
+           href="javascript: void map.zoomIn();"
+           accesskey="i">
+            zoom <em>i</em>n</a>
+        <a class="zoom"
+           href="javascript: void map.zoomOut();"
+           accesskey="o">
+            zoom <em>o</em>ut</a>
+
         <table>
             <tbody>
                 <tr>
-                    <td>
+                    <td>&nbsp;</td>
-                        <a href="javascript: void map.zoomOut();"
-                           accesskey="o">
-                            zoom <em>o</em>ut
-                        </a>
-                    </td>
                     <td>
                         <a href="javascript: void map.pan(0, -map.getSize().h / 4);"
                            accesskey="n">
                             pan <em>n</em>orth
                         </a>
                     </td>
-                    <td>
-                        <a href="javascript: void map.zoomIn();"
-                           accesskey="i">
-                            zoom <em>i</em>n
-                        </a>
-                    </td>
                 </tr>
                 <tr>
                     <td>
@@ -90,7 +109,7 @@
                             pan <em>w</em>est
                         </a>
                     </td>
-                    <td id="map" class="smallmap"></td>
+                    <td id="map" class="smallmap" tabindex="0"></td>
                     <td>
                         <a href="javascript: void map.pan(map.getSize().w / 4, 0);"
                            accesskey="e">
@@ -113,9 +132,9 @@
 
         <div id="docs">
             <p>Navigate the map in one of three ways:</p>
-                <ul>
+                <ol>
-                    <li>Click on the named links to zoom and pan</li>
+                    <li>Use Access Key "1" (alt + 1) to focus the map element, and
-                    <li>Use following keys to pan and zoom:
+                        use following keys to pan and zoom:
                         <ul>
                             <li>+ (zoom in)</li>
                             <li>- (zoom out)</li>
@@ -124,8 +143,12 @@
                             <li>left-arrow (pan east)</li>
                             <li>right-arrow (pan west)</li>
                         </ul>
+                        See <a href=http://en.wikipedia.org/wiki/Access_key>wikipedia</a> for
+                        more detail about Access Keys.
                     </li>
-                    <li>If access keys work for links in your browser, use:
+                    <li>Navigate to pan and zoom links using the "tab" key, and
+                        press "enter" to pan and zoom</li>
+                    <li>If Access Keys work for links in your browser, use:
                         <ul>
                             <li>i (zoom in)</li>
                             <li>o (zoom out)</li>
@@ -135,7 +158,7 @@
                             <li>w (pan west)</li>
                         </ul>
                     </li>
-                </ul>
+                </ol>
             <p>
 
             This is an example of using alternate methods to control panning and zooming.  This approach uses map.pan() and map.zoom().  You'll note that to pan, additional math is necessary along with map.size() in order to set the distance to pan.

lib/OpenLayers/Control/KeyboardDefaults.js

@@ -34,6 +34,15 @@ OpenLayers.Control.KeyboardDefaults = OpenLayers.Class(OpenLayers.Control, {
      */
     slideFactor: 75,
 
+    /**
+     * APIProperty: observeElement
+     * {DOMelement|String} The DOM element to handle keys for. You
+     *     can use the map div here, to have the navigation keys
+     *     work when the map div has the focus. If undefined the
+     *     document is used.
+     */
+    observeElement: null,
+
     /**
      * Constructor: OpenLayers.Control.KeyboardDefaults
      */
@@ -43,8 +52,11 @@ OpenLayers.Control.KeyboardDefaults = OpenLayers.Class(OpenLayers.Control, {
      * Create handler.
      */
     draw: function() {
-        this.handler = new OpenLayers.Handler.Keyboard( this, { 
+        var observeElement = this.observeElement || document;
-                                "keydown": this.defaultKeyPress });
+        this.handler = new OpenLayers.Handler.Keyboard( this,
+                {"keydown": this.defaultKeyPress},
+                {observeElement: observeElement}
+        );
     },
     
     /**
@@ -62,7 +74,7 @@ OpenLayers.Control.KeyboardDefaults = OpenLayers.Class(OpenLayers.Control, {
      * evt - {Event} 
      */
     defaultKeyPress: function (evt) {
-        var size;
+        var size, handled = true;
         switch(evt.keyCode) {
             case OpenLayers.Event.KEY_LEFT:
                 this.map.pan(-this.slideFactor, 0);
@@ -106,7 +118,14 @@ OpenLayers.Control.KeyboardDefaults = OpenLayers.Class(OpenLayers.Control, {
             case 95:  // -/_ (some ASCII)
                 this.map.zoomOut();
                 break; 
-        } 
+            default:
+                handled = false;
+        }
+        if (handled) {
+            // prevent browser default not to move the page
+            // when moving the page with the keyboard
+            OpenLayers.Event.stop(evt);
+        }
     },
 
     CLASS_NAME: "OpenLayers.Control.KeyboardDefaults"

lib/OpenLayers/Handler/Keyboard.js

@@ -33,6 +33,13 @@ OpenLayers.Handler.Keyboard = OpenLayers.Class(OpenLayers.Handler, {
     */
     eventListener: null,
 
+    /**
+     * Property: observeElement
+     * {DOMElement|String} The DOM element on which we listen for
+     *     key events. Default to the document.
+     */
+    observeElement: null,
+
     /**
      * Constructor: OpenLayers.Handler.Keyboard
      * Returns a new keyboard handler.
@@ -71,9 +78,10 @@ OpenLayers.Handler.Keyboard = OpenLayers.Class(OpenLayers.Handler, {
      */
     activate: function() {
         if (OpenLayers.Handler.prototype.activate.apply(this, arguments)) {
+            this.observeElement = this.observeElement || document;
             for (var i=0, len=this.KEY_EVENTS.length; i<len; i++) {
                 OpenLayers.Event.observe(
-                    document, this.KEY_EVENTS[i], this.eventListener);
+                    this.observeElement, this.KEY_EVENTS[i], this.eventListener);
             }
             return true;
         } else {
@@ -89,7 +97,7 @@ OpenLayers.Handler.Keyboard = OpenLayers.Class(OpenLayers.Handler, {
         if (OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) {
             for (var i=0, len=this.KEY_EVENTS.length; i<len; i++) {
                 OpenLayers.Event.stopObserving(
-                    document, this.KEY_EVENTS[i], this.eventListener);
+                    this.observeElement, this.KEY_EVENTS[i], this.eventListener);
             }
             deactivated = true;
         }

tests/Handler/Keyboard.html

@@ -42,59 +42,103 @@
     }
 
     function test_Handler_Keyboard_activate(t) {
-        t.plan(8);
+        t.plan(15);
+
+        var log;
         var map = new OpenLayers.Map('map');
         var control = new OpenLayers.Control();
         map.addControl(control);
         var handler = new OpenLayers.Handler.Keyboard(control);
-        handler.active = true;
+
-        var activated = handler.activate();
+        // mock OpenLayers.Event.observe
-        t.ok(!activated,
-             "activate returns false if the handler was already active");
-        handler.active = false;
-        handler.dragging = true;
         var old = OpenLayers.Event.stopObserving;
-        var types = ["keydown", "keyup"];
         OpenLayers.Event.observe = function(obj, type, method) {
-            t.ok(obj == document,
+            log[type] = obj;
-                 "activate calls observing with correct object");
+            var validType = OpenLayers.Util.indexOf(["keydown", "keyup"], type) != -1;
-            var validType = (OpenLayers.Util.indexOf(types, type) != -1);
             t.ok(validType, "activate calls observe for " + type);
             t.ok(method == handler.eventListener,
                  "activate calls observing with correct method");
         };
+
+        handler.active = true;
+        var activated = handler.activate();
+        t.ok(!activated,
+             "activate returns false if the handler was already active");
+
+        log = {};
+        handler.active = false;
+        handler.observeElement = map.div;
         activated = handler.activate();
+        t.ok(log['keydown'] == map.div,
+             "activate calls observing for keydown with correct object");
+        t.ok(log['keyup'] == map.div,
+             "activate calls observing for keyup with correct object");
         t.ok(activated,
              "activate returns true if the handler was not already active");
+
+        log = {};
+        handler.active = false;
+        handler.observeElement = null;
+        activated = handler.activate();
+        t.ok(log['keydown'] == document,
+             "activate calls observing for keydown with correct object");
+        t.ok(log['keyup'] == document,
+             "activate calls observing for keyup with correct object");
+        t.ok(activated,
+             "activate returns true if the handler was not already active");
+
         OpenLayers.Event.observe = old;
-        
+        map.destroy();
     }
 
     function test_Handler_Keyboard_deactivate(t) {
-        t.plan(8);
+        t.plan(15);
+
+        var log;
         var map = new OpenLayers.Map('map');
         var control = new OpenLayers.Control();
         map.addControl(control);
         var handler = new OpenLayers.Handler.Keyboard(control);
-        handler.active = false;
+
-        var deactivated = handler.deactivate();
+        // mock OpenLayers.Event.stopObserving
-        t.ok(!deactivated,
-             "deactivate returns false if the handler was not already active");
-        handler.active = true;
         var old = OpenLayers.Event.stopObserving;
-        var types = ["keydown", "keyup"];
         OpenLayers.Event.stopObserving = function(obj, type, method) {
-            t.ok(obj == document,
+            log[type] = obj;
-                 "deactivate calls stopObserving with correct object");
+            var validType = OpenLayers.Util.indexOf(["keydown", "keyup"], type) != -1;
-            var validType = (OpenLayers.Util.indexOf(types, type) != -1);
             t.ok(validType, "deactivate calls stopObserving for " + type);
             t.ok(method == handler.eventListener,
                  "deactivate calls stopObserving with correct method");
         };
+
+        handler.active = false;
+        var deactivated = handler.deactivate();
+        t.ok(!deactivated,
+             "deactivate returns false if the handler was not already active");
+
+        log = {};
+        handler.active = true;
+        handler.observeElement = map.div;
         deactivated = handler.deactivate();
+        t.ok(log['keydown'] == map.div,
+             "deactivate calls stopObserving for keydown with correct object");
+        t.ok(log['keyup'] == map.div,
+             "deactivate calls stopObserving for keyup with correct object");
         t.ok(deactivated,
              "deactivate returns true if the handler was active already");
+
+        log = {};
+        handler.active = true;
+        handler.observeElement = document;
+        deactivated = handler.deactivate();
+        t.ok(log['keydown'] == document,
+             "deactivate calls stopObserving for keydown with correct object");
+        t.ok(log['keyup'] == document,
+             "deactivate calls stopObserving for keyup with correct object");
+        t.ok(deactivated,
+             "deactivate returns true if the handler was active already");
+
         OpenLayers.Event.stopObserving = old;
+        map.destroy();
     }