Skip to content

F
flot
Commit f75a5a51 authored by David Schnur's avatar David Schnur
Browse files
Options

Updated axis option defaults and documentation. 

Updated the axis option defaults and docs for tickColor, tickFont,
tickWidth, and tickHeight. Also re-organized the API docs to match the
master list, and revised many areas for clarity.
parent 8d38774c
Hide whitespace changes
Inline Side-by-side
Showing with 136 additions and 134 deletions
API.md
View file @ f75a5a51
...@@ -245,61 +245,59 @@ xaxis, yaxis: { ...@@ -245,61 +245,59 @@ xaxis, yaxis: {
show: null or true/false show: null or true/false
position: "bottom" or "top" or "left" or "right" position: "bottom" or "top" or "left" or "right"
mode: null or "time" ("time" requires jquery.flot.time.js plugin) 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 color: null or color spec
font: null or font spec object font: null or font-options object
min: null or number min: null or number
max: null or number max: null or number
autoscaleMargin: null or number autoscaleMargin: null or number
transform: null or fn: number -> number transform: null or fn: number -> number
inverseTransform: null or fn: number -> number inverseTransform: null or fn: number -> number
ticks: null or number or ticks array or (fn: axis -> ticks array) ticks: null or number or ticks array or (fn: axis -> ticks array)
tickSize: number or array tickSize: number or array
minTickSize: number or array minTickSize: number or array
tickFormatter: (fn: number, object -> string) or string
tickDecimals: null or number tickDecimals: null or number
tickFormatter: (fn: number, object -> string) or string
tickColor: null or color spec tickColor: null or color spec
tickLength: null or number tickLength: null or number
tickWidth: null or number tickWidth: null or number
tickHeight: null or number tickHeight: null or number
tickFont: null or font spec object tickFont: null or font-options object
alignTicksWithAxis: null or number alignTicksWithAxis: null or number
reserveSpace: null or true reserveSpace: null or true
} }
``` ```
All axes have the same kind of options. The following describes how to All axes share the same set of options. The following descriptions are for a
configure one axis, see below for what to do if you've got more than single axis; read further down for how to create multiple x-axes or y-axes.
one x axis or y axis.
If you don't set the "show" option (i.e. it is null), visibility is 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 auto-detected, i.e. the axis will show up only if there's data associated
with it. You can override this by setting the "show" option to true or with it. You can override this by setting "show" to true or false.
false.
The "position" option specifies where the axis is placed; bottom or top for x
The "position" option specifies where the axis is placed, bottom or axes, and left or right for y axes.
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 The "mode" option determines how the data is interpreted, the default of null
numbers. Use "time" for time series data; see the time series data interprets it as decimal numbers, while "time" interprets it as time series
section. The time plugin (jquery.flot.time.js) is required for time data. See the time series data section for more information, and note that
series support. 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 The "color" option determines the color of the axis line and defaults for the
defaults to the grid color with transparency. For more fine-grained control you tick markers and label text. It defaults to the grid color with transparency.
can also set the color of the ticks separately with "tickColor".
You can customize the font and color used to draw axis text with CSS or via
You can customize the font and color used to draw the axis tick labels with CSS the "font" option. When "font" is null (the default) tick labels are assigned
or directly via the "font" option. When "font" is null - the default - each the 'flot-tick-label' class. For compatibility with Flot 0.7 and earlier the
tick label is given the 'flot-tick-label' class. For compatibility with Flot labels are also assigned the 'tickLabel' class, but this is deprecated and
0.7 and earlier the labels are also given the 'tickLabel' class, but this is scheduled to be removed with the release of version 1.0.0.
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 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 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: ...@@ -314,7 +312,7 @@ labels for a simple plot with only a single x-axis might look like this:
</div> </div>
``` ```
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: with this format:
```js ```js
...@@ -332,28 +330,25 @@ with this format: ...@@ -332,28 +330,25 @@ with this format:
The size and lineHeight must be expressed in pixels; CSS units such as 'em' The size and lineHeight must be expressed in pixels; CSS units such as 'em'
or 'smaller' are not allowed. or 'smaller' are not allowed.
The options "min"/"max" are the precise minimum/maximum value on the The "min" and "max" options specify the precise minimum/maximum value on the
scale. If you don't specify either of them, a value will automatically scale. If you don't specify either of them, Flot will automatically choose a
be chosen based on the minimum/maximum data values. Note that Flot value based on the min/max values in the data. Note that Flot always examines
always examines all the data values you feed to it, even if a all the data values you feed to it, even if a restriction on another axis may
restriction on another axis may make some of them invisible (this make some of them invisible (this makes interactive use more stable).
makes interactive use more stable).
The "autoscaleMargin" option is a bit esoteric: it's the fraction of margin
The "autoscaleMargin" is a bit esoteric: it's the fraction of margin that the scaling algorithm will add to avoid having the outermost points end
that the scaling algorithm will add to avoid that the outermost points up on the grid border. Note that this margin is only applied when a min or
ends up on the grid border. Note that this margin is only applied when max value is not explicitly set. If a margin is specified, the plot will also
a min or max value is not explicitly set. If a margin is specified, extend the axis end-point to the nearest whole tick. The default value is null
the plot will furthermore extend the axis end-point to the nearest for the x-axes and 0.02 for y-axes; this seems appropriate for most cases.
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 that you can use to change
how the data is drawn. You can design a function to compress or expand parts
"transform" and "inverseTransform" are callbacks you can put in to of the axis non-linearly, e.g. suppress weekends or compress far-away points
change the way the data is drawn. You can design a function to with a logarithm or some other means. When Flot draws the plot, each value is
compress or expand certain parts of the axis non-linearly, e.g. first put through the transform function. For example, this is how one would
suppress weekends or compress far away points with a logarithm or some implement a log scale on the x-axis:
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:
```js ```js
xaxis: { xaxis: {
...@@ -362,8 +357,7 @@ xaxis: { ...@@ -362,8 +357,7 @@ xaxis: {
} }
``` ```
Similarly, for reversing the y axis so the values appear in inverse Similarly, for reversing the y axis so the values appear in inverse order:
order:
```js ```js
yaxis: { yaxis: {
...@@ -372,38 +366,34 @@ yaxis: { ...@@ -372,38 +366,34 @@ yaxis: {
} }
``` ```
Note that for finding extrema, Flot assumes that the transform Note that for finding extrema, Flot assumes that the transform function does
function does not reorder values (it should be monotone). 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.
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 You can specify how many ticks the algorithm aims for by setting "ticks" to a
some for you. The algorithm has two passes. It first estimates how number. The algorithm always tries to generate reasonably round tick values
many ticks would be reasonable and uses this number to compute a nice so even if you ask for three ticks, you might get five if that fits better
round tick interval size. Then it generates the ticks. 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 Another option is to skip the rounding and directly set the tick interval
"ticks" to a number. The algorithm always tries to generate reasonably with "tickSize". Setting it to 2 gives you ticks at 2, 4, 6, etc. You can
round tick values so even if you ask for three ticks, you might get also specify that you just don't want ticks at a size less than a specific
five if that fits better with the rounding. If you don't want any tick size with "minTickSize". Note that for time series, the format is an
ticks at all, set "ticks" to 0 or an empty array. 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 If you want to completely override the tick algorithm, you can specify an
interval size with "tickSize". If you set it to 2, you'll get ticks at array for "ticks", either like this:
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:
```js ```js
ticks: [0, 1.2, 2.4] ticks: [0, 1.2, 2.4]
...@@ -417,11 +407,10 @@ ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]] ...@@ -417,11 +407,10 @@ ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
You can mix the two if you like. You can mix the two if you like.
For extra flexibility you can specify a function as the "ticks" For extra flexibility you can specify a function as the "ticks" parameter.
parameter. The function will be called with an object with the axis The function will be called with an object with the axis min and max, and
min and max and should return a ticks array. Here's a simplistic tick should return a ticks array. Here's a simple tick generator that produces
generator that spits out intervals of pi, suitable for use on the x intervals of pi, suitable for use on the x-axis for trigonometric functions:
axis for trigonometric functions:
```js ```js
function piTickGenerator(axis) { function piTickGenerator(axis) {
...@@ -435,13 +424,13 @@ 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). number of decimals to display (default is auto-detected).
Alternatively, for ultimate control over how ticks are formatted you can Alternatively, for ultimate control over how ticks are formatted you can
provide a function to "tickFormatter". The function is passed two provide a function to "tickFormatter". The function is passed two parameters,
parameters, the tick value and an axis object with information, and the tick value and an axis object with information, and should return a
should return a string. The default formatter looks like this: string. The default formatter looks like this:
```js ```js
function formatter(val, axis) { function formatter(val, axis) {
...@@ -449,11 +438,10 @@ 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, The axis object has "min" and "max" with the axis range, "tickDecimals" with
"tickDecimals" with the number of decimals to round the value to and the number of decimals to round the value to and "tickSize" with the size of
"tickSize" with the size of the interval between ticks as calculated the interval between ticks as calculated by the automatic axis scaling
by the automatic axis scaling algorithm (or specified by you). Here's algorithm (or specified by you). Here's an example of a custom formatter:
an example of a custom formatter:
```js ```js
function suffixFormatter(val, axis) { function suffixFormatter(val, axis) {
...@@ -466,25 +454,30 @@ function suffixFormatter(val, axis) { ...@@ -466,25 +454,30 @@ function suffixFormatter(val, axis) {
} }
``` ```
"labelWidth" and "labelHeight" specifies a fixed size of the tick "tickLength" is the length of the tick marks in pixels. By default the
labels in pixels. They're useful in case you need to align several innermost axes have ticks that extend across the plot, while any extra axes
plots. "reserveSpace" means that even if an axis isn't shown, Flot use small ticks. A value of null means to use the default, while a number
should reserve space for it - it is useful in combination with means to use ticks of that length, where zero hides the marks completely.
labelWidth and labelHeight for aligning multi-axis charts.
You can use "tickColor" to override the "color" option and give the tick
"tickLength" is the length of the tick lines in pixels. By default, the marks a different color from the axis line itself.
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, "tickWidth" and "tickHeight" specify a fixed size for the tick labels, in
while a number means small ticks of that length - set it to 0 to hide pixels. They're useful in case you need to assign several plots.
the lines completely.
You can use "tickFont" to give tick labels a different font style from the
If you set "alignTicksWithAxis" to the number of another axis, e.g. axis default. It accepts exactly the same font-options object as "font" does.
alignTicksWithAxis: 1, Flot will ensure that the autogenerated ticks
of this axis are aligned with the ticks of the other axis. This may When using multiple axes, if you set "alignTicksWithAxis" to the number of
improve the looks, e.g. if you have one y axis to the left and one to another axis, e.g. alignTicksWithAxis: 1, Flot will ensure that the generated
the right, because the grid lines will then match the ticks in both ticks of this axis are aligned with the ticks of the other axis. This may
ends. The trade-off is that the forced ticks won't necessarily be at improve the looks, e.g. if you have one y axis to the left and one to the
natural places. 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 ## ## Multiple axes ##
......
jquery.flot.js
View file @ f75a5a51
...@@ -482,27 +482,36 @@ Licensed under the MIT license. ...@@ -482,27 +482,36 @@ Licensed under the MIT license.
sorted: null // default to no legend sorting sorted: null // default to no legend sorting
}, },
xaxis: { xaxis: {
show: null, // null = auto-detect, true = always, false = never
position: "bottom", // or "top" show: null, // null = auto-detect, true = always, false = never
mode: null, // null or "time" position: "bottom", // or "top"
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" } mode: null, // null or "time"
color: null, // base color, labels, ticks
tickColor: null, // possibly different color of ticks, e.g. "rgba(0,0,0,0.15)" color: null, // base color, labels, ticks
transform: null, // null or f: number -> number to transform axis 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 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 ticks: null, // either [1, 3] or [[1, "a"], 3] or (fn: axis info -> ticks) or app. number of ticks for auto-ticks
autoscaleMargin: null, // margin in % to add if auto-setting min/max tickSize: 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 minTickSize: null, // number or [number, "unit"]
tickFormatter: null, // fn: number -> string tickFormatter: null, // fn: number -> string
tickWidth: null, // size of tick labels in pixels tickDecimals: null, // no. of decimals, null means auto
tickHeight: null,
reserveSpace: null, // whether to reserve space even if axis isn't shown 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 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 tickWidth: null, // width of tick labels in pixels
tickSize: null, // number or [number, "unit"] tickHeight: null, // height of tick labels in pixels
minTickSize: null // number or [number, "unit"] 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: { yaxis: {
autoscaleMargin: 0.02, autoscaleMargin: 0.02,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment