Document highlight and related

git-svn-id: https://flot.googlecode.com/svn/trunk@80 1e0a6537-2640-0410-bfb7-f154510ff394

API.txt

@@ -452,6 +452,9 @@ Customizing the grid
     coloredAreasColor: color
     borderWidth: number
     clickable: boolean
+    hoverable: boolean
+    autoHighlight: boolean
+    mouseActiveRadius: number
   }
 
 The grid is the thing with the axes and a number of ticks. "color"
@@ -499,9 +502,12 @@ a position and a nearby data item object as parameters. The coordinates
 are available both in the unit of the axes (not in pixels) and in
 global screen coordinates.
 
-If you set "hoverable" to true, the plot will listen for mouse move
-events on the plot area and fire a "plothover" event with the same
-parameters as the "plotclick" event.
+Likewise, if you set "hoverable" to true, the plot will listen for
+mouse move events on the plot area and fire a "plothover" event with
+the same parameters as the "plotclick" event. If "autoHighlight" is
+true (the default), nearby data items are highlighted automatically.
+If needed, you can disable highlighting and control it yourself with
+the highlight/unhighlight plot methods described elsewhere.
 
 You can use "plotclick" and "plothover" events like this:
 
@@ -511,6 +517,11 @@ You can use "plotclick" and "plothover" events like this:
         alert("You clicked at " + pos.x + ", " + pos.y);
         // secondary axis coordinates if present are in pos.x2, pos.y2,
         // if you need global screen coordinates, they are pos.pageX, pos.pageY
+
+        if (item) {
+          highlight(item.series, item.datapoint);
+          alert("You clicked a point!");
+        }
     });
 
 The item object in this example is either null or a nearby object on the form:
@@ -532,8 +543,16 @@ specified, "dataIndex" will be 1, "series" is a normalized series
 object with among other things the "Foo" label in series.label and the
 color in series.color, and "seriesIndex" is 0.
 
-Note that the detection of nearby points is still limited to points,
-and support for highlighting the point or graph is still forthcoming.
+Note that the detection of nearby points is limited to points (bars
+aren't working) at the moment.
+
+If you use the above events to update some other information and want
+to clear out that info in case the mouse goes away, you'll probably
+also need to listen to "mouseout" events on the placeholder div.
+
+"mouseActiveRadius" specifies how far the mouse can be from an item
+and still activate it. If there are two or more points within this
+radius, Flot chooses the closest item.
 
 
 Customizing the selection
@@ -561,10 +580,10 @@ like this:
   });
 
 
-Plot Members
+Plot Methods
 ------------
 
-The Plot object returned from the plot function has some members you
+The Plot object returned from the plot function has some methods you
 can call:
 
   - clearSelection()
@@ -588,6 +607,19 @@ can call:
     if you invoke setSelection inside a "plotselected" handler.
 
 
+  - highlight(series, datapoint)
+
+    Highlight a specific datapoint in the data series. You can either
+    specify the actual objects, e.g. if you got them from a
+    "plotclick" event, or you can specify the indices, e.g.
+    highlight(1, 3) to highlight the fourth point in the second series.
+
+
+  - unhighlight(series, datapoint)
+
+    Remove the highlighting of the point, same parameters as highlight.
+
+
   - setData(data)
 
     You can use this to reset the data used. Note that axis scaling,
@@ -616,7 +648,7 @@ can call:
 
 
 There are also some members that let you peek inside the internal
-workings of Flot which in some case is useful. Note that if you change
+workings of Flot which in some cases is useful. Note that if you change
 something in the objects returned, you're changing the objects used by
 Flot to keep track of its state, so be careful.
 
@@ -649,8 +681,9 @@ Flot to keep track of its state, so be careful.
   - getPlotOffset()
 
     Gets the offset that the grid has within the canvas as an object
-    with the members "left", "right", "top", "bottom". I.e., if you draw a
-    circle on the canvas with the center placed at (left, top), its
-    center will be at the top-most, left corner of the grid.
+    with distances from the canvas edges as "left", "right", "top",
+    "bottom". I.e., if you draw a circle on the canvas with the center
+    placed at (left, top), its center will be at the top-most, left
+    corner of the grid.
 
 

jquery.flot.js

@@ -83,8 +83,8 @@
                 // interactive stuff
                 clickable: false,
                 hoverable: false,
-                mouseCatchingArea: 10, // FIXME
                 autoHighlight: true, // highlight in case mouse is near
+                mouseActiveRadius: 10, // how far the mouse can be away to activate an item
             },
             selection: {
                 mode: null, // one of null, "x", "y" or "xy"
@@ -164,9 +164,9 @@
             var i;
 
             // collect what we already got of colors
-            var neededColors = series.length;
-            var usedColors = [];
-            var assignedColors = [];
+            var neededColors = series.length,
+                usedColors = [],
+                assignedColors = [];
             for (i = 0; i < series.length; ++i) {
                 var sc = series[i].color;
                 if (sc != null) {
@@ -185,8 +185,7 @@
             }
 
             // produce colors as needed
-            var colors = [];
-            var variation = 0;
+            var colors = [], variation = 0;
             i = 0;
             while (colors.length < neededColors) {
                 var c;
@@ -661,9 +660,6 @@
                 generator = function (axis) {
                     var ticks = [];
 
-                    if (axis.min == null) // FIXME
-                        return ticks;
-
                     // spew out all possible ticks
                     var start = floorInBase(axis.min, axis.tickSize),
                         i = 0, v = Number.NaN, prev;
@@ -1491,7 +1487,7 @@
 
         // Returns the data item the mouse is over, or null if none is found
         function findNearbyItem(mouseX, mouseY) {
-            var maxDistance = options.grid.mouseCatchingArea;
+            var maxDistance = options.grid.mouseActiveRadius;
             var lowestDistance = maxDistance * maxDistance + 1,
                 item = null;
 
@@ -1675,6 +1671,9 @@
             if (typeof s == "number")
                 s = series[s];
 
+            if (typeof point == "number")
+                point = s.data[point];
+
             var i = indexOfHighlight(s, point);
             if (i == -1) {
                 highlights.push({ series: s, point: point, auto: auto });
@@ -1689,6 +1688,9 @@
             if (typeof s == "number")
                 s = series[s];
 
+            if (typeof point == "number")
+                point = s.data[point];
+
             var i = indexOfHighlight(s, point);
             if (i != -1) {
                 highlights.splice(i, 1);