diff options
Diffstat (limited to 'API.txt')
| -rw-r--r-- | API.txt | 301 |
1 files changed, 239 insertions, 62 deletions
@@ -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 @@ -52,8 +52,9 @@ drawing. As a special case, a null value for lines is interpreted as a line segment end, i.e. the points before and after the null value are not connected. -Lines and points take two coordinates. For bars, you can specify a -third coordinate which is the bottom of the bar (defaults to 0). +Lines and points take two coordinates. For filled lines and bars, you +can specify a third coordinate which is the bottom of the filled +area/bar (defaults to 0). The format of a single series object is as follows: @@ -64,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 @@ -92,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 @@ -171,15 +171,18 @@ ignored. Note that Flot will overwrite the contents of the container. Customizing the axes ==================== - xaxis, yaxis, x2axis, y2axis: { + xaxis, yaxis: { + show: null or true/false + position: "bottom" or "top" or "left" or "right" mode: null or "time" + + color: null or color spec + tickColor: null or color spec + 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 @@ -188,27 +191,51 @@ 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 + reserveSpace: null or true + + tickLength: null or number + + alignTicksWithAxis: 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. + +If you don't set the "show" option (i.e. it is null), visibility is +auto-detected, i.e. the axis will show up if there's data associated +with it. You can override this by setting the "show" option to true or +false. + +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 "color" option determines the color of the labels and ticks for +the axis (default is the grid color). For more fine-grained control +you can also set the color of the ticks separately with "tickColor" +(otherwise it's autogenerated as the base color with some +transparency). 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 -be chosen based on the minimum/maximum data values. +be chosen based on the minimum/maximum data values. Note that Flot +always examines all the data values you feed to it, even if a +restriction on another axis may make some of them invisible (this +makes interactive use more stable). The "autoscaleMargin" is a bit esoteric: it's the fraction of margin that the scaling algorithm will add to avoid that the outermost points -ends up on the grid border. Note that this margin is only applied -when a min or max value is not explicitly set. If a margin is -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. +ends up on the grid border. Note that this margin is only applied when +a min or max value is not explicitly set. If a margin is specified, +the plot will furthermore extend the axis end-point to the nearest +whole tick. The default value is "null" for the x axes and 0.02 for y +axes which seems appropriate for most cases. "transform" and "inverseTransform" are callbacks you can put in to change the way the data is drawn. You can design a function to @@ -223,8 +250,16 @@ into a natural logarithm axis with the following code: inverseTransform: function (v) { return Math.exp(v); } } +Similarly, for reversing the y axis so the values appear in inverse +order: + + yaxis: { + transform: function (v) { return -v; }, + inverseTransform: function (v) { return -v; } + } + 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 @@ -281,13 +316,12 @@ 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 +parameters, the tick value and an axis object with information, and should return a string. The default formatter looks like this: function formatter(val, axis) { @@ -309,6 +343,59 @@ 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. "reserveSpace" means that even if an axis isn't shown, Flot +should reserve space for it - it is useful in combination with +labelWidth and labelHeight for aligning multi-axis charts. + +"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. + +If you set "alignTicksWithAxis" to the number of another axis, e.g. +alignTicksWithAxis: 1, Flot will ensure that the autogenerated ticks +of this axis are aligned with the ticks of the other axis. This may +improve the looks, e.g. if you have one y axis to the left and one to +the right, because the grid lines will then match the ticks in both +ends. The trade-off is that the forced ticks won't necessarily be at +natural places. + + +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 ================ @@ -396,13 +483,17 @@ specifiers are supported %H: hours (left-padded with a zero) %M: minutes (left-padded with a zero) %S: seconds (left-padded with a zero) - %d: day of month (1-31) - %m: month (1-12) + %d: day of month (1-31), use %0d for zero-padding + %m: month (1-12), use %0m for zero-padding %y: year (four digits) %b: month name (customizable) %p: am/pm, additionally switches %h/%H to 12 hour instead of 24 %P: AM/PM (uppercase version of %p) +Inserting a zero like %0m or %0d means that the specifier will be +left-padded with a zero if it's only single-digit. So %y-%0m-%0d +results in unambigious ISO timestamps like 2007-05-10 (for May 10th). + You can customize the month names with the "monthNames" option. For instance, for Danish you might specify: @@ -453,6 +544,7 @@ Customizing the data series points: { radius: number + symbol: "circle" or function } bars: { @@ -479,7 +571,7 @@ The most important options are "lines", "points" and "bars" that specify whether and how lines, points and bars should be shown for each data series. In case you don't specify anything at all, Flot will default to showing lines (you can turn this off with -lines: { show: false}). You can specify the various types +lines: { show: false }). You can specify the various types independently of each other, and Flot will happily draw each of them in turn (this is probably only useful for lines and points), e.g. @@ -519,6 +611,26 @@ connected with a straight (possibly diagonal) line or with first a horizontal and then a vertical line. Note that this transforms the data by adding extra points. +For points, you can specify the radius and the symbol. The only +built-in symbol type is circles, for other types you can use a plugin +or define them yourself by specifying a callback: + + function cross(ctx, x, y, radius, shadow) { + var size = radius * Math.sqrt(Math.PI) / 2; + ctx.moveTo(x - size, y - size); + ctx.lineTo(x + size, y + size); + ctx.moveTo(x - size, y + size); + ctx.lineTo(x + size, y - size); + } + +The parameters are the drawing context, x and y coordinates of the +center of the point, a radius which corresponds to what the circle +would have used and whether the call is to draw a shadow (due to +limited canvas support, shadows are currently faked through extra +draws). It's good practice to ensure that the area covered by the +symbol is the same as for the circle with the given radius, this +ensures that all symbols have approximately the same visual weight. + "shadowSize" is the default size of shadows in pixels. Set it to 0 to remove shadows. @@ -540,40 +652,48 @@ Customizing the grid aboveData: boolean color: color 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 + minBorderMargin: number or null clickable: boolean hoverable: boolean autoHighlight: boolean mouseActiveRadius: number } -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 +The grid is the thing with the axes and a number of ticks. Many of the +things in the grid are configured under the individual axes, but not +all. "color" is the color of the grid itself whereas "backgroundColor" +specifies the background color inside the grid area, here null means that the background is transparent. You can also set a gradient, see the gradient documentation below. You can turn off the whole grid including tick labels by setting -"show" to false. "aboveData" determines whether the grid is drawn on +"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". +"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. +"minBorderMargin" controls the default minimum margin around the +border - it's used to make sure that points aren't accidentally +clipped by the canvas edge so by default the value is computed from +the point radius. "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: @@ -592,7 +712,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 = []; @@ -621,7 +741,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) { @@ -757,7 +877,8 @@ can call: interactive things like a 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). + redraws (e.g. from a mousemove). You can get to the overlay by + setting up a drawOverlay hook. - width()/height() @@ -775,12 +896,24 @@ 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 - + + - resize() + + Tells Flot to resize the drawing canvas to the size of the + placeholder. You need to run setupGrid() and draw() afterwards as + canvas resizing is a destructive operation. This is used + internally by the resize plugin. + + - shutdown() + + Cleans up any event handlers Flot has currently registered. This + is used internally. + There are also some members that let you peek inside the internal workings of Flot which is useful in some cases. Note that if you change @@ -806,14 +939,22 @@ 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 associated with any data + points and y2axis.show to see if it is currently shown. - getPlaceholder() @@ -835,8 +976,11 @@ Flot to keep track of its state, so be careful. - getOptions() - Gets the options for the plot, in a normalized format with default - values filled in. + Gets the options for the plot, normalized, with default values + filled in. You get a reference to actual values used by Flot, so + if you modify the values in here, Flot will use the new values. + If you change something, you probably have to call draw() or + setupGrid() or triggerRedrawOverlay() to see the change. Hooks @@ -866,6 +1010,8 @@ Here's an overview of the phases Flot goes through: 7. Responding to events, if any + 8. Shutdown: this mostly happens in case a plot is overwritten + Each hook is simply a function which is put in the appropriate array. You can add them through the "hooks" option, and they are also available after the plot is constructed as the "hooks" attribute on the returned @@ -945,14 +1091,23 @@ hooks in the plugins bundled with Flot. doesn't check it or do any normalization on it afterwards. + - drawSeries [phase 5] + + function(plot, canvascontext, series) + + Hook for custom drawing of a single series. Called just before the + standard drawing routine has been called in the loop that draws + each series. + + - draw [phase 5] function(plot, canvascontext) Hook for drawing on the canvas. Called after the grid is drawn - (unless it's disabled) and the series have been plotted (in case - any points, lines or bars have been turned on). For examples of how - to draw things, look at the source code. + (unless it's disabled or grid.aboveData is set) and the series have + been plotted (in case any points, lines or bars have been turned + on). For examples of how to draw things, look at the source code. - bindEvents [phase 6] @@ -981,6 +1136,12 @@ hooks in the plugins bundled with Flot. order wrong. The hook only gets one event, though (either for the overlay or for the static canvas). + Note that custom plot events generated by Flot are not generated on + eventHolder, but on the div placeholder supplied as the first + argument to the plot call. You can get that with + plot.getPlaceholder() - that's probably also the one you should use + if you need to fire a custom event. + - drawOverlay [phase 7] @@ -999,6 +1160,16 @@ hooks in the plugins bundled with Flot. crosshair plugin for an example. + - shutdown [phase 8] + + function (plot, eventHolder) + + Run when plot.shutdown() is called, which usually only happens in + case a plot is overwritten by a new plot. If you're writing a + plugin that adds extra DOM elements or event handlers, you should + add a callback to clean up after you. Take a look at the section in + PLUGINS.txt for more info. + Plugins ------- @@ -1016,9 +1187,15 @@ Here's a brief explanation of how the plugin plumbings work: Each plugin registers itself in the global array $.plot.plugins. When you make a new plot object with $.plot, Flot goes through this array calling the "init" function of each plugin and merging default options -from its "option" attribute. The init function gets a reference to the -plot object created and uses this to register hooks and add new public -methods if needed. +from the "option" attribute of the plugin. The init function gets a +reference to the plot object created and uses this to register hooks +and add new public methods if needed. See the PLUGINS.txt file for details on how to write a plugin. As the above description hints, it's actually pretty easy. + + +Version number +-------------- + +The version number of Flot is available in $.plot.version. |