Added documentation and example for the crosshairs feature

git-svn-id: https://flot.googlecode.com/svn/trunk@116 1e0a6537-2640-0410-bfb7-f154510ff394
18 years ago · 9b08e8206f
parent 0b135a2633
commit 9b08e8206f
4 changed files with 157 additions and 15 deletions
--- a/API.txt
+++ b/API.txt
@ -334,7 +334,8 @@ pretend trick described above. But you can fix up the timestamps by
 adding the time zone offset, e.g. for UTC+0200 you would add 2 hours
 to the UTC timestamp you got. Then it'll look right on the plot. Most
 programming environments have some means of getting the timezone
-offset for a specific date.
+offset for a specific date (note that you need to get the offset for
+each individual timestamp to account for daylight savings).

 Once you've got the timestamps into the data and specified "time" as
 the axis mode, Flot will automatically generate relevant ticks and
@ -614,6 +615,25 @@ like this:
    // and y2axis if present
  });

+The "plotselected" event is only fired when the user has finished
+making the selection. A "plotselecting" event is fired during the
+process with the same parameters as the "plotselected" event, in case
+you want to know what's happening while it's happening,
+
+
+Customizing the crosshair
+=========================
+
+  crosshair: {
+    mode: null or "x" or "y" or "xy"
+    color: color
+  }
+
+You can enable crosshairs, thin lines, that follow the mouse by
+setting the mode to one of "x", "y" or "xy". The "x" mode enables a
+vertical crosshair that lets you trace the values on the x axis, "y"
+enables a horizontal crosshair and "xy" enables them both.
+

 Plot Methods
 ------------
@ -621,11 +641,6 @@ Plot Methods
 The Plot object returned from the plot function has some methods you
 can call:

-  - clearSelection()
-
-    Clear the selection rectangle.
-
-
  - setSelection(ranges, preventEvent)

    Set the selection rectangle. The passed in ranges is on the same
@ -640,7 +655,26 @@ can call:
    setSelection will trigger the "plotselected" event when called. If
    you don't want that to happen, e.g. if you're inside a
    "plotselected" handler, pass true as the second parameter.
+
    
+  - clearSelection()
+
+    Clear the selection rectangle.
+
+
+  - setCrosshair(pos)
+
+    Set the position of the crosshair. Note that this is cleared if
+    the user moves the mouse. "pos" should be on the form { x: xpos,
+    y: ypos } (or x2 and y2 if you're using the secondary axes), which
+    is coincidentally the same format as what you get from a "plothover"
+    event. If "pos" is null, the crosshair is cleared.
+
+
+  - clearCrosshair()
+
+    Clear the crosshair.
+

  - highlight(series, datapoint)

--- a/NEWS.txt
+++ b/NEWS.txt
@ -1,7 +1,7 @@
 Flot 0.x
 --------

-New features:
+Changes:

 - Added support for disabling interactivity for specific data series
  (request from Ronald Schouten and Steve Upton).
@ -13,6 +13,17 @@ New features:
  passed in so you can specify DOM elements or CSS expressions to make
  it easier to use Flot with libraries like Prototype or Mootools.

+- A new "plotselecting" event is now emitted while the user is making
+  selection.
+
+- Added a new crosshairs feature for tracing the mouse position on the
+  axes, enable with crosshair { mode: "x"} (see the new tracking
+  example for a use).
+  
+- The "plothover" event is now emitted immediately instead of at most
+  10 times per second, you'll have to put in a setTimeout yourself if
+  you're doing something really expensive on this event.
+
 Bug fixes:

 - Fixed two corner-case bugs when drawing filled curves (report and
--- a/examples/tracking.html
+++ b/examples/tracking.html
@ -0,0 +1,78 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <title>Flot Examples</title>
+    <link href="layout.css" rel="stylesheet" type="text/css"></link>
+    <!--[if IE]><script language="javascript" type="text/javascript" src="../excanvas.pack.js"></script><![endif]-->
+    <script language="javascript" type="text/javascript" src="../jquery.js"></script>
+    <script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
+ </head>
+    <body>
+    <h1>Flot Examples</h1>
+
+    <div id="placeholder" style="width:600px;height:300px"></div>
+
+    <p>You can add crosshairs that'll track the mouse position, either
+    on both axes or as here on only one.</p>
+
+    <p>If you combine it with listening on hover events, you can use
+    it to track the intersection on the curves by interpolating
+    the data points.</p>
+
+    <p id="hoverdata"></p>
+
+<script id="source" language="javascript" type="text/javascript">
+$(function () {
+    var sin = [], cos = [];
+    for (var i = 0; i < 14; i += 0.1) {
+        sin.push([i, Math.sin(i)]);
+        cos.push([i, Math.cos(i)]);
+    }
+
+    var plot = $.plot($("#placeholder"),
+           [ { data: sin, label: "sin(x)"}, { data: cos, label: "cos(x)" } ],
+           { lines: { show: true },
+             crosshair: { mode: "x" },
+             grid: { hoverable: true, autoHighlight: false },
+             yaxis: { min: -1.2, max: 1.2 }
+             });
+
+    var legends = $("#placeholder .legendLabel");
+    legends.each(function () {
+        // fix the widths so they don't jump around
+        $(this).css('width', $(this).width() + 30);
+    });
+    
+    $("#placeholder").bind("plothover", function (event, pos, item) {
+        var axes = plot.getAxes();
+        if (pos.x < axes.xaxis.min || pos.x > axes.xaxis.max ||
+            pos.y < axes.yaxis.min || pos.y > axes.yaxis.max)
+            return;
+
+        var i, j, dataset = plot.getData();
+        for (i = 0; i < dataset.length; ++i) {
+            var series = dataset[i];
+
+            // find the nearest points, x-wise
+            for (j = 0; j < series.data.length; ++j)
+                if (series.data[j][0] > pos.x)
+                    break;
+            
+            // now interpolate
+            var y, p1 = series.data[j - 1], p2 = series.data[j];
+            if (p1 == null)
+                y = p2[1];
+            else if (p2 == null)
+                y = p1[1];
+            else
+                y = p1[1] + (p2[1] - p1[1]) * (pos.x - p1[0]) / (p2[0] - p1[0]);
+            
+            legends.eq(i).text(series.label + " = " + y.toFixed(2));
+        }
+    });
+});
+</script>
+
+ </body>
+</html>
--- a/jquery.flot.js
+++ b/jquery.flot.js
@ -364,7 +364,8 @@
            eventHolder = $([overlay, canvas]);

            // bind events
-            if (options.selection.mode != null || options.grid.hoverable) {
+            if (options.selection.mode != null || options.crosshair.mode != null
+                || options.grid.hoverable) {
                // FIXME: temp. work-around until jQuery bug 1871 is fixed
                eventHolder.each(function () {
                    this.onmousemove = onMouseMove;
@ -1679,15 +1680,15 @@
                                       function (s) { return s["hoverable"] != false; });

            if (options.crosshair.mode != null) {
-                setPositionFromEvent(crosshair.pos, e);
+                setPositionFromEvent(crosshair.pos, lastMousePos);
                triggerRedrawOverlay();
            }

            if (selection.active) {
                target.trigger("plotselecting", [ selectionIsSane() ? getSelectionForEvent() : null ]);

-                updateSelection(lastMousePos);
                crosshair.pos.x = -1; // hide the crosshair while selecting
+                updateSelection(lastMousePos);
            }
        }
        
@ -1731,6 +1732,18 @@
            triggerClickHoverEvent("plotclick", e,
                                   function (s) { return s["clickable"] != false; });
        }
+
+        /*
+        function userPositionInCanvasSpace(pos) {
+            return { x: parseInt(pos.x != null ? axes.xaxis.p2c(pos.x) : axes.x2axis.p2c(pos.x2)),
+                     y: parseInt(pos.y != null ? axes.yaxis.p2c(pos.y) : axes.y2axis.p2c(pos.y2)) };
+        }
+        
+        function positionInDivSpace(pos) {
+            var cpos = userPositionInCanvasSpace(pos);
+            return { x: cpos.x + plotOffset.left,
+                     y: cpos.y + plotOffset.top };
+        }*/
        
        // trigger click or hover event (they send the same parameters
        // so we share their code)
@ -1755,8 +1768,6 @@
                // fill in mouse pos for any listeners out there
                item.pageX = parseInt(item.series.xaxis.p2c(item.datapoint[0]) + offset.left + plotOffset.left);
                item.pageY = parseInt(item.series.yaxis.p2c(item.datapoint[1]) + offset.top + plotOffset.top);
-
-                    
            }

            if (options.grid.autoHighlight) {
@ -1819,10 +1830,18 @@
                octx.strokeStyle = parseColor(options.crosshair.color).scale(null, null, null, 0.8).toString();
                octx.lineWidth = 1;
                ctx.lineJoin = "round";
-                var pos = crosshair.pos;
+                var pos = crosshair.pos,
+                    extend = options.crosshair.extendBeyondGrid;
+
                octx.beginPath();
-                octx.moveTo(pos.x, options.crosshair.extendBeyondGrid ? -plotOffset.top : 0);
-                octx.lineTo(pos.x, options.crosshair.extendBeyondGrid ? canvasHeight - plotOffset.top : plotHeight);
+                if (options.crosshair.mode.indexOf("x") != -1) {
+                    octx.moveTo(pos.x, extend ? -plotOffset.top : 0);
+                    octx.lineTo(pos.x, extend ? canvasHeight - plotOffset.top : plotHeight);
+                }
+                if (options.crosshair.mode.indexOf("y") != -1) {
+                    octx.moveTo(extend ? -plotOffset.left : 0, pos.y);
+                    octx.lineTo(extend ? canvasWidth - plotOffset.left : plotWidth, pos.y);
+                }
                octx.stroke();
                
            }