Class which represents an axis of a cartesian chart. More...

#include <Wt/Chart/WAxis>

Classes
struct	TickLabel
	Represents a label/tick on the axis. More...

Public Types
typedef boost::function< double(double)>	LabelTransform
	A label transform function. More...

Public Member Functions
	WAxis ()
	Constructor.

virtual	~WAxis ()
	Destructor.

Axis	id () const
	Returns the axis id. More...

void	setVisible (bool visible)
	Sets whether this axis is visible. More...

bool	isVisible () const
	Returns whether this axis is visible. More...

void	setLocation (AxisValue value)
	Sets the axis location. More...

AxisValue	location () const
	Returns the axis location. More...

void	setScale (AxisScale scale)
	Sets the scale of the axis. More...

AxisScale	scale () const
	Returns the scale of the axis. More...

void	setMinimum (double minimum)
	Sets the minimum value displayed on the axis. More...

double	minimum () const
	Returns the minimum value displayed on the axis. More...

void	setMaximum (double maximum)
	Sets the maximum value for the axis displayed on the axis. More...

double	maximum () const
	Returns the maximum value displayed on the axis. More...

void	setRange (double minimum, double maximum)
	Sets the axis range (minimum and maximum values) manually. More...

void	setResolution (double resolution)
	Sets the axis resolution. More...

double	resolution () const
	Returns the axis resolution. More...

void	setAutoLimits (WFlags< AxisValue > locations)
	Let the minimum and/or maximum be calculated from the data. More...

WFlags< AxisValue >	autoLimits () const
	Returns the limits that are calculated automatically. More...

void	setRoundLimits (WFlags< AxisValue > locations)
	Specifies whether limits should be rounded. More...

WFlags< AxisValue >	roundLimits () const
	Returns whether limits should be rounded. More...

void	setBreak (double minimum, double maximum)
	Specifies a range that needs to be omitted from the axis. More...

void	setLabelInterval (double labelInterval)
	Sets the label interval. More...

double	labelInterval () const
	Returns the label interval. More...

void	setLabelBasePoint (double point)
	Sets a point to be included as one of the labels (if possible). More...

double	labelBasePoint () const
	Returns the base point for labels. More...

void	setLabelFormat (const WString &format)
	Sets the label format. More...

WString	labelFormat () const
	Returns the label format string. More...

void	setLabelAngle (double angle)
	Sets the label angle. More...

double	labelAngle () const
	Returns the label angle. More...

void	setTitleOrientation (const Orientation &orientation)
	Sets the title orientation. More...

const Orientation &	titleOrientation () const
	Returns the title orientation. More...

void	setGridLinesEnabled (bool enabled)
	Sets whether gridlines are displayed for this axis. More...

bool	isGridLinesEnabled () const
	Returns whether gridlines are displayed for this axis. More...

void	setPen (const WPen &pen)
	Changes the pen used for rendering the axis and ticks. More...

const WPen &	pen () const
	Returns the pen used for rendering the axis and ticks. More...

void	setTextPen (const WPen &pen)
	Changes the pen used for rendering labels for this axis. More...

const WPen &	textPen () const
	Returns the pen used for rendering labels for this axis. More...

void	setGridLinesPen (const WPen &pen)
	Changes the pen used for rendering the grid lines. More...

const WPen &	gridLinesPen () const
	Returns the pen used for rendering the grid lines. More...

void	setMargin (int pixels)
	Sets the margin between the axis and the plot area. More...

int	margin () const
	Returns the margin between the axis and the plot area. More...

void	setTitle (const WString &title)
	Sets the axis title. More...

const WString &	title () const
	Returns the axis title. More...

void	setTitleFont (const WFont &titleFont)
	Sets the axis title font. More...

const WFont &	titleFont () const
	Returns the axis title font. More...

void	setTitleOffset (double offset)
	Sets the offset from the axis for the title label.

double	titleOffset () const
	Returns the title offset.

void	setLabelFont (const WFont &labelFont)
	Sets the axis label font. More...

const WFont &	labelFont () const
	Returns the axis label font. More...

virtual WString	label (double u) const
	Returns the label for a value. More...

void	setZoomRange (double minimum, double maximum)
	Set the range to zoom to on this axis. More...

double	zoomMinimum () const
	Get the zoom range minimum for this axis. More...

double	zoomMaximum () const
	Get the zoom range maximum for this axis. More...

Signal< double, double > &	zoomRangeChanged ()
	A signal triggered when the zoom range is changed on the client side. More...

void	setZoom (double zoom)
	Sets the zoom level for this axis. More...

double	zoom () const
	Get the zoom level for this axis. More...

void	setMaxZoom (double maxZoom)
	Sets the maximum zoom level for this axis. More...

double	maxZoom () const
	Get the maximum zoom level for this axis. More...

void	setMinimumZoomRange (double size)
	Sets the minimum zoom range for this axis. More...

double	minimumZoomRange () const
	Get the minimum zoom range for this axis. More...

void	setPan (double pan)
	Sets the value to pan to for this axis. More...

double	pan () const
	Get the value to pan to for this axis, when pan is enabled on the chart. More...

void	setPadding (int padding)
	Sets the padding between the chart area and this axis. More...

int	padding () const
	Returns the padding between the chart area and this axis. More...

void	setTickDirection (TickDirection direction)
	Sets the direction that the axis ticks should point to. More...

TickDirection	tickDirection () const
	Gets the direction that the axis ticks point to. More...

void	setSoftLabelClipping (bool enabled)
	Enables soft clipping of axis labels. More...

bool	softLabelClipping () const
	Returns whether soft label clipping is enabled. More...

void	setInverted (bool inverted=true)
	Set whether this axis should be inverted. More...

bool	inverted () const
	Get whether this axis is inverted. More...

void	setLabelTransform (const LabelTransform &transform, AxisValue side)
	Set the transform function to apply to a given side. More...

LabelTransform	labelTransform (AxisValue side) const
	Get the label transform configured for the given side. More...

Static Public Attributes
static const double	AUTO_MINIMUM = -DBL_MAX
	Constant which indicates automatic minimum calculation. More...

static const double	AUTO_MAXIMUM = DBL_MAX
	Constant which indicates automatic maximum calculation. More...

Protected Types

Protected Member Functions
virtual void	getLabelTicks (std::vector< TickLabel > &ticks, int segment, AxisConfig config) const
	Returns the label (and ticks) information for this axis.

virtual WString	autoDateFormat (const WDateTime &dt, DateTimeUnit unit, bool atTick) const
	Returns the Date format.

Detailed Description

Class which represents an axis of a cartesian chart.

A cartesian chart has two or three axes: an X axis (XAxis), a Y axis (YAxis) and optionally a second Y axis (Y2Axis). Each of the up to three axes in a cartesian chart has a unique id() that identifies which of these three axes it is in the enclosing chart().

Use setVisible() to change the visibility of an axis, setGridLinesEnabled() to show grid lines for an axis. The pen styles for rendering the axis or grid lines may be changed using setPen() and setGridLinesPen(). A margin between the axis and the main plot area may be configured using setMargin().

By default, the axis will automatically adjust its range so that all data will be visible. You may manually specify a range using setMinimum(), setMaximum or setRange(). The interval between labels is by default automatically adjusted depending on the axis length and the range, but may be manually specified using setLabelInterval().

The axis has support for being "broken", to support displaying data with a few outliers which would otherwise swamp the chart. This is not done automatically, but instead you need to use setBreak() to specify the value range that needs to be omitted from the axis. The omission is rendered in the axis and in bars that cross the break.

The labels are shown using a "%.4g" format string for numbers, and a suitable format for DateScale or DateTimeScale scales, based on heuristics. The format may be customized using setLabelFormat(). The angle of the label text may be changed using setLabelAngle(). By default, all labels are printed horizontally.

See also: WCartesianChart

Member Typedef Documentation

typedef boost::function<double (double)> Wt::Chart::WAxis::LabelTransform

A label transform function.

The label transform is a function from double to double.

See also: WAxis::setLabelTransform()

Member Function Documentation

WFlags< AxisValue > Wt::Chart::WAxis::autoLimits ( ) const

Returns the limits that are calculated automatically.

This returns the limits (Chart::MinimumValue and/or Chart::MaximumValue) that are calculated automatically from the data, rather than being specified manually using setMinimum() and/or setMaximum().

See also: setAutoLimits()

const WPen& Wt::Chart::WAxis::gridLinesPen ( ) const

Returns the pen used for rendering the grid lines.

See also: setGridLinesPen()

Axis Wt::Chart::WAxis::id ( ) const

Returns the axis id.

See also: chart(), WCartesianChart::axis()

bool Wt::Chart::WAxis::inverted ( ) const

Get whether this axis is inverted.

See also: setInverted()

bool Wt::Chart::WAxis::isGridLinesEnabled ( ) const

Returns whether gridlines are displayed for this axis.

See also: setGridLinesEnabled()

bool Wt::Chart::WAxis::isVisible ( ) const

Returns whether this axis is visible.

See also: setVisible()

WString Wt::Chart::WAxis::label ( double u ) const

virtual

Returns the label for a value.

This returns the label text that corresponds to a given value.

The default implementation uses the labelFormat() to properly represent the value.

double Wt::Chart::WAxis::labelAngle ( ) const

Returns the label angle.

See also: setLabelAngle()

double Wt::Chart::WAxis::labelBasePoint ( ) const

Returns the base point for labels.

See also: setLabelBasePoint()

const WFont& Wt::Chart::WAxis::labelFont ( ) const

Returns the axis label font.

See also: setLabelFont()

WString Wt::Chart::WAxis::labelFormat ( ) const

Returns the label format string.

See also: setLabelFormat()

double Wt::Chart::WAxis::labelInterval ( ) const

Returns the label interval.

See also: setLabelInterval()

WAxis::LabelTransform Wt::Chart::WAxis::labelTransform ( AxisValue side ) const

Get the label transform configured for the given side.

If no transform is configured for the given side, the identity function is returned.

See also: setLabelTransform()

AxisValue Wt::Chart::WAxis::location ( ) const

Returns the axis location.

See also: setLocation()

int Wt::Chart::WAxis::margin ( ) const

Returns the margin between the axis and the plot area.

See also: setMargin()

double Wt::Chart::WAxis::maximum ( ) const

Returns the maximum value displayed on the axis.

This returned the maximum value that was set using setMaximum(), or otherwise the automatically calculated (and rounded) maximum.

The numerical value corresponding to a data point is defined by it's AxisScale type.

See also: setMaximum(), setAutoLimits(), setRoundLimits()

double Wt::Chart::WAxis::maxZoom ( ) const

Get the maximum zoom level for this axis.

Only applies to a WCartesianChart in interactive mode.

See also: setMaxZoom()

Deprecated:: Use minimumZoomRange() instead

double Wt::Chart::WAxis::minimum ( ) const

Returns the minimum value displayed on the axis.

This returned the minimum value that was set using setMinimum(), or otherwise the automatically calculated (and rounded) minimum.

The numerical value corresponding to a data point is defined by it's AxisScale type.

See also: setMinimum(), setAutoLimits(), setRoundLimits()

double Wt::Chart::WAxis::minimumZoomRange ( ) const

Get the minimum zoom range for this axis.

Only applies to a WCartesianChart in interactive mode.

See also: setMinimumZoomRange()

int Wt::Chart::WAxis::padding ( ) const

Returns the padding between the chart area and this axis.

See also: setPadding()

double Wt::Chart::WAxis::pan ( ) const

Get the value to pan to for this axis, when pan is enabled on the chart.

Only applies to a WCartesianChart in interactive mode.

See also: setPan()

Deprecated:: Use zoomMinimum() instead.

const WPen& Wt::Chart::WAxis::pen ( ) const

Returns the pen used for rendering the axis and ticks.

See also: setPen()

double Wt::Chart::WAxis::resolution ( ) const

Returns the axis resolution.

See also: setResolution()

WFlags<AxisValue> Wt::Chart::WAxis::roundLimits ( ) const

Returns whether limits should be rounded.

See also: setRoundLimits()

AxisScale Wt::Chart::WAxis::scale ( ) const

Returns the scale of the axis.

See also: setScale()

void Wt::Chart::WAxis::setAutoLimits ( WFlags< AxisValue > locations )

Let the minimum and/or maximum be calculated from the data.

Using this method, you can indicate that you want to have automatic limits, rather than limits set manually using setMinimum() or setMaximum().

locations can be Chart::MinimumValue and/or Chart::MaximumValue.

The default value is Chart::MinimumValue | Chart::MaximumValue.

void Wt::Chart::WAxis::setBreak	(	double	minimum,
		double	maximum
	)

Specifies a range that needs to be omitted from the axis.

This is useful to display data with a few outliers which would otherwise swamp the chart. This is not done automatically, but instead you need to use setBreak() to specify the value range that needs to be omitted from the axis. The omission is rendered in the axis and in BarSeries that cross the break.

Note: This feature is incompatible with the interactive features of WCartesianChart.

void Wt::Chart::WAxis::setGridLinesEnabled ( bool enabled )

Sets whether gridlines are displayed for this axis.

When enabled, gird lines are drawn for each tick on this axis, using the gridLinesPen().

Unlike all other visual aspects of an axis, rendering of the gridlines is not controlled by setDisplayEnabled().

See also: setGridLinesPen(), isGridLinesEnabled()

void Wt::Chart::WAxis::setGridLinesPen ( const WPen & pen )

Changes the pen used for rendering the grid lines.

The default value is a gray pen of 0 width.

See also: setPen(), gridLinesPen().

void Wt::Chart::WAxis::setInverted ( bool inverted = true )

Set whether this axis should be inverted.

When inverted, the axis will be drawn in the opposite direction, e.g. if normally, the low values are on the left and high values on the right, when inverted, the low values will be on the right and high values on the left.

void Wt::Chart::WAxis::setLabelAngle ( double angle )

Sets the label angle.

Sets the angle used for displaying the labels (in degrees). A 0 angle corresponds to horizontal text.

The default value is 0.0.

See also: labelAngle()

void Wt::Chart::WAxis::setLabelBasePoint ( double point )

Sets a point to be included as one of the labels (if possible).

The given point will be included as one of the labels, by adjusting the minimum value on the axis, if that minimum is auto-computed. This is only applicable to a Linear scale axis.

The default value is 0.0.

See also: setRoundLimits()

void Wt::Chart::WAxis::setLabelFont ( const WFont & labelFont )

Sets the axis label font.

The default label font is a 10 point Sans Serif font.

See also: labelFont()

void Wt::Chart::WAxis::setLabelFormat ( const WString & format )

Sets the label format.

Sets a format string which is used to format values, both for the axis labels as well as data series values (see WDataSeries::setLabelsEnabled()).

For an axis with a LinearScale or LogScale scale, the format string must be a format string that is accepted by snprintf() and which formats one double. If the format string is an empty string, then WLocale::toString() is used.

For an axis with a DateScale scale, the format string must be a format string accepted by WDate::toString(), to format a date. If the format string is an empty string, a suitable format is chosen based on heuristics.

For an axis with a DateTimeScale scale, the format string must be a format string accepted by WDateTime::toString(), to format a date. If the format string is an empty string, a suitable format is chosen based on heuristics.

The default value is "%.4g" for a numeric axis, and a suitable format for date(time) scales based on a heuristic taking into account the current axis range.

See also: labelFormat()

void Wt::Chart::WAxis::setLabelInterval ( double labelInterval )

Sets the label interval.

Specifies the interval for displaying labels (and ticks) on the axis. The default value is 0.0, and indicates that the interval should be computed automatically.

The unit for the label interval is in logical units (i.e. the same as minimum or maximum).

See also: setLabelFormat()

void Wt::Chart::WAxis::setLabelTransform	(	const LabelTransform &	transform,
		AxisValue	side
	)

Set the transform function to apply to a given side.

The label transform must be a function from double to double, and will be applied on the double value of the model coordinate of every axis tick.

The label transform will not move the position of the axis ticks, only change the labels displayed at the ticks.

This can be useful in combination with a location() set to BothSides, to show different labels on each side.

If DateScale or DateTimeScale are used, the double value will be in seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Only MinimumValue, ZeroValue and MaximumValue are accepted for side. If you set a label transform for another side, the label transform will not be used.

The label transform will not be used if the scale() is CategoryScale.

void Wt::Chart::WAxis::setLocation ( AxisValue value )

Sets the axis location.

Configures the location of the axis, relative to values on the other axis (i.e. Y values for the X axis, and X values for the Y axis).

The default value is Chart::MinimumValue.

See also: location()

void Wt::Chart::WAxis::setMargin ( int pixels )

Sets the margin between the axis and the plot area.

The margin is defined in pixels.

The default value is 0.

See also: margin()

void Wt::Chart::WAxis::setMaximum ( double maximum )

Sets the maximum value for the axis displayed on the axis.

By default, the minimum and maximum values are determined automatically so that all the data can be displayed.

The numerical value corresponding to a data point is defined by it's AxisScale type.

See also: setMinimum(), setAutoLimits()

void Wt::Chart::WAxis::setMaxZoom ( double maxZoom )

Sets the maximum zoom level for this axis.

Only applies to a WCartesianChart in interactive mode. The zoom level should be >= 1 (1 = no zoom).

Note: This is only implemented for the X and first Y axis. It has no effect on the second Y axis.

Deprecated:: Use setMinimumZoomRange(double) instead

void Wt::Chart::WAxis::setMinimum ( double minimum )

Sets the minimum value displayed on the axis.

By default, the minimum and maximum values are determined automatically so that all the data can be displayed.

The numerical value corresponding to a data point is defined by it's AxisScale type.

See also: setMaximum(), setAutoLimits()

void Wt::Chart::WAxis::setMinimumZoomRange ( double size )

Sets the minimum zoom range for this axis.

Only applies to a WCartesianChart in interactive mode.

This range is the smallest difference there can be between zoomMinimum() and zoomMaximum().

Note: This is only implemented for the X and first Y axis. It has no effect on the second Y axis.

void Wt::Chart::WAxis::setPadding ( int padding )

Sets the padding between the chart area and this axis.

See also: padding()

void Wt::Chart::WAxis::setPan ( double pan )

Sets the value to pan to for this axis.

This sets the leftmost (horizontal axis) or bottom (vertical axis) value to be displayed on the chart.

Note that if this would cause the chart to go out of bounds, the panning of the chart will be automatically adjusted.

Only applies to a WCartesianChart in interactive mode.

Note: This is only implemented for the X and first Y axis. It has no effect on the second Y axis.; If the pan position has been changed on the client side, this may not reflect the actual pan position.

Deprecated:: Use setZoomRange() instead.

void Wt::Chart::WAxis::setPen ( const WPen & pen )

Changes the pen used for rendering the axis and ticks.

The default value is a black pen of 0 width.

See also: setGridLinesPen().

void Wt::Chart::WAxis::setRange	(	double	minimum,
		double	maximum
	)

Sets the axis range (minimum and maximum values) manually.

Specifies both minimum and maximum value for the axis. This automatically disables automatic range calculation.

The numerical value corresponding to a data point is defined by it's AxisScale type.

See also: setMinimum(), setMaximum()

void Wt::Chart::WAxis::setResolution ( double resolution )

Sets the axis resolution.

Specifies the axis resolution, in case maximum-minimum < resolution minimum and maximum are modified so the maximum - minimum = resolution

The default resolution is 0, which uses a built-in epsilon.

See also: resolution()

void Wt::Chart::WAxis::setRoundLimits ( WFlags< AxisValue > locations )

Specifies whether limits should be rounded.

When enabling rounding, this has the effect of rounding down the minimum value, or rounding up the maximum value, to the nearest label interval.

By default, rounding is enabled for an auto-calculated limited, and disabled for a manually specifed limit.

See also: setAutoLimits()

void Wt::Chart::WAxis::setScale ( AxisScale scale )

Sets the scale of the axis.

For the X scale in a CategoryChart, the scale should be left unchanged to CategoryScale.

For all other axes, the default value is LinearScale, but this may be changed to LogScale or DateScale. DateScale is only useful for the X axis in a ScatterPlot which contains WDate values.

See also: scale()

void Wt::Chart::WAxis::setSoftLabelClipping ( bool enabled )

Enables soft clipping of axis labels.

This is set to false by for a 3D chart and to true for a 2D chart.

This setting determines how labels should be clipped in case not the entire axis is visible due to clipping. "Hard" clipping is done by the paint device and may truncate labels. "Soft" clipping will determine if the corresponding tick is visible, and draw the label (unclipped), preventing labels from being truncated. For a 2D chart, this feature is only relevant when zoom is enabled on a WCartesianChart.

Soft clipping enabled (slower).

This is the default for WCartesianChart. The tick for 0 is visible, and the 0 is shown completely. The tick for 01/01/86 is not visible, so its label is not shown.

Soft clipping disabled (faster).

The tick of the 0 is visible, but the 0 is shown partially. Also, the tick of 01/01/86 is not visible, but the label is partially shown.

void Wt::Chart::WAxis::setTextPen ( const WPen & pen )

Changes the pen used for rendering labels for this axis.

The default value is a black pen of 0 width.

See also: setGridLinesPen().; setPen().; WCartesianChart::setTextPen()

void Wt::Chart::WAxis::setTickDirection ( TickDirection direction )

Sets the direction that the axis ticks should point to.

If set to Outwards, the axis ticks will point outside of the chart, and the labels will be on the outside.

If set to Inwards, the axis ticks will point inside of the chart, and the labels will be on the inside. Also, the padding() will be set to 25.

See also: tickDirection(); setPadding()

void Wt::Chart::WAxis::setTitle ( const WString & title )

Sets the axis title.

The default title is empty.

See also: title()

void Wt::Chart::WAxis::setTitleFont ( const WFont & titleFont )

Sets the axis title font.

The default title font is a 12 point Sans Serif font.

See also: titleFont()

void Wt::Chart::WAxis::setTitleOrientation ( const Orientation & orientation )

Sets the title orientation.

Sets the orientation used for displaying the title.

The default value is Horizontal

See also: titleOrientation()

void Wt::Chart::WAxis::setVisible ( bool visible )

Sets whether this axis is visible.

Changes whether the axis is displayed, including ticks and labels. The rendering of the grid lines is controlled seperately by setGridLinesEnabled().

The default value is true for the X axis and first Y axis, but false for the second Y axis.

See also: setGridLinesEnabled().

void Wt::Chart::WAxis::setZoom ( double zoom )

Sets the zoom level for this axis.

Only applies to a WCartesianChart in interactive mode. The zoom level should be >= 1 and smaller than maxZoom()

Note: This is only implemented for the X and first Y axis. It has no effect on the second Y axis.

Deprecated:: Use setZoomRange() instead.

void Wt::Chart::WAxis::setZoomRange	(	double	minimum,
		double	maximum
	)

Set the range to zoom to on this axis.

The minimum is the lowest value to be displayed, and the maximum is the highest value to be displayed.

If the difference between minimum and maximum is less than minimumZoomRange(), the zoom range will be made more narrow around the center of minimum and maximum.

If the given minimum is larger than the given maximum, the two values are swapped.

Only applies to a WCartesianChart in interactive mode.