From 9b08e8206f1ea15c939d756849a0c9b46d42f485 Mon Sep 17 00:00:00 2001 From: "olau@iola.dk" Date: Fri, 21 Nov 2008 21:10:13 +0000 Subject: [PATCH] Added documentation and example for the crosshairs feature git-svn-id: https://flot.googlecode.com/svn/trunk@116 1e0a6537-2640-0410-bfb7-f154510ff394 --- API.txt | 46 +++++++++++++++++++++---- NEWS.txt | 13 ++++++- examples/tracking.html | 78 ++++++++++++++++++++++++++++++++++++++++++ jquery.flot.js | 35 ++++++++++++++----- 4 files changed, 157 insertions(+), 15 deletions(-) create mode 100644 examples/tracking.html diff --git a/API.txt b/API.txt index 2595bf2..bfea5ff 100644 --- 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) diff --git a/NEWS.txt b/NEWS.txt index d904f5f..3dcb203 100644 --- 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 diff --git a/examples/tracking.html b/examples/tracking.html new file mode 100644 index 0000000..0bbb09d --- /dev/null +++ b/examples/tracking.html @@ -0,0 +1,78 @@ + + + + + Flot Examples + + + + + + +

Flot Examples

+ +
+ +

You can add crosshairs that'll track the mouse position, either + on both axes or as here on only one.

+ +

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.

+ +

+ + + + + diff --git a/jquery.flot.js b/jquery.flot.js index 54a31cc..3bc3e1b 100644 --- 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(); }