Landed dual axis/hover event/finding nearby datapoints patch

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

API.txt

@@ -57,6 +57,8 @@ The format of a single series object is as follows:
     lines: specific lines options,
     bars: specific bars options,
     points: specific points options,
+    xaxis: 1 or 2,
+    yaxis: 1 or 2,
     shadowSize: number
   }
 
@@ -81,6 +83,11 @@ The latter is mostly useful if you let the user add and remove series,
 in which case you can hard-code the color index to prevent the colors
 from jumping around between the series.
 
+The "xaxis" and "yaxis" options specify which axis to use, specify 2
+to get the secondary axis (x axis at top or y axis to the right).
+E.g., you can use this to make a dual axis plot by specifying
+{ yaxis: 2 } for one data series.
+
 The rest of the options are all documented below as they are the same
 as the default options passed in via the options parameter in the plot
 commmand. When you specify them for a specific data series, they will
@@ -148,7 +155,7 @@ that it will overwrite the contents of the container.
 Customizing the axes
 ====================
 
-  xaxis, yaxis: {
+  xaxis, yaxis, x2axis, y2axis: {
     mode: null or "time"
     min: null or number
     max: null or number
@@ -163,7 +170,7 @@ Customizing the axes
     tickDecimals: null or number
   }
 
-The two axes have the same kind of options. The "mode" option
+The axes have the same kind of options. The "mode" option
 determines how the data is interpreted, the default of null means as
 decimal numbers. Use "time" for time series data, see the next section.
 
@@ -447,11 +454,11 @@ Customizing the grid
     clickable: boolean
   }
 
-The grid is the thing with the two axes and a number of ticks. "color"
+The grid is the thing with the axes and a number of ticks. "color"
 is the color of the grid itself whereas "backgroundColor" specifies
 the background color inside the grid area. The default value of null
 means that the background is transparent. You should only need to set
-backgroundColor if want the grid area to be a different color from the
+backgroundColor if you want the grid area to be a different color from the
 page color. Otherwise you might as well just set the background color
 of the page with CSS.
 
@@ -488,18 +495,42 @@ An example function might look like this:
 
 If you set "clickable" to true, the plot will listen for click events
 on the plot area and fire a "plotclick" event on the placeholder with
-an object { x: number, y: number } as parameter when one occurs. The
-returned coordinates will be in the unit of the plot (not in pixels).
-You can use it like this:
+a position and a nearby data item object as parameters. The returned
+coordinates are in the unit of the axes (not in pixels).
+
+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.
+
+You can use "plotclick" and "plothover" events like this:
 
     $.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
 
-    $("#placeholder").bind("plotclick", function (e, pos) {
-        // the values are in pos.x and pos.y
+    $("#placeholder").bind("plotclick", function (event, pos, item) {
+        alert("You clicked at " + pos.x + ", " + pos.y);
+        // secondary axis coordinates if present are in pos.x2, pos.y2
     });
 
-Support for hover indications or for associating the clicks with any
-specific data is still forthcoming.
+The item object in this example is either null or a nearby object on the form:
+
+  item: {
+      datapoint: the point as you specified it in the data, e.g. [0, 2]
+      dataIndex: the index of the point in the data array
+      series: the series object
+      seriesIndex: the index of the series
+  }
+
+For instance, if you have specified the data like this 
+
+    $.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);
+
+and the mouse is near the point (7, 3), "datapoint" is the [7, 3] we
+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.
 
 
 Customizing the selection
@@ -515,12 +546,15 @@ You enable selection support by setting the mode to one of "x", "y" or
 similarly for "y" mode. For "xy", the selection becomes a rectangle
 where both ranges can be specified. "color" is color of the selection.
 
-When selection support is enabled, a "selected" event will be emitted
+When selection support is enabled, a "plotselected" event will be emitted
 on the DOM element you passed into the plot function. The event
-handler gets one extra parameter with the area selected, like this:
+handler gets one extra parameter with the ranges selected on the axes,
+like this:
 
-  placeholder.bind("selected", function(event, area) {
-    // area selected is area.x1 to area.x2 and area.y1 to area.y2
+  placeholder.bind("plotselected", function(event, ranges) {
+    alert("You selected " + ranges.xaxis.from + " to " + ranges.xaxis.to)
+    // similar for yaxis, secondary axes are in x2axis
+    // and y2axis if present
   });
 
 
@@ -534,18 +568,20 @@ members:
 
     Clear the selection rectangle.
 
-  - setSelection(area)
+  - setSelection(ranges)
 
-    Set the selection rectangle. The passed in area should have the
-    members x1 and x2 if the selection mode is "x" and y1 and y2 if
-    the selection mode is "y" and both x1, x2 and y1, y2 if the
-    selection mode is "xy", like this:
+    Set the selection rectangle. The passed in ranges is on the same
+    form as returned in the "plotselected" event. If the selection
+    mode is "x", you should put in either an xaxis (or x2axis) object,
+    if the mode is "y" you need to put in an yaxis (or y2axis) object
+    and both xaxis/x2axis and yaxis/y2axis if the selection mode is
+    "xy", like this:
 
-      setSelection({ x1: 0, x2: 10, y1: 40, y2: 60});
+      setSelection({ xaxis: { from: 0, to: 10 }, yaxis: { from: 40, to: 60 } });
 
-    setSelection will trigger the "selected" event when called so you
+    setSelection will trigger the "plotselected" event when called so you
     may have to do a bit of shortcircuiting to prevent an eternal loop
-    if you invoke the method inside the "selected" handler.
+    if you invoke setSelection inside a "plotselected" handler.
 
   - getCanvas()
 
@@ -580,7 +616,7 @@ members:
 
       var series = plot.getData();
       for (var i = 0; i < series.length; ++i)
-        alert([i].color);
+        alert(series[i].color);
 
   - setupGrid()
 

NEWS.txt

 Flot x.x
 --------
 
-API changes: timestamps in time mode are now displayed according to
+Backwards API change summary: Timestamps are now in UTC. Also
+"selected" event -> becomes "plotselected" with new data, the
+parameters for setSelection are now different (but backwards
+compatibility hooks are in place).
+
+Interactivity: added a new "plothover" event and this and the
+"plotclick" event now returns the closest data item (based on patch by
+/david).
+
+Timestamps in time mode are now displayed according to
 UTC instead of the time zone of the visitor. This affects the way the
 timestamps should be input; you'll probably have to offset the
 timestamps according to your local time zone. It also affects any
@@ -9,6 +18,14 @@ custom date handling code (which basically now should use the
 equivalent UTC date mehods, e.g. .setUTCMonth() instead of
 .setMonth().
 
+Support for dual axis has been added (based on patch by someone who's
+annoyed and /david). For each data series you can specify which axes
+it belongs to, and there are two more axes, x2axis and y2axis, to
+customize. This affects the "selected" event which has been renamed to
+"plotselected" and spews out { xaxis: { from: -10, to: 20 } ... } and
+setSelection in which the parameters are on a new form (backwards
+compatible hooks are in place so old code shouldn't break).
+
 Added support for specifying the size of tick labels (axis.labelWidth,
 axis.labelHeight). Useful for specifying a max label size to keep
 multiple plots aligned.
@@ -26,7 +43,8 @@ sets. Prevent the possibility of eternal looping in tick calculations.
 Fixed a bug when borderWidth is set to 0 (reported by
 Rob/sanchothefat). Fixed a bug with drawing bars extending below 0
 (reported by James Hewitt, convenient patch by Ryan Funduk). Fixed a
-bug with line widths of bars (reported by MikeM).
+bug with line widths of bars (reported by MikeM). Fixed a bug with
+'nw' and 'sw' legend positions.
 
 
 Flot 0.4

TODO

@@ -24,16 +24,13 @@ support for highlighting stuff
 
 legend
   - interactive auto-highlight of graph?
+  - ability to specify noRows instead of just noColumns
 
 labels
   - labels on bars, data points
-  - plan "all points" option
+  - plain "all points" option
   - interactive "label this point" command
 
-interactive hover over
-  - fire event with value for points
-  - fire event with graph id for lines
-
 error margin indicators
   - for scientific/statistical purposes
 

examples/index.html

@@ -15,13 +15,11 @@
 
     <ul>
       <li><a href="basic.html">Basic example</a></li>
-      <li><a href="graph-types.html">Different graph types</a></li>
-      <li><a href="setting-options.html">Setting various options</a></li>
-      <li><a href="real-data.html">Real data with a bit of interactivity</a></li>
-      <li><a href="selection.html">Selection support and zooming</a></li>
-      <li><a href="zooming.html">Zooming with overview</a></li>
-      <li><a href="time.html">Plotting time series</a></li>
-      <li><a href="visitors.html">Visitors per day with zooming and weekends</a></li>
+      <li><a href="graph-types.html">Different graph types</a> and <a href="setting-options.html">setting various options</a></li>
+      <li><a href="turning-series.html">Turning series on/off</a></li>
+      <li><a href="selection.html">Selection support and zooming</a> and <a href="zooming.html">zooming with overview</a></li>
+      <li><a href="time.html">Plotting time series</a> and <a href="visitors.html">visitors per day with zooming and weekends</a></li>
+      <li><a href="dual-axis.html">Dual axis support</a></li>
       <li><a href="interacting.html">Interacting with the data</a></li>
     </ul>
  </body>

examples/interacting.html

@@ -13,23 +13,47 @@
 
     <div id="placeholder" style="width:600px;height:300px"></div>
 
-    <p>Flot supports user interactions. It's currently still a bit
-    primitive, but you can enable the user to click on the plot and
-    get the corresponding x and y values back.</p>
+    <p>One of the goals of Flot is to support user interactions intelligently.
+    Try hovering over the graph above and clicking on the points (note that support for highlighting the points is still missing).</p>
 
-    <p>Try clicking on the plot above. <span id="result"></span></p>
+    <p id="clickdata"></p>
+
+    <p id="hoverdata" style="display:none">Mouse hovers at
+    (<span id="x"></span>, <span id="y"></span>).<br>
+    Nearby item: <span id="nearby"></span>.</p>
 
 <script id="source" language="javascript" type="text/javascript">
 $(function () {
-    var d = [];
-    for (var i = 0; i < 14; i += 0.5)
-        d.push([i, Math.sin(i)]);
+    var sin = [], cos = [];
+    for (var i = 0; i < 14; i += 0.5) {
+        sin.push([i, Math.sin(i)]);
+        cos.push([i, Math.cos(i)]);
+    }
+
+    $.plot($("#placeholder"),
+           [ { data: sin, label: "sin(x)"}, { data: cos, label: "cos(x)" } ],
+           { lines: { show: true },
+             points: { show: true },
+             grid: { hoverable: true, clickable: true } });
 
-    $.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
+    $("#placeholder").bind("plothover", function (event, pos, item) {
+        $("#x").text(pos.x.toFixed(2));
+        $("#y").text(pos.y.toFixed(2));
+        
+        var nearby = "none";
+        if (item)
+            nearby = "point " + item.dataIndex + " in " + item.series.label + " at (" + item.datapoint[0].toFixed(2) + ", " + item.datapoint[1].toFixed(2) + ")";
+        $("#nearby").text(nearby);
+        
+        $("#hoverdata").show();
+    });
 
-    $("#placeholder").bind("plotclick", function (e, pos) {
-        // the values are in pos.x and pos.y
-        $("#result").text('You clicked on (' + pos.x.toFixed(2) +  ', ' + pos.y.toFixed(2) + ')');
+    $("#placeholder").bind("plotclick", function (event, pos, item) {
+        if (item) {
+            var x = item.datapoint[0].toFixed(2);
+            var y = item.datapoint[1].toFixed(2);
+            $("#clickdata").text(item.series.label + " of " + x + " = " + y);
+        }
     });
 });
 </script>

examples/selection.html

@@ -31,7 +31,7 @@
 
     <p>Selections are really useful for zooming. Just replot the
        chart with min and max values for the axes set to the values
-       in the "selected" event triggered. Try enabling the checkbox
+       in the "plotselected" event triggered. Try enabling the checkbox
        below and select a region again.</p>
 
     <p><input id="zoom" type="checkbox">Zoom to selection.</input></p>
@@ -80,14 +80,14 @@ $(function () {
 
     var placeholder = $("#placeholder");
 
-    placeholder.bind("selected", function (event, area) {
-        $("#selection").text(area.x1.toFixed(1) + " to " + area.x2.toFixed(1));
+    placeholder.bind("plotselected", function (event, ranges) {
+        $("#selection").text(ranges.xaxis.from.toFixed(1) + " to " + ranges.xaxis.to.toFixed(1));
 
         var zoom = $("#zoom").attr("checked");
         if (zoom)
             plot = $.plot(placeholder, data,
                           $.extend(true, {}, options, {
-                              xaxis: { min: area.x1, max: area.x2 }
+                              xaxis: { min: ranges.xaxis.from, max: ranges.xaxis.to }
                           }));
     });
     

examples/visitors.html

@@ -67,25 +67,25 @@ $(function () {
     // now connect the two
     var internalSelection = false;
     
-    $("#placeholder").bind("selected", function (event, area) {
+    $("#placeholder").bind("plotselected", function (event, ranges) {
         // do the zooming
         plot = $.plot($("#placeholder"), [d],
                       $.extend(true, {}, options, {
-                          xaxis: { min: area.x1, max: area.x2 }
+                          xaxis: { min: ranges.xaxis.from, max: ranges.xaxis.to }
                       }));
         
         if (internalSelection)
             return; // prevent eternal loop
         internalSelection = true;
-        overview.setSelection(area);
+        overview.setSelection(ranges);
         internalSelection = false;
     });
     
-    $("#overview").bind("selected", function (event, area) {
+    $("#overview").bind("plotselected", function (event, ranges) {
         if (internalSelection)
             return;
         internalSelection = true;
-        plot.setSelection(area);
+        plot.setSelection(ranges);
         internalSelection = false;
     });
 });

examples/zooming.html

@@ -65,31 +65,31 @@ $(function () {
     // now connect the two
     var internalSelection = false;
     
-    $("#placeholder").bind("selected", function (event, area) {
+    $("#placeholder").bind("plotselected", function (event, ranges) {
         // clamp the zooming to prevent eternal zoom
-        if (area.x2 - area.x1 < 0.00001)
-            area.x2 = area.x1 + 0.00001;
-        if (area.y2 - area.y1 < 0.00001)
-            area.y2 = area.y1 + 0.00001;
+        if (ranges.xaxis.to - ranges.xaxis.from < 0.00001)
+            ranges.xaxis.to = ranges.xaxis.from + 0.00001;
+        if (ranges.yaxis.to - ranges.yaxis.from < 0.00001)
+            ranges.yaxis.to = ranges.yaxis.from + 0.00001;
         
         // do the zooming
-        plot = $.plot($("#placeholder"), getData(area.x1, area.x2),
+        plot = $.plot($("#placeholder"), getData(ranges.xaxis.from, ranges.xaxis.to),
                       $.extend(true, {}, options, {
-                          xaxis: { min: area.x1, max: area.x2 },
-                          yaxis: { min: area.y1, max: area.y2 }
+                          xaxis: { min: ranges.xaxis.from, max: ranges.xaxis.to },
+                          yaxis: { min: ranges.yaxis.from, max: ranges.yaxis.to }
                       }));
         
         if (internalSelection)
             return; // prevent eternal loop
         internalSelection = true;
-        overview.setSelection(area);
+        overview.setSelection(ranges);
         internalSelection = false;
     });
-    $("#overview").bind("selected", function (event, area) {
+    $("#overview").bind("plotselected", function (event, ranges) {
         if (internalSelection)
             return;
         internalSelection = true;
-        plot.setSelection(area);
+        plot.setSelection(ranges);
         internalSelection = false;
     });
 });