diff --git a/API.md b/API.md index 42c638a..f82e3e2 100644 --- a/API.md +++ b/API.md @@ -245,61 +245,59 @@ xaxis, yaxis: { show: null or true/false position: "bottom" or "top" or "left" or "right" mode: null or "time" ("time" requires jquery.flot.time.js plugin) - timezone: null, "browser" or timezone (only makes sense for mode: "time") + timezone: null or "browser" or timezone (only used with mode: "time") color: null or color spec - font: null or font spec object + font: null or font-options object min: null or number max: null or number autoscaleMargin: null or number - + transform: null or fn: number -> number inverseTransform: null or fn: number -> number - + ticks: null or number or ticks array or (fn: axis -> ticks array) tickSize: number or array minTickSize: number or array - tickFormatter: (fn: number, object -> string) or string tickDecimals: null or number + tickFormatter: (fn: number, object -> string) or string tickColor: null or color spec tickLength: null or number tickWidth: null or number tickHeight: null or number - tickFont: null or font spec object + tickFont: null or font-options object alignTicksWithAxis: null or number reserveSpace: null or true } ``` -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. +All axes share the same set of options. The following descriptions are for a +single axis; read further down for how to create multiple x-axes or y-axes. 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 time plugin (jquery.flot.time.js) is required for time -series support. - -The "color" option determines the color of the line and ticks for the axis, and -defaults to the grid color with transparency. For more fine-grained control you -can also set the color of the ticks separately with "tickColor". - -You can customize the font and color used to draw the axis tick labels with CSS -or directly via the "font" option. When "font" is null - the default - each -tick label is given the 'flot-tick-label' class. For compatibility with Flot -0.7 and earlier the labels are also given the 'tickLabel' class, but this is -deprecated and scheduled to be removed with the release of version 1.0.0. +auto-detected, i.e. the axis will show up only if there's data associated +with it. You can override this by setting "show" to true or false. + +The "position" option specifies where the axis is placed; bottom or top for x +axes, and left or right for y axes. + +The "mode" option determines how the data is interpreted, the default of null +interprets it as decimal numbers, while "time" interprets it as time series +data. See the time series data section for more information, and note that +the time plugin (jquery.flot.time.js) is required for time series support. + +The "color" option determines the color of the axis line and defaults for the +tick markers and label text. It defaults to the grid color with transparency. + +You can customize the font and color used to draw axis text with CSS or via +the "font" option. When "font" is null (the default) tick labels are assigned +the 'flot-tick-label' class. For compatibility with Flot 0.7 and earlier the +labels are also assigned the 'tickLabel' class, but this is deprecated and +scheduled to be removed with the release of version 1.0.0. To enable more granular control over styles, labels are divided between a set of text containers, with each holding the labels for one axis. These containers @@ -314,7 +312,7 @@ labels for a simple plot with only a single x-axis might look like this: ``` -For direct control over label styles you can also provide "font" as an object +For direct control over text styles you can also provide "font" as an object with this format: ```js @@ -332,28 +330,25 @@ with this format: The size and lineHeight must be expressed in pixels; CSS units such as 'em' or 'smaller' are not allowed. -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. 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 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 -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: +The "min" and "max" options specify the precise minimum/maximum value on the +scale. If you don't specify either of them, Flot will automatically choose a +value based on the min/max values in the data. 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" option is a bit esoteric: it's the fraction of margin +that the scaling algorithm will add to avoid having the outermost points end +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 also +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; this seems appropriate for most cases. + +"transform" and "inverseTransform" are callbacks that you can use to change +how the data is drawn. You can design a function to compress or expand 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. For example, this is how one would +implement a log scale on the x-axis: ```js xaxis: { @@ -362,8 +357,7 @@ xaxis: { } ``` -Similarly, for reversing the y axis so the values appear in inverse -order: +Similarly, for reversing the y axis so the values appear in inverse order: ```js yaxis: { @@ -372,38 +366,34 @@ yaxis: { } ``` -Note that for finding extrema, Flot assumes that the transform -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 -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. +Note that for finding extrema, Flot assumes that the transform 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 required for +converting from canvas coordinates to data coordinates, i.e. 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 options, a tick generator algorithm will make +some for you. The algorithm has two passes. It first estimates how many ticks +would be reasonable, uses this to compute a nice round tick interval size, +then generates the ticks. -If you don't specify any ticks, a tick generator algorithm will make -some for you. The algorithm has two passes. It first estimates how -many ticks would be reasonable and uses this number to compute a nice -round tick interval size. Then it generates the ticks. +You can specify how many ticks the algorithm aims for by setting "ticks" to a +number. The algorithm always tries to generate reasonably round tick values +so even if you ask for three ticks, you might get five if that fits better +with the rounding. If you don't want any ticks at all, set "ticks" to 0 or an +empty array. -You can specify how many ticks the algorithm aims for by setting -"ticks" to a number. The algorithm always tries to generate reasonably -round tick values so even if you ask for three ticks, you might get -five if that fits better with the rounding. If you don't want any -ticks at all, set "ticks" to 0 or an empty array. +Another option is to skip the rounding and directly set the tick interval +with "tickSize". Setting it to 2 gives you ticks at 2, 4, 6, etc. You can +also specify that you just don't want ticks at a size less than a specific +tick size with "minTickSize". Note that for time series, the format is an +array like [2, "month"]; see the time series data section for more info. -Another option is to skip the rounding part and directly set the tick -interval size with "tickSize". If you set it to 2, you'll get ticks at -2, 4, 6, etc. Alternatively, you can specify that you just don't want -ticks at a size less than a specific tick size with "minTickSize". -Note that for time series, the format is an array like [2, "month"], -see the next section. - -If you want to completely override the tick algorithm, you can specify -an array for "ticks", either like this: +If you want to completely override the tick algorithm, you can specify an +array for "ticks", either like this: ```js ticks: [0, 1.2, 2.4] @@ -417,11 +407,10 @@ ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]] You can mix the two if you like. -For extra flexibility you can specify a function as the "ticks" -parameter. The function will be called with an object with the axis -min and max and should return a ticks array. Here's a simplistic tick -generator that spits out intervals of pi, suitable for use on the x -axis for trigonometric functions: +For extra flexibility you can specify a function as the "ticks" parameter. +The function will be called with an object with the axis min and max, and +should return a ticks array. Here's a simple tick generator that produces +intervals of pi, suitable for use on the x-axis for trigonometric functions: ```js function piTickGenerator(axis) { @@ -435,13 +424,13 @@ function piTickGenerator(axis) { } ``` -You can control how the ticks look like with "tickDecimals", the +You can control how the ticks look with "tickDecimals", which specifies the number of decimals to display (default is auto-detected). 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: +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: ```js function formatter(val, axis) { @@ -449,11 +438,10 @@ function formatter(val, axis) { } ``` -The axis object has "min" and "max" with the range of the axis, -"tickDecimals" with the number of decimals to round the value to and -"tickSize" with the size of the interval between ticks as calculated -by the automatic axis scaling algorithm (or specified by you). Here's -an example of a custom formatter: +The axis object has "min" and "max" with the axis range, "tickDecimals" with +the number of decimals to round the value to and "tickSize" with the size of +the interval between ticks as calculated by the automatic axis scaling +algorithm (or specified by you). Here's an example of a custom formatter: ```js function suffixFormatter(val, axis) { @@ -466,25 +454,30 @@ function suffixFormatter(val, axis) { } ``` -"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. +"tickLength" is the length of the tick marks in pixels. By default the +innermost axes have ticks that extend across the plot, while any extra axes +use small ticks. A value of null means to use the default, while a number +means to use ticks of that length, where zero hides the marks completely. + +You can use "tickColor" to override the "color" option and give the tick +marks a different color from the axis line itself. + +"tickWidth" and "tickHeight" specify a fixed size for the tick labels, in +pixels. They're useful in case you need to assign several plots. + +You can use "tickFont" to give tick labels a different font style from the +axis default. It accepts exactly the same font-options object as "font" does. + +When using multiple axes, if you set "alignTicksWithAxis" to the number of +another axis, e.g. alignTicksWithAxis: 1, Flot will ensure that the generated +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 on both ends. The +trade-off is that the forced ticks won't necessarily be at natural places. + +"reserveSpace" indicates that Flot should reserve space for the axis even if +it isn't visible. This is useful in combination with labelWidth/labelHeight +for aligning multi-axis charts. ## Multiple axes ## diff --git a/jquery.flot.js b/jquery.flot.js index 3764c16..e0b7c7f 100644 --- a/jquery.flot.js +++ b/jquery.flot.js @@ -482,27 +482,36 @@ Licensed under the MIT license. sorted: null // default to no legend sorting }, xaxis: { - show: null, // null = auto-detect, true = always, false = never - position: "bottom", // or "top" - mode: null, // null or "time" - font: null, // null (derived from CSS in placeholder) or object like { size: 11, lineHeight: 13, style: "italic", weight: "bold", family: "sans-serif", variant: "small-caps" } - color: null, // base color, labels, ticks - tickColor: null, // possibly different color of ticks, e.g. "rgba(0,0,0,0.15)" - transform: null, // null or f: number -> number to transform axis + + show: null, // null = auto-detect, true = always, false = never + position: "bottom", // or "top" + mode: null, // null or "time" + + color: null, // base color, labels, ticks + font: null, // null (derived from CSS in placeholder) or object like { size: 11, lineHeight: 13, style: "italic", weight: "bold", family: "sans-serif", variant: "small-caps" } + + min: null, // min. value to show, null means set automatically + max: null, // max. value to show, null means set automatically + autoscaleMargin: null, // margin in % to add if auto-setting min/max + + transform: null, // null or f: number -> number to transform axis inverseTransform: null, // if transform is set, this should be the inverse function - min: null, // min. value to show, null means set automatically - max: null, // max. value to show, null means set automatically - autoscaleMargin: null, // margin in % to add if auto-setting min/max - ticks: null, // either [1, 3] or [[1, "a"], 3] or (fn: axis info -> ticks) or app. number of ticks for auto-ticks - tickFormatter: null, // fn: number -> string - tickWidth: null, // size of tick labels in pixels - tickHeight: null, - reserveSpace: null, // whether to reserve space even if axis isn't shown - tickLength: null, // size in pixels of ticks, or "full" for whole line - alignTicksWithAxis: null, // axis number or null for no sync - tickDecimals: null, // no. of decimals, null means auto - tickSize: null, // number or [number, "unit"] - minTickSize: null // number or [number, "unit"] + + ticks: null, // either [1, 3] or [[1, "a"], 3] or (fn: axis info -> ticks) or app. number of ticks for auto-ticks + tickSize: null, // number or [number, "unit"] + minTickSize: null, // number or [number, "unit"] + tickFormatter: null, // fn: number -> string + tickDecimals: null, // no. of decimals, null means auto + + tickColor: null, // possibly different color of ticks, e.g. "rgba(0,0,0,0.15)" + tickLength: null, // size in pixels of ticks, or "full" for whole line + + tickWidth: null, // width of tick labels in pixels + tickHeight: null, // height of tick labels in pixels + tickFont: null, // null or font-spec object (see font, above) + + reserveSpace: null, // whether to reserve space even if axis isn't shown + alignTicksWithAxis: null // axis number or null for no sync }, yaxis: { autoscaleMargin: 0.02,