From d3acc16e463d40ac60bce06fdfa2452fc5eb8d1e Mon Sep 17 00:00:00 2001 From: "olau@iola.dk" Date: Tue, 2 Jun 2009 18:14:35 +0000 Subject: [PATCH] Removed work-around for slow jQuery mousemove events (closing issue 134), add new hooks and new API for interactive plugins, move crosshair support to plugin git-svn-id: https://flot.googlecode.com/svn/trunk@159 1e0a6537-2640-0410-bfb7-f154510ff394 --- API.txt | 110 ++++++++++++++++++++++--------- NEWS.txt | 8 +-- README.txt | 4 +- examples/tracking.html | 4 +- jquery.flot.crosshair.js | 117 +++++++++++++++++++++++++++++++++ jquery.flot.js | 137 ++++++++++++--------------------------- 6 files changed, 248 insertions(+), 132 deletions(-) create mode 100644 jquery.flot.crosshair.js diff --git a/API.txt b/API.txt index 16ba007..e857bf2 100644 --- a/API.txt +++ b/API.txt @@ -204,7 +204,7 @@ specified, the plot will furthermore extend the axis end-point to the nearest whole tick. The default value is "null" for the x axis and 0.02 for the y axis which seems appropriate for most cases. -"labelWidth" and "labelHeight" specifies the maximum size of the tick +"labelWidth" and "labelHeight" specifies a fixed size of the tick labels in pixels. They're useful in case you need to align several plots. @@ -662,20 +662,6 @@ A "plotunselected" event with no arguments is emitted when the user clicks the mouse to remove the selection. -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. - - Specifying gradients ==================== @@ -730,20 +716,12 @@ can call: Clear the selection rectangle. Pass in true to avoid getting a "plotunselected" event. + - getSelection() - - 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. - + Returns the current selection in the same format as the + "plotselected" event. If there's currently no selection, it + returns null. + - highlight(series, datapoint) @@ -787,7 +765,28 @@ can call: - draw() - Redraws the canvas. + Redraws the plot canvas. + + - triggerRedrawOverlay() + + Schedules an update of an overlay canvas used for drawing + interactive things like the selection and point highlights. This + is mostly useful for writing plugins. The redraw doesn't happen + immediately, instead a timer is set to catch multiple successive + redraws (e.g. from a mousemove). + + - width()/height() + + Gets the width and height of the plotting area inside the grid. + This is smaller than the canvas or placeholder dimensions as some + extra space is needed (e.g. for labels). + + - offset() + + Returns the offset of the plotting area inside the grid relative + to the document, useful for instance for calculating mouse + positions (event.pageX/Y minus this offset is the pixel position + inside the plot). There are also some members that let you peek inside the internal @@ -837,7 +836,7 @@ Flot to keep track of its state, so be careful. Gets the options for the plot, in a normalized format with default values filled in. - + Hooks ===== @@ -851,7 +850,7 @@ Here's an overview of the phases Flot goes through: 1. Plugin initialization, parsing options - 2. Constructing the canvas used for drawing + 2. Constructing the canvases used for drawing 3. Set data: parsing data specification, calculating colors, copying raw data points into internal format, @@ -871,7 +870,7 @@ sub-object on the Plot object with the names mentioned below, e.g. var plot = $.plot(...); - function f() { alert("hello!")}; + function f(plot, series, datapoints) { alert("hello!")}; plot.hooks.processDatapoints.push(f); @@ -885,6 +884,7 @@ Currently available hooks (when in doubt, check the Flot source): Called after Flot has parsed and merged options. Rarely useful, but does allow customizations beyond simple merging of default values. + - processRawData [phase 3] @@ -895,6 +895,7 @@ Currently available hooks (when in doubt, check the Flot source): points and sets datapoints.pointsize to the size of the points, Flot will skip the copying/normalization step for this series. + - processDatapoints [phase 3] function(plot, series, datapoints) @@ -914,7 +915,52 @@ Currently available hooks (when in doubt, check the Flot source): Note that you must leave datapoints in a good condition as Flot doesn't check it or do any normalization on it afterwards. + + - bindEvents [phase 6] + + function(plot, eventHolder) + + Called after Flot has setup its event handlers. Should set any + necessary event handlers on eventHolder, a jQuery object with the + canvas, e.g. + + function (plot, eventHolder) { + eventHolder.mousedown(function (e) { + alert("You pressed the mouse at " + e.pageX + " " + e.pageY); + }); + } + + Interesting events include click, mousemove, mouseup/down. You can + use all jQuery events. Usually, the event handlers will update the + state by drawing something (add a drawOverlay hook and call + triggerRedrawOverlay) or firing an externally visible event for + user code. See the crosshair plugin for an example. + + Currently, eventHolder actually contains both the static canvas + used for the plot itself and the overlay canvas used for + interactive features because some versions of IE get the stacking + order wrong. The hook only gets one event, though (either for the + overlay or for the static canvas). + + + - drawOverlay [phase 7] + + function (plot, canvascontext) + + The drawOverlay hook is used for interactive things that need a + canvas to draw on. The model currently used by Flot works the way + that an extra overlay canvas is positioned on top of the static + canvas. This overlay is cleared and then completely redrawn + whenever something interesting happens. This hook is called when + the overlay canvas is to be redrawn. + + "canvascontext" is the 2D context of the overlay canvas. You can + use this to draw things. You'll most likely need some of the + metrics computed by Flot, e.g. plot.width()/plot.height(). See the + crosshair plugin for an example. + + Plugins ------- diff --git a/NEWS.txt b/NEWS.txt index 1b91d10..44f6875 100644 --- a/NEWS.txt +++ b/NEWS.txt @@ -34,10 +34,6 @@ Changes: - A new "plotselecting" event is now emitted while the user is making a 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. @@ -95,6 +91,10 @@ Changes: them summed. This is useful for drawing additive/cumulative graphs with bars and (currently unfilled) lines. +- Crosshairs plugin: trace the mouse position on the axes, enable with + crosshair: { mode: "x"} (see the new tracking example for a use). + + Bug fixes: - Fixed two corner-case bugs when drawing filled curves (report and diff --git a/README.txt b/README.txt index 46c47f7..3f15f05 100644 --- a/README.txt +++ b/README.txt @@ -28,7 +28,9 @@ support for VML which excanvas is relying on. It appears that some stripped down versions used for test environments on virtual machines lack the VML support. -Also note that you need at least jQuery 1.2.6. +Also note that you need at least jQuery 1.2.6 (but at least 1.3.2 is +recommended for interactive charts because of performance improvements +in event handling). Basic usage diff --git a/examples/tracking.html b/examples/tracking.html index 76fd717..a0ad77d 100644 --- a/examples/tracking.html +++ b/examples/tracking.html @@ -7,6 +7,7 @@ +

Flot Examples

@@ -23,6 +24,7 @@