From bad53abc5a7157072157e746a7887ec36abd0db8 Mon Sep 17 00:00:00 2001 From: "olau@iola.dk" Date: Thu, 15 Apr 2010 17:13:55 +0000 Subject: [PATCH] Revamped internals to add support for extra axes, not just dual (sponsored by Flight Data Services) git-svn-id: https://flot.googlecode.com/svn/trunk@251 1e0a6537-2640-0410-bfb7-f154510ff394 --- API.txt | 132 ++- NEWS.txt | 28 +- examples/index.html | 2 +- .../{dual-axis.html => multiple-axes.html} | 36 +- jquery.flot.crosshair.js | 18 +- jquery.flot.js | 907 ++++++++++++------ jquery.flot.navigate.js | 107 +-- jquery.flot.selection.js | 113 ++- 8 files changed, 877 insertions(+), 466 deletions(-) rename examples/{dual-axis.html => multiple-axes.html} (96%) diff --git a/API.txt b/API.txt index bc64035..1cf2c46 100644 --- a/API.txt +++ b/API.txt @@ -15,8 +15,8 @@ you apply to the div, e.g. background images have been reported to be a problem on IE 7. The format of the data is documented below, as is the available -options. The "plot" object returned has some methods you can call. -These are documented separately below. +options. The plot object returned from the call has some methods you +can call. These are documented separately below. Note that in general Flot gives no guarantees if you change any of the objects you pass in to the plot function or get out of it since @@ -65,8 +65,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 + xaxis: number + yaxis: number clickable: boolean hoverable: boolean shadowSize: number @@ -93,10 +93,9 @@ 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 "xaxis" and "yaxis" options specify which axis to use. The axes +are numbered from 1 (default), so { yaxis: 2} means that the series +should be plotted against the second y axis. "clickable" and "hoverable" can be set to false to disable interactivity for specific series if interactivity is turned on in @@ -172,15 +171,13 @@ ignored. Note that Flot will overwrite the contents of the container. Customizing the axes ==================== - xaxis, yaxis, x2axis, y2axis: { + xaxis, yaxis: { + position: "bottom" or "top" or "left" or "right" mode: null or "time" min: null or number max: null or number autoscaleMargin: null or number - labelWidth: null or number - labelHeight: null or number - transform: null or fn: number -> number inverseTransform: null or fn: number -> number @@ -189,11 +186,22 @@ Customizing the axes minTickSize: number or array tickFormatter: (fn: number, object -> string) or string tickDecimals: null or number + + labelWidth: null or number + labelHeight: null or number + + tickLength: null or number } -All 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. +All axes have the same kind of options. The following describes how to +configure one axis, see below for what to do if you've got more than +one x axis or y axis. + +The "position" option specifies where the axis is placed, bottom or +top for x axes, left or right for y axes. 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 time series data +section. The options "min"/"max" are the precise minimum/maximum value on the scale. If you don't specify either of them, a value will automatically @@ -207,10 +215,6 @@ 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 a fixed size of the tick -labels in pixels. They're useful in case you need to align several -plots. - "transform" and "inverseTransform" are callbacks you can put in to change the way the data is drawn. You can design a function to compress or expand certain parts of the axis non-linearly, e.g. @@ -225,7 +229,7 @@ into a natural logarithm axis with the following code: } Note that for finding extrema, Flot assumes that the transform -function does not reorder values (monotonicity is assumed). +function does not reorder values (it should be monotone). The inverseTransform is simply the inverse of the transform function (so v == inverseTransform(transform(v)) for all relevant v). It is @@ -282,11 +286,10 @@ axis for trigonometric functions: return res; } - You can control how the ticks look like with "tickDecimals", the number of decimals to display (default is auto-detected). -Alternatively, for ultimate control over how ticks look like you can +Alternatively, for ultimate control over how ticks are formatted you can provide a function to "tickFormatter". The function is passed two parameters, the tick value and an "axis" object with information, and should return a string. The default formatter looks like this: @@ -310,6 +313,49 @@ an example of a custom formatter: return val.toFixed(axis.tickDecimals) + " B"; } +"labelWidth" and "labelHeight" specifies a fixed size of the tick +labels in pixels. They're useful in case you need to align several +plots. + +"tickLength" is the length of the tick lines in pixels. By default, the +innermost axes will have ticks that extend all across the plot, while +any extra axes use small ticks. A value of null means use the default, +while a number means small ticks of that length - set it to 0 to hide +the lines completely. + + +Multiple axes +============= + +If you need more than one x axis or y axis, you need to specify for +each data series which axis they are to use, as described under the +format of the data series, e.g. { data: [...], yaxis: 2 } specifies +that a series should be plotted against the second y axis. + +To actually configure that axis, you can't use the xaxis/yaxis options +directly - instead there are two arrays in the options: + + xaxes: [] + yaxes: [] + +Here's an example of configuring a single x axis and two y axes (we +can leave options of the first y axis empty as the defaults are fine): + + { + xaxes: [ { position: "top" } ], + yaxes: [ { }, { position: "right", min: 20 } ] + } + +The arrays get their default values from the xaxis/yaxis settings, so +say you want to have all y axes start at zero, you can simply specify +yaxis: { min: 0 } instead of adding a min parameter to all the axes. + +Generally, the various interfaces in Flot dealing with data points +either accept an xaxis/yaxis parameter to specify which axis number to +use (starting from 1), or lets you specify the coordinate directly as +x2/x3/... or x2axis/x3axis/... instead of "x" or "xaxis". + + Time series data ================ @@ -547,6 +593,7 @@ Customizing the grid backgroundColor: color/gradient or null tickColor: color labelMargin: number + axisMargin: number markings: array of markings or (fn: axes -> array of markings) borderWidth: number borderColor: color or null @@ -566,19 +613,21 @@ You can turn off the whole grid including tick labels by setting "show" to false. "aboveData" determines whether the grid is drawn above the data or below (below is default). -"tickColor" is the color of the ticks and "labelMargin" is the spacing -between tick labels and the grid. Note that you can style the tick -labels with CSS, e.g. to change the color. They have class "tickLabel". -"borderWidth" is the width of the border around the plot. Set it to 0 -to disable the border. You can also set "borderColor" if you want the -border to have a different color than the grid lines. +"tickColor" is the color of the ticks, "labelMargin" is the space in +pixels between tick labels and axis line, and "axisMargin" is the +space in pixels between axes when there are two next to each other. +Note that you can style the tick labels with CSS, e.g. to change the +color. They have class "tickLabel". "borderWidth" is the width of the +border around the plot. Set it to 0 to disable the border. You can +also set "borderColor" if you want the border to have a different +color than the grid lines. "markings" is used to draw simple lines and rectangular areas in the background of the plot. You can either specify an array of ranges on -the form { xaxis: { from, to }, yaxis: { from, to } } (secondary axis -coordinates with x2axis/y2axis) or with a function that returns such -an array given the axes for the plot in an object as the first -parameter. +the form { xaxis: { from, to }, yaxis: { from, to } } (with multiple +axes, you can specify coordinates for other axes instead, e.g. as +x2axis/x3axis/...) or with a function that returns such an array given +the axes for the plot in an object as the first parameter. You can set the color of markings by specifying "color" in the ranges object. Here's an example array: @@ -597,7 +646,7 @@ A line is drawn if from and to are the same, e.g. would draw a line parallel to the x axis at y = 1. You can control the line width with "lineWidth" in the range object. -An example function might look like this: +An example function that makes vertical stripes might look like this: markings: function (axes) { var markings = []; @@ -626,7 +675,7 @@ You can use "plotclick" and "plothover" events like this: $("#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, + // axis coordinates for other axes, if present, are in pos.x2, pos.x3, ... // if you need global screen coordinates, they are pos.pageX, pos.pageY if (item) { @@ -780,10 +829,10 @@ can call: - pointOffset({ x: xpos, y: ypos }) Returns the calculated offset of the data point at (x, y) in data - space within the placeholder div. If you are working with dual axes, you + space within the placeholder div. If you are working with multiple axes, you can specify the x and y axis references, e.g. - o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 2 }) + o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 }) // o.left and o.top now contains the offset within the div @@ -811,14 +860,21 @@ Flot to keep track of its state, so be careful. - getAxes() - Gets an object with the axes settings as { xaxis, yaxis, x2axis, - y2axis }. + Gets an object with the axes. The axes are returned as the + attributes of the object, so for instance getAxes().xaxis is the + x axis. Various things are stuffed inside an axis object, e.g. you could use getAxes().xaxis.ticks to find out what the ticks are for the xaxis. Two other useful attributes are p2c and c2p, functions for transforming from data point space to the canvas plot space and back. Both returns values that are offset with the plot offset. + Check the Flot source code for the complete set of attributes (or + output an axis with console.log() and inspect it). + + With multiple axes, the extra axes are returned as x2axis, x3axis, + etc., e.g. getAxes().y2axis is the second y axis. You can check + y2axis.used to see whether the axis is actually in use or not. - getPlaceholder() diff --git a/NEWS.txt b/NEWS.txt index 98ebd9d..07eb9fb 100644 --- a/NEWS.txt +++ b/NEWS.txt @@ -1,6 +1,30 @@ Flot x.x -------- +API changes: + +Multiple axes support. Code using dual axes should be changed from +using x2axis/y2axis in the options to using an array. For instance, + + { + xaxis: { ... }, x2axis: { ... }, + yaxis: { ... }, y2axis: { ... } + } + +becomes + + { + xaxes: [ { ... }, { ... } ], + yaxes: [ { ... }, { ... } ] + } + +Note that if you're just using one axis, continue to use the +xaxis/yaxis directly (it now sets the default settings for the +arrays). Plugins touching the axes must be ported to take the extra +axes into account, a couple of helper functions have been added for +that purpose, check the source. + + Changes: - Support for specifying a bottom for each point for line charts when @@ -15,9 +39,11 @@ Changes: - Stacking plugin can stack horizontal bar charts. - Navigate plugin now redraws the plot while panning instead of only after the fact (can be disabled by setting the pan.frameRate option - to null). Issue 235. + to null), raised by lastthemy (issue 235). - Date formatter now accepts %0m and %0d to get a zero-padded month or day (issue raised by Maximillian Dornseif). +- Revamped internals to support an unlimited number of axes, not just + dual (sponsored by Flight Data Services, www.flightdataservices.com). - New hooks: drawSeries Bug fixes: diff --git a/examples/index.html b/examples/index.html index e9074c3..b9d6cc8 100644 --- a/examples/index.html +++ b/examples/index.html @@ -33,7 +33,7 @@