Wt  3.3.0
Public Member Functions | Protected Member Functions | Private Member Functions
Wt::Chart::WCartesianChart Class Reference

A cartesian chart. More...

#include <Wt/Chart/WCartesianChart>

Inheritance diagram for Wt::Chart::WCartesianChart:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 WCartesianChart (WContainerWidget *parent=0)
 Creates a new cartesian chart.
 WCartesianChart (ChartType type, WContainerWidget *parent=0)
 Creates a new cartesian chart.
void setType (ChartType type)
 Sets the chart type.
ChartType type () const
 Returns the chart type.
void setOrientation (Orientation orientation)
 Sets the chart orientation.
Orientation orientation () const
 Returns the chart orientation.
void setXSeriesColumn (int modelColumn)
 Sets the the model column for the X series.
int XSeriesColumn () const
 Returns the model column for the X series.
void addSeries (const WDataSeries &series)
 Adds a data series.
void removeSeries (int modelColumn)
 Removes a data series.
void setSeries (const std::vector< WDataSeries > &series)
 Sets all data series.
WDataSeriesseries (int modelColumn)
 Returns a data series corresponding to a data column.
const WDataSeriesseries (int modelColumn) const
 Returns a data series corresponding to a data column.
const std::vector< WDataSeries > & series () const
 Returns a list with the current data series.
WAxisaxis (Axis axis)
 Returns a chart axis.
const WAxisaxis (Axis axis) const
 Accesses a chart axis.
void setBarMargin (double margin)
 Sets the margin between bars of different series.
double barMargin () const
 Returns the margin between bars of different series.
void setLegendEnabled (bool enabled)
 Enables the legend.
bool isLegendEnabled () const
 Returns whether the legend is enabled.
void setLegendLocation (LegendLocation location, Side side, AlignmentFlag alignment)
 Configures the legend location.
void setLegendStyle (const WFont &font, const WPen &border, const WBrush &background)
 Configures the legend decoration.
LegendLocation legendLocation () const
 Returns the legend location.
Side legendSide () const
 Returns the legend side.
AlignmentFlag legendAlignment () const
 Returns the legend alignment.
int legendColumns () const
 Returns the legend columns.
WLength legendColumnWidth () const
 Returns the legend column width.
WFont legendFont () const
 Returns the legend font.
WPen legendBorder () const
 Returns the legend border pen.
WBrush legendBackground () const
 Returns the legend background brush.
void setLegendColumns (int columns, const WLength &width)
 Configures multiple legend columns.
virtual void paint (WPainter &painter, const WRectF &rectangle=WRectF()) const
 Paint the chart in a rectangle of the given painter.
virtual void drawMarker (const WDataSeries &series, WPainterPath &result) const
 Draws the marker for a given data series.
virtual void renderLegendIcon (WPainter &painter, const WPointF &pos, const WDataSeries &series) const
 Renders the legend icon for a given data series.
virtual void renderLegendItem (WPainter &painter, const WPointF &pos, const WDataSeries &series) const
 Renders the legend item for a given data series.
WPointF mapFromDevice (const WPointF &point, Axis ordinateAxis=OrdinateAxis) const
 Maps from device coordinates to model coordinates.
WPointF mapToDevice (const boost::any &xValue, const boost::any &yValue, Axis axis=OrdinateAxis, int xSegment=0, int ySegment=0) const
 Maps model values onto chart coordinates.
void initLayout (const WRectF &rectangle=WRectF())
 Initializes the chart layout.
WWidgetcreateLegendItemWidget (int index)
 Creates a widget which renders the a legend item.
virtual void addDataPointArea (const WDataSeries &series, const WModelIndex &xIndex, WAbstractArea *area)
 Adds a data point area (used for displaying e.g. tooltips).
void setAxisPadding (int axisPadding)
 Sets the padding between the chart area and the axes.
int axisPadding () const
 Returns the padding between the chart area and the axes.

Protected Member Functions

void paintEvent (WPaintDevice *paintDevice)
 Paints the widget.
virtual WChart2DRenderercreateRenderer (WPainter &painter, const WRectF &rectangle) const
 Creates a renderer which renders the chart.

Private Member Functions

virtual void modelColumnsInserted (const WModelIndex &parent, int start, int end)
 Method called when colums have been inserted in the model.
virtual void modelColumnsRemoved (const WModelIndex &parent, int start, int end)
 Method called when colums have been removed from the model.
virtual void modelRowsInserted (const WModelIndex &parent, int start, int end)
 Method called when rows have been inserted from the model.
virtual void modelRowsRemoved (const WModelIndex &parent, int start, int end)
 Method called when rows have been removed from the model.
virtual void modelDataChanged (const WModelIndex &topLeft, const WModelIndex &bottomRight)
 Method called when data has been changed in the model.
virtual void modelChanged ()
 Method called whenever the entire model was changed.
virtual void modelReset ()
 Method called whenever the entire model was reset.

Detailed Description

A cartesian chart.

A cartesian chart is a chart that uses X and Y axes. It can display one or multiple data series, which each may be rendered using bars, lines, areas, or points.

To use a cartesian chart, the minimum you need to do is set a model using setModel(), set the model column that holds the X data using setXSeriesColumn(int modelColumn), and add one or more series using addSeries(const WDataSeries&). Each series corresponds to one data column that holds Y data.

A cartesian chart is either a CategoryChart or a ScatterPlot.

In a CategoryChart, the X series represent different categories, which are listed consecutively in model row order. The X axis scale is set to CategoryScale.

ChartWCartesianChart-1.png
A category chart with bar series

Each series may be rendered differently, and this is configured in the data series (see WDataSeries for more information).

In a ScatterPlot, the X series data are interpreted as numbers on a numerical scale. The scale for the X axis defaults to a LinearScale, but this may be changed to a DateScale when the X series contains dates (of type WDate) to create a time series chart, or to a LogScale. A ScatterPlot supports the same types of data series as a CategoryChart, but does not support stacking. In a scatter plot, the X series do not need to be ordered in increasing values, and may be set differently for each dataseries using WDataSeries::setXSeriesColumn(int modelColumn).

ChartWCartesianChart-2.png
A time series scatter plot with line series

Missing data in a model series Y values is interpreted as a break. For curve-like series, this breaks the curve (or line).

The cartesian chart has support for dual Y axes. Each data series may be bound to one of the two Y axes. By default, only the first Y axis is displayed. To show the second Y axis you will need to call:

 chart->axis(Y2Axis).setVisible(true);

By default a chart has a horizontal X axis and a vertical Y axis, which corresponds to a Vertical orientation. The orientation may be changed to Horizontal using setOrientation().

The styling of the series data are dictated by a palette which may be set using setPalette(WChartPalette *), but may be overridden by settings in each data series.

CSS

Styling through CSS is not applicable.

See also:
WDataSeries, WAxis
WPieChart

Constructor & Destructor Documentation

Wt::Chart::WCartesianChart::WCartesianChart ( WContainerWidget parent = 0)

Creates a new cartesian chart.

Creates a cartesian chart of type CategoryChart.

Wt::Chart::WCartesianChart::WCartesianChart ( ChartType  type,
WContainerWidget parent = 0 
)

Creates a new cartesian chart.

Creates a cartesian chart of the indicated type.


Member Function Documentation

void Wt::Chart::WCartesianChart::addDataPointArea ( const WDataSeries series,
const WModelIndex xIndex,
WAbstractArea area 
) [virtual]

Adds a data point area (used for displaying e.g. tooltips).

You may want to specialize this is if you wish to modify (or delete) the area.

Note:
Currently, an area is only created if the Wt::ToolTipRole data at the data point is not empty.
void Wt::Chart::WCartesianChart::addSeries ( const WDataSeries series)

Adds a data series.

A single chart may display one or more data series. Each data series displays data from a single model column in the chart. Series are plotted in the order that they have been added to the chart.

The series column is reset to -1 when the model is set (or changed). Thus you need to set a model before configuring the series.

See also:
removeSeries(), setSeries()
WAxis & Wt::Chart::WCartesianChart::axis ( Axis  axis)

Returns a chart axis.

Returns a reference to the specified axis.

const WAxis & Wt::Chart::WCartesianChart::axis ( Axis  axis) const

Accesses a chart axis.

Returns a const reference to the specified axis.

int Wt::Chart::WCartesianChart::axisPadding ( ) const

Returns the padding between the chart area and the axes.

See also:
setAxisPadding()
double Wt::Chart::WCartesianChart::barMargin ( ) const

Returns the margin between bars of different series.

See also:
setBarMargin(double)
WWidget * Wt::Chart::WCartesianChart::createLegendItemWidget ( int  index)

Creates a widget which renders the a legend item.

The legend item widget will contain a text and a WPaintedWidget which draws the series' symbol.

WChart2DRenderer * Wt::Chart::WCartesianChart::createRenderer ( WPainter painter,
const WRectF rectangle 
) const [protected, virtual]

Creates a renderer which renders the chart.

The rendering of the chart is delegated to a WChart2DRenderer class, which will render the chart within the rectangle of the painter.

You may want to reimplement this method if you wish to override one or more aspects of the rendering, by returning an new instance of a specialized WChart2DRenderer class.

After rendering, the renderer is deleted.

See also:
WChart2DRenderer::render()
void Wt::Chart::WCartesianChart::drawMarker ( const WDataSeries series,
WPainterPath result 
) const [virtual]

Draws the marker for a given data series.

Draws the marker for the indicated series in the result. This method is called while painting the chart, and you may want to reimplement this method if you wish to provide a custom marker for a particular data series.

See also:
setLegendEnabled()
void Wt::Chart::WCartesianChart::initLayout ( const WRectF rectangle = WRectF())

Initializes the chart layout.

A cartesian chart delegates the rendering and layout of the chart and its axes to a WChart2DRenderer. As a consequence, the mapping between model and device coordinates is also established by this class, which is only created on-demand when painging.

If you wish to establish the layout, in order to use the mapFromDevice() and mapToDevice() methods before the chart has been rendered, you should call this method.

Unless a specific chart rectangle is specified, the entire widget area is assumed.

bool Wt::Chart::WCartesianChart::isLegendEnabled ( ) const

Returns whether the legend is enabled.

See also:
setLegendEnabled()
AlignmentFlag Wt::Chart::WCartesianChart::legendAlignment ( ) const

Returns the legend alignment.

See also:
setLegendLocation()
WBrush Wt::Chart::WCartesianChart::legendBackground ( ) const

Returns the legend background brush.

See also:
setLegendStyle()
WPen Wt::Chart::WCartesianChart::legendBorder ( ) const

Returns the legend border pen.

See also:
setLegendStyle()
int Wt::Chart::WCartesianChart::legendColumns ( ) const

Returns the legend columns.

See also:
setLegendColumns()
WLength Wt::Chart::WCartesianChart::legendColumnWidth ( ) const

Returns the legend column width.

See also:
setLegendColumns()
WFont Wt::Chart::WCartesianChart::legendFont ( ) const

Returns the legend font.

See also:
setLegendStyle()
LegendLocation Wt::Chart::WCartesianChart::legendLocation ( ) const

Returns the legend location.

See also:
setLegendLocation()
Side Wt::Chart::WCartesianChart::legendSide ( ) const

Returns the legend side.

See also:
setLegendLocation()
WPointF Wt::Chart::WCartesianChart::mapFromDevice ( const WPointF point,
Axis  ordinateAxis = OrdinateAxis 
) const

Maps from device coordinates to model coordinates.

Maps a position in the chart back to model coordinates.

This uses the axis dimensions that are based on the latest chart rendering. If you have not yet rendered the chart, or wish to already the mapping reflect model changes since the last rendering, you should call initLayout() first.

See also:
mapToDevice()
WPointF Wt::Chart::WCartesianChart::mapToDevice ( const boost::any &  xValue,
const boost::any &  yValue,
Axis  axis = OrdinateAxis,
int  xSegment = 0,
int  ySegment = 0 
) const

Maps model values onto chart coordinates.

This returns the chart device coordinates for a (x,y) pair of model values.

This uses the axis dimensions that are based on the latest chart rendering. If you have not yet rendered the chart, or wish to already the mapping reflect model changes since the last rendering, you should call initLayout() first.

The xSegment and ySegment arguments are relevant only when the corresponding axis is broken using WAxis::setBreak(). Then, its possible values may be 0 (below the break) or 1 (above the break).

See also:
mapFromDevice()
void Wt::Chart::WCartesianChart::modelChanged ( ) [private, virtual]

Method called whenever the entire model was changed.

See also:
setModel(WAbstractItemModel *)

Reimplemented from Wt::Chart::WAbstractChart.

void Wt::Chart::WCartesianChart::modelColumnsInserted ( const WModelIndex parent,
int  start,
int  end 
) [private, virtual]

Method called when colums have been inserted in the model.

See also:
WAbstractItemModel::columnsInserted

Implements Wt::Chart::WAbstractChart.

void Wt::Chart::WCartesianChart::modelColumnsRemoved ( const WModelIndex parent,
int  start,
int  end 
) [private, virtual]

Method called when colums have been removed from the model.

See also:
WAbstractItemModel::columnsRemoved

Implements Wt::Chart::WAbstractChart.

void Wt::Chart::WCartesianChart::modelDataChanged ( const WModelIndex topLeft,
const WModelIndex bottomRight 
) [private, virtual]

Method called when data has been changed in the model.

See also:
WAbstractItemModel::dataChanged

Implements Wt::Chart::WAbstractChart.

void Wt::Chart::WCartesianChart::modelReset ( ) [private, virtual]

Method called whenever the entire model was reset.

Bound to the WAbstractItemModel::modelReset() and WAbstractItemModel::layoutChanged() signals.

Reimplemented from Wt::Chart::WAbstractChart.

void Wt::Chart::WCartesianChart::modelRowsInserted ( const WModelIndex parent,
int  start,
int  end 
) [private, virtual]

Method called when rows have been inserted from the model.

See also:
WAbstractItemModel::rowsInserted

Implements Wt::Chart::WAbstractChart.

void Wt::Chart::WCartesianChart::modelRowsRemoved ( const WModelIndex parent,
int  start,
int  end 
) [private, virtual]

Method called when rows have been removed from the model.

See also:
WAbstractItemModel::rowsRemoved

Implements Wt::Chart::WAbstractChart.

Orientation Wt::Chart::WCartesianChart::orientation ( ) const

Returns the chart orientation.

See also:
setOrientation()
void Wt::Chart::WCartesianChart::paint ( WPainter painter,
const WRectF rectangle = WRectF() 
) const [virtual]

Paint the chart in a rectangle of the given painter.

Paints the chart inside the painter, in the area indicated by rectangle. When rectangle is a null rectangle, the entire painter window is used.

Implements Wt::Chart::WAbstractChart.

void Wt::Chart::WCartesianChart::paintEvent ( WPaintDevice paintDevice) [protected, virtual]

Paints the widget.

You should reimplement this method to paint the contents of the widget, using the given paintDevice.

Implements Wt::WPaintedWidget.

void Wt::Chart::WCartesianChart::removeSeries ( int  modelColumn)

Removes a data series.

This removes the first data series which plots the given modelColumn.

See also:
addSeries(), setSeries()
void Wt::Chart::WCartesianChart::renderLegendIcon ( WPainter painter,
const WPointF pos,
const WDataSeries series 
) const [virtual]

Renders the legend icon for a given data series.

Renders the legend icon for the indicated series in the painter at position pos.

This method is called while rendering a legend item, and you may want to reimplement this method if you wish to provide a custom legend icon for a particular data series.

See also:
renderLegendItem()
void Wt::Chart::WCartesianChart::renderLegendItem ( WPainter painter,
const WPointF pos,
const WDataSeries series 
) const [virtual]

Renders the legend item for a given data series.

Renders the legend item for the indicated series in the painter at position pos. The default implementation draws the marker, and the series description to the right. The series description is taken from the model's header data for that series' data column.

This method is called while painting the chart, and you may want to reimplement this method if you wish to provide a custom marker for a particular data series.

See also:
setLegendEnabled()
WDataSeries & Wt::Chart::WCartesianChart::series ( int  modelColumn)

Returns a data series corresponding to a data column.

Returns a reference to the first data series that plots data from modelColumn.

const WDataSeries & Wt::Chart::WCartesianChart::series ( int  modelColumn) const

Returns a data series corresponding to a data column.

Returns a const reference to the first data series that plots data from modelColumn.

const std::vector<WDataSeries>& Wt::Chart::WCartesianChart::series ( ) const

Returns a list with the current data series.

Returns the complete list of current data series.

See also:
setSeries(const std::vector<WDataSeries>&)
void Wt::Chart::WCartesianChart::setAxisPadding ( int  axisPadding)

Sets the padding between the chart area and the axes.

See also:
axisPadding()
void Wt::Chart::WCartesianChart::setBarMargin ( double  margin)

Sets the margin between bars of different series.

Use this method to change the margin that is set between bars of different series. The margin is specified as a fraction of the width. For example, a value of 0.1 adds a 10% margin between bars of each series. Negative values are also allowed. For example, use a margin of -1 to plot the bars of different series on top of each other.

The default value is 0.

void Wt::Chart::WCartesianChart::setLegendColumns ( int  columns,
const WLength width 
)

Configures multiple legend columns.

Multiple columns are typically useful when placing the legend at the top or at the bottom of the chart.

The default value is a single column, 100 pixels wide.

void Wt::Chart::WCartesianChart::setLegendEnabled ( bool  enabled)

Enables the legend.

The location of the legend can be configured using setLegendLocation(). Only series for which the legend is enabled or included in this legend.

The default value is false.

See also:
see WDataSeries::isLegendEnabled(), setLegendLocation()
void Wt::Chart::WCartesianChart::setLegendLocation ( LegendLocation  location,
Side  side,
AlignmentFlag  alignment 
)

Configures the legend location.

The legend can be renderd either inside or outside of the chart area. When location is Chart::LegendInside, the legend will be rendered inside the chart. When location is Chart::Legendoutside, the legend is rendered outside the chart, in the chart padding area.

The provided side can either be Wt::Left, Wt::Right, Wt::Top, Wt::Bottom and configures the side of the chart at which the legend is displayed.

The alignment specifies how the legend is aligned. This can be a horizontal alignment flag (Wt::AlignLeft, Wt::AlignCenter, or Wt::AlignRight), when the side is Bottom or Top, or a vertical alignment flag (Wt::AlignTop, Wt::AlignMiddle, or Wt::AlignBottom) when the side is Left or Right.

The default location is Chart::LegendOutside, Wt::Right and Wt::AlignMiddle.

To have more control over the legend, you could reimplement the renderLegendItem() method to customize how one item in the legend is rendered, or, alternatively you can disable the legend generated by the chart itself, and reimplement the paint() method in which you use the renderLegendItem() method repeatedly to render a customized legend.

See also:
WDataSeries::setLegendEnabled()
void Wt::Chart::WCartesianChart::setLegendStyle ( const WFont font,
const WPen border,
const WBrush background 
)

Configures the legend decoration.

This configures the font, border and background for the legend.

The default font is a 10pt sans serif font (the same as the default axis label font), the default border is NoPen and the default background is NoBrush.

See also:
setLegendEnabled()
void Wt::Chart::WCartesianChart::setOrientation ( Orientation  orientation)

Sets the chart orientation.

Sets the chart orientation, which corresponds to the orientation of the Y axis: a Wt::Vertical orientation corresponds to the conventional way of a horizontal X axis and vertical Y axis. A Wt::Horizontal orientation is the other way around.

The default orientation is Wt::Vertical.

See also:
orientation()
void Wt::Chart::WCartesianChart::setSeries ( const std::vector< WDataSeries > &  series)

Sets all data series.

Replaces the current list of series with the new list.

See also:
series(), addSeries(), removeSeries()
void Wt::Chart::WCartesianChart::setType ( ChartType  type)

Sets the chart type.

The chart type determines how (x,y) data are interpreted. In a CategoryChart, the X values are categories, and these are plotted consecutively, evenly spaced, and in row order. In a ScatterPlot, the X values are interpreted numerically (as for Y values).

The default chart type is a CategoryChart.

See also:
type()
WAxis::setScale(), axis(Axis)
void Wt::Chart::WCartesianChart::setXSeriesColumn ( int  modelColumn)

Sets the the model column for the X series.

Use this method to specify the default data for the X series. For a ScatterPlot this is mandatory if an X series is not specified for every WDataSeries. For a CategoryChart, if not specified, an increasing series of integer numbers will be used (1, 2, ...).

Scatterplot dataseries may each individually be given its own X series data using WDataSeries::setXSeriesColumn(int modelColumn)

The default value is -1 (not specified).

The series column is reset to -1 when the model is set (or changed). Thus you need to set a model before configuring the series.

See also:
XSeriesColumn()
ChartType Wt::Chart::WCartesianChart::type ( ) const

Returns the chart type.

See also:
setType()
int Wt::Chart::WCartesianChart::XSeriesColumn ( ) const

Returns the model column for the X series.

See also:
setXSeriesColumn()
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator

Generated on Mon Apr 8 2013 for the C++ Web Toolkit (Wt) by doxygen 1.7.5.1