From 21dddbcb1f7719c6e6e4ab01c89efe2a20e9e434 Mon Sep 17 00:00:00 2001
From: Ansis Brammanis <brammanis@gmail.com>
Date: Wed, 16 Mar 2016 16:25:57 -0700
Subject: [PATCH] update examples for new queryRenderedFeatures

---
 .../examples/3400-01-04-center-on-symbol.html |  26 ++---
 .../examples/3400-01-04-hover-styles.html     |  18 ++-
 .../3400-01-05-queryrenderedfeatures.html     |   8 +-
 .../3400-01-06-polygon-popup-on-click.html    |  33 ++----
 .../examples/3400-01-06-popup-on-click.html   |  36 +++---
 .../examples/3400-01-06-popup-on-hover.html   |  31 +++--
 .../3400-01-17-updating-choropleth.html       |  34 +++---
 ...1-19-using-box-queryrenderedfeatures.html} |  65 +++++------
 .../3400-01-20-timeline-animation.html        |  62 +++++-----
 docs/_posts/examples/3400-01-22-measure.html  | 110 ++++++++----------
 js/ui/map.js                                  |   2 +-
 11 files changed, 180 insertions(+), 245 deletions(-)
 rename docs/_posts/examples/{3400-01-19-using-featuresin.html => 3400-01-19-using-box-queryrenderedfeatures.html} (76%)

diff --git a/docs/_posts/examples/3400-01-04-center-on-symbol.html b/docs/_posts/examples/3400-01-04-center-on-symbol.html
index 04dc4dfa81c..c5021aa56da 100644
--- a/docs/_posts/examples/3400-01-04-center-on-symbol.html
+++ b/docs/_posts/examples/3400-01-04-center-on-symbol.html
@@ -2,7 +2,7 @@
 layout: example
 category: example
 title: Center the map on a clicked marker
-description: Using featuresAt and flyTo to center the map on a symbol
+description: Using queryRenderedFeatures and flyTo to center the map on a symbol
 ---
 <div id='map'></div>
 <script>
@@ -73,26 +73,22 @@
 });
 
 map.on('click', function (e) {
-    // Use featuresAt to get features within a given radius of the click event
+    // Use queryRenderedFeatures to get features at a click event's point
     // Use layer option to avoid getting results from other layers
-    map.featuresAt(e.point, {layer: 'symbols', radius: 10, includeGeometry: true}, function (err, features) {
-        if (err) throw err;
-        // if there are features within the given radius of the click event,
-        // fly to the location of the click event
-        if (features.length) {
-            // Get coordinates from the symbol and center the map on those coordinates
-            map.flyTo({center: features[0].geometry.coordinates});
-        }
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['symbols'] });
+    // if there are features within the given radius of the click event,
+    // fly to the location of the click event
+    if (features.length) {
+        // Get coordinates from the symbol and center the map on those coordinates
+        map.flyTo({center: features[0].geometry.coordinates});
+    }
 });
 
 
 // Use the same approach as above to indicate that the symbols are clickable
 // by changing the cursor style to 'pointer'.
 map.on('mousemove', function (e) {
-    map.featuresAt(e.point, {layer: 'symbols', radius: 10}, function (err, features) {
-        if (err) throw err;
-        map.getCanvas().style.cursor = features.length ? 'pointer' : '';
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['symbols'] });
+    map.getCanvas().style.cursor = features.length ? 'pointer' : '';
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-04-hover-styles.html b/docs/_posts/examples/3400-01-04-hover-styles.html
index 9812785c764..b7588a92c3d 100644
--- a/docs/_posts/examples/3400-01-04-hover-styles.html
+++ b/docs/_posts/examples/3400-01-04-hover-styles.html
@@ -2,7 +2,7 @@
 layout: example
 category: example
 title: Highlight features under the mouse pointer
-description: Using featuresAt and a filter to change hover styles
+description: Using queryRenderedFeatures and a filter to change hover styles
 ---
 <div id='map'></div>
 <script>
@@ -59,16 +59,12 @@
     // If a feature is found, then we'll update the filter in the route-hover
     // layer to only show that state, thus making a hover effect.
     map.on("mousemove", function(e) {
-        map.featuresAt(e.point, {
-            radius: 5,
-            layer: ["state-fills"]
-        }, function (err, features) {
-            if (!err && features.length) {
-                map.setFilter("route-hover", ["==", "name", features[0].properties.name]);
-            } else {
-                map.setFilter("route-hover", ["==", "name", ""]);
-            }
-        });
+        var features = map.queryRenderedFeatures(e.point, { layers: ["state-fills"] });
+        if (features.length) {
+            map.setFilter("route-hover", ["==", "name", features[0].properties.name]);
+        } else {
+            map.setFilter("route-hover", ["==", "name", ""]);
+        }
     });
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-05-queryrenderedfeatures.html b/docs/_posts/examples/3400-01-05-queryrenderedfeatures.html
index f7e14277cbc..41ca91e58fb 100644
--- a/docs/_posts/examples/3400-01-05-queryrenderedfeatures.html
+++ b/docs/_posts/examples/3400-01-05-queryrenderedfeatures.html
@@ -2,7 +2,7 @@
 layout: example
 category: example
 title: Get features under the mouse pointer
-description: Using the featuresAt API to show properties of hovered-over map elements.
+description: Using the queryRenderedFeatures API to show properties of hovered-over map elements.
 ---
 <style>
     #features {
@@ -34,10 +34,8 @@
     });
 
     map.on('mousemove', function (e) {
-        map.featuresAt(e.point, {radius: 5}, function (err, features) {
-            if (err) throw err;
-            document.getElementById('features').innerHTML = JSON.stringify(features, null, 2);
-        });
+        var features = map.queryRenderedFeatures(e.point);
+        document.getElementById('features').innerHTML = JSON.stringify(features, null, 2);
     });
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-06-polygon-popup-on-click.html b/docs/_posts/examples/3400-01-06-polygon-popup-on-click.html
index b0822daa89b..d2193ed74d6 100644
--- a/docs/_posts/examples/3400-01-06-polygon-popup-on-click.html
+++ b/docs/_posts/examples/3400-01-06-polygon-popup-on-click.html
@@ -43,38 +43,27 @@
     });
 });
 
-var popup = new mapboxgl.Popup();
 
 // When a click event occurs near a marker icon, open a popup at the location of
 // the feature, with description HTML from its properties.
 map.on('click', function (e) {
-    map.featuresAt(e.point, {
-        radius: 1,
-        includeGeometry: true,
-        layer: 'states-layer'
-    }, function (err, features) {
+    var features = map.queryRenderedFeatures(e.point, { layers: ['states-layer'] });
+    if (!features.length) {
+        return;
+    }
 
-        if (err || !features.length) {
-            popup.remove();
-            return;
-        }
-
-        var feature = features[0];
+    var feature = features[0];
 
-        popup.setLngLat(map.unproject(e.point))
-            .setHTML(feature.properties.name)
-            .addTo(map);
-    });
+    var popup = new mapboxgl.Popup()
+        .setLngLat(map.unproject(e.point))
+        .setHTML(feature.properties.name)
+        .addTo(map);
 });
 
 // Use the same approach as above to indicate that the symbols are clickable
 // by changing the cursor style to 'pointer'.
 map.on('mousemove', function (e) {
-    map.featuresAt(e.point, {
-        radius: 1,
-        layer: 'states-layer'
-    }, function (err, features) {
-        map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : '';
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['states-layer'] });
+    map.getCanvas().style.cursor = (features.length) ? 'pointer' : '';
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-06-popup-on-click.html b/docs/_posts/examples/3400-01-06-popup-on-click.html
index 8c6f4a90029..5d43dd93798 100644
--- a/docs/_posts/examples/3400-01-06-popup-on-click.html
+++ b/docs/_posts/examples/3400-01-06-popup-on-click.html
@@ -138,40 +138,30 @@
     });
 });
 
-var popup = new mapboxgl.Popup();
 
 // When a click event occurs near a marker icon, open a popup at the location of
 // the feature, with description HTML from its properties.
 map.on('click', function (e) {
-    map.featuresAt(e.point, {
-        radius: 7.5, // Half the marker size (15px).
-        includeGeometry: true,
-        layer: 'markers'
-    }, function (err, features) {
+    var features = map.queryRenderedFeatures(e.point, { layers: ['markers'] });
 
-        if (err || !features.length) {
-            popup.remove();
-            return;
-        }
+    if (!features.length) {
+        return;
+    }
 
-        var feature = features[0];
+    var feature = features[0];
 
-        // Populate the popup and set its coordinates
-        // based on the feature found.
-        popup.setLngLat(feature.geometry.coordinates)
-            .setHTML(feature.properties.description)
-            .addTo(map);
-    });
+    // Populate the popup and set its coordinates
+    // based on the feature found.
+    var popup = new mapboxgl.Popup()
+        .setLngLat(feature.geometry.coordinates)
+        .setHTML(feature.properties.description)
+        .addTo(map);
 });
 
 // Use the same approach as above to indicate that the symbols are clickable
 // by changing the cursor style to 'pointer'.
 map.on('mousemove', function (e) {
-    map.featuresAt(e.point, {
-        radius: 7.5, // Half the marker size (15px).
-        layer: 'markers'
-    }, function (err, features) {
-        map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : '';
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['markers'] });
+    map.getCanvas().style.cursor = (features.length) ? 'pointer' : '';
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-06-popup-on-hover.html b/docs/_posts/examples/3400-01-06-popup-on-hover.html
index 07880118a2b..bd45e721917 100644
--- a/docs/_posts/examples/3400-01-06-popup-on-hover.html
+++ b/docs/_posts/examples/3400-01-06-popup-on-hover.html
@@ -145,26 +145,21 @@
 });
 
 map.on('mousemove', function(e) {
-    map.featuresAt(e.point, {
-        radius: 7.5, // Half the marker size (15px).
-        includeGeometry: true,
-        layer: 'markers'
-    }, function(err, features) {
-        // Change the cursor style as a UI indicator.
-        map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : '';
+    var features = map.queryRenderedFeatures(e.point, { layers: ['markers'] });
+    // Change the cursor style as a UI indicator.
+    map.getCanvas().style.cursor = (features.length) ? 'pointer' : '';
 
-        if (err || !features.length) {
-            popup.remove();
-            return;
-        }
+    if (!features.length) {
+        popup.remove();
+        return;
+    }
 
-        var feature = features[0];
+    var feature = features[0];
 
-        // Populate the popup and set its coordinates
-        // based on the feature found.
-        popup.setLngLat(feature.geometry.coordinates)
-            .setHTML(feature.properties.description)
-            .addTo(map);
-    });
+    // Populate the popup and set its coordinates
+    // based on the feature found.
+    popup.setLngLat(feature.geometry.coordinates)
+        .setHTML(feature.properties.description)
+        .addTo(map);
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-17-updating-choropleth.html b/docs/_posts/examples/3400-01-17-updating-choropleth.html
index b0b0a3f8ea9..76f1c3373cf 100644
--- a/docs/_posts/examples/3400-01-17-updating-choropleth.html
+++ b/docs/_posts/examples/3400-01-17-updating-choropleth.html
@@ -180,28 +180,24 @@ <h4>Population</h4>
 });
 
 map.on('mousemove', function(e) {
-    map.featuresAt(e.point, {
-
+    var features = map.queryRenderedFeatures(e.point, {
         // Collect each layer id we created into an array.
-        layer: layers.map(function(layer, i) {
+        layers: layers.map(function(layer, i) {
             return 'layer-' + i;
         })
-    }, function(err, features) {
-        // Change the cursor style as a UI indicator.
-        map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : '';
-
-        if (err || !features.length) {
-            popup.remove();
-            return;
-        }
-
-        var details = features[0].properties;
-
-        // Initialize a popup and set its coordinates
-        // based on the feature found.
-        popup.setLngLat(e.lngLat)
-            .setHTML(details.name + ': ' + details[facet].toLocaleString())
-            .addTo(map);
     });
+    // Change the cursor style as a UI indicator.
+    map.getCanvas().style.cursor = (features.length) ? 'pointer' : '';
+
+    if (!features.length) {
+        popup.remove();
+        return;
+    }
+
+    // Initialize a popup and set its coordinates
+    // based on the feature found.
+    popup.setLngLat(e.lngLat)
+        .setHTML(details.name + ': ' + details[facet].toLocaleString())
+        .addTo(map);
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-19-using-featuresin.html b/docs/_posts/examples/3400-01-19-using-box-queryrenderedfeatures.html
similarity index 76%
rename from docs/_posts/examples/3400-01-19-using-featuresin.html
rename to docs/_posts/examples/3400-01-19-using-box-queryrenderedfeatures.html
index 6943e8ea099..2a88a2b907c 100644
--- a/docs/_posts/examples/3400-01-19-using-featuresin.html
+++ b/docs/_posts/examples/3400-01-19-using-box-queryrenderedfeatures.html
@@ -2,7 +2,7 @@
 layout: example
 category: example
 title: Highlight features within a bounding box
-description: 'Hold <kbd>Shift</kbd> &amp; drag the map to query features using <code>featuresIn</code>.'
+description: 'Hold <kbd>Shift</kbd> &amp; drag the map to query features using <code>queryRenderedFeatures</code>.'
 ---
 <style>
 .boxdraw {
@@ -157,50 +157,43 @@
             box = null;
         }
 
-        // If bbox exists. use this value as the argument for `featuresIn`
+        // If bbox exists. use this value as the argument for `queryRenderedFeatures`
         if (bbox) {
-            map.featuresIn(bbox, {
-                layer: 'counties'
-            }, function(err, features) {
-                if (err) console.warn(err);
-
-                if (features.length >= 1000) {
-                    return window.alert('Select a smaller number of features');
-                }
-
-                // Run through the selected features and set a filter
-                // to match features with unique FIPS codes to activate
-                // the `counties-highlighted` layer.
-                var filter = features.reduce(function(memo, feature) {
-                    memo.push(feature.properties.FIPS);
-                    return memo;
-                }, ['in', 'FIPS']);
-
-                map.setFilter("counties-highlighted", filter);
-            });
+            var features = map.queryRenderedFeatures(bbox, { layers: ['counties'] });
+
+            if (features.length >= 1000) {
+                return window.alert('Select a smaller number of features');
+            }
+
+            // Run through the selected features and set a filter
+            // to match features with unique FIPS codes to activate
+            // the `counties-highlighted` layer.
+            var filter = features.reduce(function(memo, feature) {
+                memo.push(feature.properties.FIPS);
+                return memo;
+            }, ['in', 'FIPS']);
+
+            map.setFilter("counties-highlighted", filter);
         }
 
         map.dragPan.enable();
     }
 
     map.on('mousemove', function(e) {
-        map.featuresAt(e.point, {
-            layer: 'counties-highlighted'
-        }, function(err, features) {
-            // Change the cursor style as a UI indicator.
-            map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : '';
-
-            if (err || !features.length) {
-                popup.remove();
-                return;
-            }
+        var features = map.queryRenderedFeatures(e.point, { layers: ['counties-highlighted'] });
+        // Change the cursor style as a UI indicator.
+        map.getCanvas().style.cursor = (features.length) ? 'pointer' : '';
+
+        if (!features.length) {
+            popup.remove();
+            return;
+        }
 
-            var feature = features[0];
+        var feature = features[0];
 
-            popup.setLngLat(e.lngLat)
-                .setText(feature.properties.COUNTY)
-                .addTo(map);
-        });
+        popup.setLngLat(e.lngLat)
+            .setText(feature.properties.COUNTY)
+            .addTo(map);
     });
 });
 </script>
diff --git a/docs/_posts/examples/3400-01-20-timeline-animation.html b/docs/_posts/examples/3400-01-20-timeline-animation.html
index 15c135faace..098d37937bc 100644
--- a/docs/_posts/examples/3400-01-20-timeline-animation.html
+++ b/docs/_posts/examples/3400-01-20-timeline-animation.html
@@ -68,6 +68,7 @@ <h2>Significant earthquakes in 2015</h2>
 });
 
 var popup = new mapboxgl.Popup({
+    closeOnClick: false,
     closeButton: false
 });
 
@@ -201,44 +202,35 @@ <h2>Significant earthquakes in 2015</h2>
         });
 
         map.on('mousemove', function(e) {
-            map.featuresAt(e.point, {
-                radius: 30,
-                layer: layerIDs
-            }, function(err, features) {
-                // Change the cursor style as a UI indicator.
-                map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : '';
-            });
+            var features = map.queryRenderedFeatures(e.point, { layers: layerIDs });
+            // Change the cursor style as a UI indicator.
+            map.getCanvas().style.cursor = (features.length) ? 'pointer' : '';
         });
 
         map.on('click', function(e) {
-            map.featuresAt(e.point, {
-                includeGeometry: true,
-                radius: 30,
-                layer: layerIDs
-            }, function(err, features) {
-                if (err || !features.length) {
-                    popup.remove();
-                    return;
-                }
-
-                var feature = features[0];
-
-                var link = document.createElement('a');
-                link.href = feature.properties.url;
-                link.target = '_blank';
-                link.textContent = feature.properties.place;
-
-                // Use wrapped coordinates to ensure longitude is within (180, -180)
-                var coords = feature.geometry.coordinates;
-                var ll = new mapboxgl.LngLat(coords[0], coords[1]);
-                var wrapped = ll.wrap();
-
-                // Center the map to its point.
-                map.flyTo({ center: wrapped });
-                popup.setLngLat(wrapped)
-                    .setHTML(link.outerHTML)
-                    .addTo(map);
-            });
+            var features = map.queryRenderedFeatures(e.point, { layers: layerIDs });
+            if (!features.length) {
+                popup.remove();
+                return;
+            }
+
+            var feature = features[0];
+
+            var link = document.createElement('a');
+            link.href = feature.properties.url;
+            link.target = '_blank';
+            link.textContent = feature.properties.place;
+
+            // Use wrapped coordinates to ensure longitude is within (180, -180)
+            var coords = feature.geometry.coordinates;
+            var ll = new mapboxgl.LngLat(coords[0], coords[1]);
+            var wrapped = ll.wrap();
+
+            // Center the map to its point.
+            map.flyTo({ center: wrapped });
+            popup.setLngLat(wrapped)
+                .setHTML(link.outerHTML)
+                .addTo(map);
         });
     });
 });
diff --git a/docs/_posts/examples/3400-01-22-measure.html b/docs/_posts/examples/3400-01-22-measure.html
index 86250cd1298..dfcf58c0d87 100644
--- a/docs/_posts/examples/3400-01-22-measure.html
+++ b/docs/_posts/examples/3400-01-22-measure.html
@@ -89,69 +89,59 @@
     });
 
     map.on('click', function(e) {
-        map.featuresAt(e.point, {
-            radius: 5,
-            includeGeometry: true,
-            layer: 'measure-points'
-        }, function (err, features) {
-            if (err) return;
-
-            // Remove the linestring from the group
-            // So we can redraw it based on the points collection
-            if (geojson.features.length > 1) geojson.features.pop();
-
-            // Clear the Distance container to populate it with a new value
-            distanceContainer.innerHTML = '';
-
-            // If a marker was clicked, remove it from the
-            if (features.length) {
-                var id = features[0].properties.id;
-                geojson.features = geojson.features.filter(function(point) {
-                    return point.properties.id !== id;
-                });
-            } else {
-                var point = {
-                    "type": "Feature",
-                    "geometry": {
-                        "type": "Point",
-                        "coordinates": [
-                            e.lngLat.lng,
-                            e.lngLat.lat
-                        ]
-                    },
-                    "properties": {
-                        "id": new Date().getTime()
-                    }
-                };
-
-                geojson.features.push(point);
-            }
-
-            if (geojson.features.length > 1) {
-                linestring.geometry.coordinates = geojson.features.map(function(point) {
-                    return point.geometry.coordinates;
-                });
-
-                geojson.features.push(linestring);
-
-                // Populate the distanceContainer with total distance
-                var value = document.createElement('pre');
-                value.textContent = 'Total distance: ' + turf.lineDistance(linestring).toLocaleString() + 'km';
-                distanceContainer.appendChild(value);
-            }
-
-            map.getSource('geojson').setData(geojson);
-        });
+        var features = map.queryRenderedFeatures(e.point, { layers: ['measure-points'] });
+
+        // Remove the linestring from the group
+        // So we can redraw it based on the points collection
+        if (geojson.features.length > 1) geojson.features.pop();
+
+        // Clear the Distance container to populate it with a new value
+        distanceContainer.innerHTML = '';
+
+        // If a marker was clicked, remove it from the
+        if (features.length) {
+            var id = features[0].properties.id;
+            geojson.features = geojson.features.filter(function(point) {
+                return point.properties.id !== id;
+            });
+        } else {
+            var point = {
+                "type": "Feature",
+                "geometry": {
+                    "type": "Point",
+                    "coordinates": [
+                        e.lngLat.lng,
+                        e.lngLat.lat
+                    ]
+                },
+                "properties": {
+                    "id": String(new Date().getTime())
+                }
+            };
+
+            geojson.features.push(point);
+        }
+
+        if (geojson.features.length > 1) {
+            linestring.geometry.coordinates = geojson.features.map(function(point) {
+                return point.geometry.coordinates;
+            });
+
+            geojson.features.push(linestring);
+
+            // Populate the distanceContainer with total distance
+            var value = document.createElement('pre');
+            value.textContent = 'Total distance: ' + turf.lineDistance(linestring).toLocaleString() + 'km';
+            distanceContainer.appendChild(value);
+        }
+
+        map.getSource('geojson').setData(geojson);
     });
 });
 
 map.on('mousemove', function (e) {
-    map.featuresAt(e.point, {
-        radius: 5,
-        layer: 'measure-points'
-    }, function (err, features) {
-        // UI indicator for clicking/hovering a point on the map
-        map.getCanvas().style.cursor = (!err && features.length) ? 'pointer' : 'crosshair';
-    });
+    var features = map.queryRenderedFeatures(e.point, { layers: ['measure-points'] });
+    // UI indicator for clicking/hovering a point on the map
+    map.getCanvas().style.cursor = (features.length) ? 'pointer' : 'crosshair';
 });
 </script>
diff --git a/js/ui/map.js b/js/ui/map.js
index 645529dbe05..c603a2a651f 100644
--- a/js/ui/map.js
+++ b/js/ui/map.js
@@ -372,7 +372,7 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
      * var features = map.queryRenderedFeatures([20, 35], { layers: ['my-layer-name'] });
      *
      * @example
-     * var features = map.queryRenderedFeaturesAsync([[10, 20], [30, 50]], { layers: ['my-layer-name'] });
+     * var features = map.queryRenderedFeatures([[10, 20], [30, 50]], { layers: ['my-layer-name'] });
      */
     queryRenderedFeatures: function(pointOrBox, params) {
         if (!(pointOrBox instanceof Point || Array.isArray(pointOrBox))) {