diff options
Diffstat (limited to 'API.txt')
| -rw-r--r-- | API.txt | 543 |
1 files changed, 372 insertions, 171 deletions
@@ -40,7 +40,7 @@ E.g. [ [1, 3], [2, 14.01], [3.5, 3.14] ] Note that to simplify the internal logic in Flot both the x and y -values must be numbers, even if specifying time series (see below for +values must be numbers (even if specifying time series, see below for how to do this). This is a common problem because you might retrieve data from the database and serialize them directly to JSON without noticing the wrong type. If you're getting mysterious errors, double @@ -49,7 +49,7 @@ check that you're inputting numbers and not strings. If a null is specified as a point or if one of the coordinates is null or couldn't be converted to a number, the point is ignored when drawing. As a special case, a null value for lines is interpreted as a -line segment end, i.e. the point before and after the null value are +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 @@ -64,7 +64,6 @@ The format of a single series object is as follows: lines: specific lines options bars: specific bars options points: specific points options - threshold: specific threshold options xaxis: 1 or 2 yaxis: 1 or 2 clickable: boolean @@ -100,7 +99,7 @@ E.g., you can use this to make a dual axis plot by specifying "clickable" and "hoverable" can be set to false to disable interactivity for specific series if interactivity is turned on in -plot, see below. +the plot, see below. The rest of the options are all documented below as they are the same as the default options passed in via the options parameter in the plot @@ -120,8 +119,10 @@ All options are completely optional. They are documented individually below, to change them you just specify them in an object, e.g. var options = { - lines: { show: true }, - points: { show: true } + series: { + lines: { show: true }, + points: { show: true } + } }; $.plot(placeholder, data, options); @@ -165,8 +166,6 @@ If you want the legend to appear somewhere else in the DOM, you can specify "container" as a jQuery object/expression to put the legend table into. The "position" and "margin" etc. options will then be ignored. Note that Flot will overwrite the contents of the container. -Most of the above settings do not apply - Customizing the axes @@ -177,9 +176,13 @@ Customizing the axes 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 + ticks: null or number or ticks array or (fn: range -> ticks array) tickSize: number or array minTickSize: number or array @@ -203,10 +206,33 @@ 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. +"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. +suppress weekends or compress far away points with a logarithm or some +other means. When Flot draws the plot, each value is first put through +the transform function. Here's an example, the x axis can be turned +into a natural logarithm axis with the following code: + + xaxis: { + transform: function (v) { return Math.log(v); }, + inverseTransform: function (v) { return Math.exp(v); } + } + +Note that for finding extrema, Flot assumes that the transform +function does not reorder values (monotonicity is assumed). + +The inverseTransform is simply the inverse of the transform function +(so v == inverseTransform(transform(v)) for all relevant v). It is +required for converting from canvas coordinates to data coordinates, +e.g. for a mouse interaction where a certain pixel is clicked. If you +don't use any interactive features of Flot, you may not need it. + + The rest of the options deal with the ticks. If you don't specify any ticks, a tick generator algorithm will make @@ -283,7 +309,6 @@ an example of a custom formatter: return val.toFixed(axis.tickDecimals) + " B"; } - Time series data ================ @@ -354,6 +379,7 @@ through the following axis options: minTickSize: array timeformat: null or format string monthNames: null or array of size 12 of strings + twelveHourClock: boolean Here "timeformat" is a format string to use. You might use it like this: @@ -366,20 +392,25 @@ this: This will result in tick labels like "2000/12/24". The following specifiers are supported - %h': hours - %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) - %y': year (four digits) - %b': month name (customizable) + %h: hours + %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) + %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) You can customize the month names with the "monthNames" option. For instance, for Danish you might specify: monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"] +If you set "twelveHourClock" to true, the autogenerated timestamps +will use 12 hour AM/PM timestamps instead of 24 hour. + The format string and month names are used by a very simple built-in format function that takes a date object, a format string (and optionally an array of month names) and returns the formatted string. @@ -412,47 +443,51 @@ been produced with two days in-between. Customizing the data series =========================== - lines, points, bars: { - show: boolean - lineWidth: number - fill: boolean or number - fillColor: null or color/gradient - } - - points: { - radius: number - } - - bars: { - barWidth: number - align: "left" or "center" - horizontal: boolean - } + series: { + lines, points, bars: { + show: boolean + lineWidth: number + fill: boolean or number + fillColor: null or color/gradient + } - lines: { - steps: boolean - } + points: { + radius: number + } - colors: [ color1, color2, ... ] + bars: { + barWidth: number + align: "left" or "center" + horizontal: boolean + } - shadowSize: number + lines: { + steps: boolean + } - threshold: { - below: number - color: color + shadowSize: number } + + colors: [ color1, color2, ... ] +The options inside "series: {}" are copied to each of the series. So +you can specify that all series should have bars by putting it in the +global options, or override it for individual series by specifying +bars in a particular the series object in the array of data. + The most important options are "lines", "points" and "bars" that -specifies whether and how lines, points and bars should be shown for +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 independently of each other, and Flot will happily draw each of them -in turn, e.g. +in turn (this is probably only useful for lines and points), e.g. var options = { - lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" }, - points: { show: true, fill: false } + series: { + lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" }, + points: { show: true, fill: false } + } }; "lineWidth" is the thickness of the line or outline in pixels. You can @@ -468,20 +503,24 @@ setting fill to a number between 0 (fully transparent) and 1 (fully opaque). For bars, fillColor can be a gradient, see the gradient documentation -below. "barWidth" is the width of the bars in units of the x axis, -contrary to most other measures that are specified in pixels. For -instance, for time series the unit is milliseconds so 24 * 60 * 60 * -1000 produces bars with the width of a day. "align" specifies whether -a bar should be left-aligned (default) or centered on top of the value -it represents. When "horizontal" is on, the bars are drawn -horizontally, i.e. from the y axis instead of the x axis; note that -the bar end points are still defined in the same way so you'll -probably want to swap the coordinates if you've been plotting vertical -bars first. +below. "barWidth" is the width of the bars in units of the x axis (or +the y axis if "horizontal" is true), contrary to most other measures +that are specified in pixels. For instance, for time series the unit +is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of +a day. "align" specifies whether a bar should be left-aligned +(default) or centered on top of the value it represents. When +"horizontal" is on, the bars are drawn horizontally, i.e. from the y +axis instead of the x axis; note that the bar end points are still +defined in the same way so you'll probably want to swap the +coordinates if you've been plotting vertical bars first. For lines, "steps" specifies whether two adjacent data points are connected with a straight (possibly diagonal) line or with first a -horizontal and then a vertical line. +horizontal and then a vertical line. Note that this transforms the +data by adding extra points. + +"shadowSize" is the default size of shadows in pixels. Set it to 0 to +remove shadows. The "colors" array specifies a default color theme to get colors for the data series from. You can specify as many colors as you like, like @@ -492,18 +531,13 @@ this: If there are more data series than colors, Flot will try to generate extra colors by lightening and darkening colors in the theme. -"shadowSize" is the default size of shadows in pixels. Set it to 0 to -remove shadows. - -"threshold" specifies that the data points below "below" should be -drawn with the specified color. This makes it easy to mark points -below 0, e.g. for budget data. - Customizing the grid ==================== grid: { + show: boolean + aboveData: boolean color: color backgroundColor: color/gradient or null tickColor: color @@ -523,6 +557,10 @@ background color inside the grid area. The default value of 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 +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". @@ -552,7 +590,7 @@ A line is drawn if from and to are the same, e.g. markings: [ { yaxis: { from: 1, to: 1 } }, ... ] would draw a line parallel to the x axis at y = 1. You can control the -line width with "lineWidth" in the ranges objects. +line width with "lineWidth" in the range object. An example function might look like this: @@ -595,7 +633,7 @@ You can use "plotclick" and "plothover" events like this: The item object in this example is either null or a nearby object on the form: item: { - datapoint: the point as you specified it in the data, e.g. [0, 2] + datapoint: the point, e.g. [0, 2] dataIndex: the index of the point in the data array series: the series object seriesIndex: the index of the series @@ -606,10 +644,12 @@ For instance, if you have specified the data like this $.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...); -and the mouse is near the point (7, 3), "datapoint" is the [7, 3] we -specified, "dataIndex" will be 1, "series" is a normalized series -object with among other things the "Foo" label in series.label and the -color in series.color, and "seriesIndex" is 0. +and the mouse is near the point (7, 3), "datapoint" is [7, 3], +"dataIndex" will be 1, "series" is a normalized series object with +among other things the "Foo" label in series.label and the color in +series.color, and "seriesIndex" is 0. Note that plugins and options +that transform the data can shift the indexes from what you specified +in the original data array. If you use the above events to update some other information and want to clear out that info in case the mouse goes away, you'll probably @@ -625,53 +665,6 @@ can set "hoverable" and "clickable" to false in the options for that series, like this { data: [...], label: "Foo", clickable: false }. -Customizing the selection -========================= - - selection: { - mode: null or "x" or "y" or "xy", - color: color - } - -You enable selection support by setting the mode to one of "x", "y" or -"xy". In "x" mode, the user will only be able to specify the x range, -similarly for "y" mode. For "xy", the selection becomes a rectangle -where both ranges can be specified. "color" is color of the selection. - -When selection support is enabled, a "plotselected" event will be emitted -on the DOM element you passed into the plot function. The event -handler gets one extra parameter with the ranges selected on the axes, -like this: - - placeholder.bind("plotselected", function(event, ranges) { - alert("You selected " + ranges.xaxis.from + " to " + ranges.xaxis.to) - // similar for yaxis, secondary axes are in x2axis - // 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, - -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 ==================== @@ -690,10 +683,18 @@ For the series you can specify the gradient as an object that specifies the scaling of the brightness and the opacity of the series color, e.g. - { colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] + { colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] } where the first color simply has its alpha scaled, whereas the second -is also darkened. +is also darkened. For instance, for bars the following makes the bars +gradually disappear, without outline: + + bars: { + show: true, + lineWidth: 0, + fill: true, + fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] } + } Flot currently only supports vertical gradients drawn from top to bottom because that's what works with IE. @@ -705,53 +706,22 @@ Plot Methods The Plot object returned from the plot function has some methods you can call: - - setSelection(ranges, preventEvent) - - Set the selection rectangle. The passed in ranges is on the same - form as returned in the "plotselected" event. If the selection - mode is "x", you should put in either an xaxis (or x2axis) object, - if the mode is "y" you need to put in an yaxis (or y2axis) object - and both xaxis/x2axis and yaxis/y2axis if the selection mode is - "xy", like this: - - setSelection({ xaxis: { from: 0, to: 10 }, yaxis: { from: 40, to: 60 } }); - - 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(preventEvent) - - Clear the selection rectangle. Pass in true to avoid getting a - "plotunselected" event. - - - - 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) Highlight a specific datapoint in the data series. You can either specify the actual objects, e.g. if you got them from a "plotclick" event, or you can specify the indices, e.g. - highlight(1, 3) to highlight the fourth point in the second series. + highlight(1, 3) to highlight the fourth point in the second series + (remember, zero-based indexing). - - unhighlight(series, datapoint) + - unhighlight(series, datapoint) or unhighlight() - Remove the highlighting of the point, same parameters as highlight. + Remove the highlighting of the point, same parameters as + highlight. + + If you call unhighlight with no parameters, e.g. as + plot.unhighlight(), all current highlights are removed. - setData(data) @@ -760,10 +730,11 @@ can call: ticks, legend etc. will not be recomputed (use setupGrid() to do that). You'll probably want to call draw() afterwards. - You can use this function to speed up redrawing a plot if you know - that the axes won't change. Put in the new data with - setData(newdata) and call draw() afterwards, and you're good to - go. + You can use this function to speed up redrawing a small plot if + you know that the axes won't change. Put in the new data with + setData(newdata), call draw(), and you're good to go. Note that + for large datasets, almost all the time is consumed in draw() + plotting the data so in this case don't bother. - setupGrid() @@ -778,17 +749,47 @@ can call: - draw() - Redraws the canvas. - + Redraws the plot canvas. + + - triggerRedrawOverlay() + + Schedules an update of an overlay canvas used for drawing + 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). + + - 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). + + - 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 + can specify the x and y axis references, e.g. + + o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 2 }) + // o.left and o.top now contains the offset within the div + There are also some members that let you peek inside the internal -workings of Flot which in some cases is useful. Note that if you change +workings of Flot which is useful in some cases. Note that if you change something in the objects returned, you're changing the objects used by Flot to keep track of its state, so be careful. - getData() - Returns an array of the data series currently used on normalized + Returns an array of the data series currently used in normalized form with missing settings filled in according to the global options. So for instance to find out what color Flot has assigned to the data series, you could do this: @@ -797,20 +798,32 @@ Flot to keep track of its state, so be careful. for (var i = 0; i < series.length; ++i) alert(series[i].color); + A notable other interesting field besides color is datapoints + which has a field "points" with the normalized data points in a + flat array (the field "pointsize" is the increment in the flat + array to get to the next point so for a dataset consisting only of + (x,y) pairs it would be 2). - getAxes() Gets an object with the axes settings as { xaxis, yaxis, x2axis, - y2axis }. 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. - + y2axis }. + + 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. + + - getPlaceholder() + + Returns placeholder that the plot was put into. This can be useful + for plugins for adding DOM elements or firing events. - getCanvas() Returns the canvas used for drawing in case you need to hack on it yourself. You'll probably need to get the plot offset too. - - getPlotOffset() @@ -820,4 +833,192 @@ Flot to keep track of its state, so be careful. placed at (left, top), its center will be at the top-most, left corner of the grid. + - getOptions() + + Gets the options for the plot, in a normalized format with default + values filled in. + + +Hooks +===== + +In addition to the public methods, the Plot object also has some hooks +that can be used to modify the plotting process. You can install a +callback function at various points in the process, the function then +gets access to the internal data structures in Flot. + +Here's an overview of the phases Flot goes through: + + 1. Plugin initialization, parsing options + + 2. Constructing the canvases used for drawing + + 3. Set data: parsing data specification, calculating colors, + copying raw data points into internal format, + normalizing them, finding max/min for axis auto-scaling + + 4. Grid setup: calculating axis spacing, ticks, inserting tick + labels, the legend + + 5. Draw: drawing the grid, drawing each of the series in turn + + 6. Setting up event handling for interactive features + + 7. Responding to events, if any + +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 +plot object, e.g. + + // define a simple draw hook + function hellohook(plot, canvascontext) { alert("hello!"); }; + + // pass it in, in an array since we might want to specify several + var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } }); + + // we can now find it again in plot.hooks.draw[0] unless a plugin + // has added other hooks + +The available hooks are described below. All hook callbacks get the +plot object as first parameter. You can find some examples of defined +hooks in the plugins bundled with Flot. + + - processOptions [phase 1] + + function(plot, options) + + Called after Flot has parsed and merged options. Useful in the + instance where customizations beyond simple merging of default + values is needed. A plugin might use it to detect that it has been + enabled and then turn on or off other options. + + + - processRawData [phase 3] + + function(plot, series, data, datapoints) + + Called before Flot copies and normalizes the raw data for the given + series. If the function fills in datapoints.points with normalized + points and sets datapoints.pointsize to the size of the points, + Flot will skip the copying/normalization step for this series. + + In any case, you might be interested in setting datapoints.format, + an array of objects for specifying how a point is normalized and + how it interferes with axis scaling. + + The default format array for points is something along the lines of: + + [ + { x: true, number: true, required: true }, + { y: true, number: true, required: true } + ] + The first object means that for the first coordinate it should be + taken into account when scaling the x axis, that it must be a + number, and that it is required - so if it is null or cannot be + converted to a number, the whole point will be zeroed out with + nulls. Beyond these you can also specify "defaultValue", a value to + use if the coordinate is null. This is for instance handy for bars + where one can omit the third coordinate (the bottom of the bar) + which then defaults to 0. + + + - processDatapoints [phase 3] + + function(plot, series, datapoints) + + Called after normalization of the given series but before finding + min/max of the data points. This hook is useful for implementing data + transformations. "datapoints" contains the normalized data points in + a flat array as datapoints.points with the size of a single point + given in datapoints.pointsize. Here's a simple transform that + multiplies all y coordinates by 2: + + function multiply(plot, series, datapoints) { + var points = datapoints.points, ps = datapoints.pointsize; + for (var i = 0; i < points.length; i += ps) + points[i + 1] *= 2; + } + + Note that you must leave datapoints in a good condition as Flot + doesn't check it or do any normalization on it afterwards. + + + - 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. + + + - 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 +------- + +Plugins extend the functionality of Flot. To use a plugin, simply +include its Javascript file after Flot in the HTML page. + +If you're worried about download size/latency, you can concatenate all +the plugins you use, and Flot itself for that matter, into one big file +(make sure you get the order right), then optionally run it through a +Javascript minifier such as YUI Compressor. + +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. + +See the PLUGINS.txt file for details on how to write a plugin. As the +above description hints, it's actually pretty easy. |