Qwt User's Guide: QwtPlotItem Class Reference

Qwt User's Guide 6.1.5

Public Types | Public Member Functions | Protected Member Functions | List of all members
QwtPlotItem Class Referenceabstract

Base class for items on the plot canvas. More...

`#include <qwt_plot_item.h>`

Inheritance diagram for QwtPlotItem:
[legend]

## Public Types
enum | RttiValues { Rtti_PlotItem = 0, Rtti_PlotGrid, Rtti_PlotScale, Rtti_PlotLegend, Rtti_PlotMarker, Rtti_PlotCurve, Rtti_PlotSpectroCurve, Rtti_PlotIntervalCurve, Rtti_PlotHistogram, Rtti_PlotSpectrogram, Rtti_PlotSVG, Rtti_PlotTradingCurve, Rtti_PlotBarChart, Rtti_PlotMultiBarChart, Rtti_PlotShape, Rtti_PlotTextLabel, Rtti_PlotZone, Rtti_PlotUserItem = 1000 }
| Runtime type information. More...
enum | ItemAttribute { Legend = 0x01, AutoScale = 0x02, Margins = 0x04 }
| Plot Item Attributes. More...
enum | ItemInterest { ScaleInterest = 0x01, LegendInterest = 0x02 }
| Plot Item Interests. More...
enum | RenderHint { RenderAntialiased = 0x1 }
| Render hints. More...
typedef QFlags< ItemAttribute > | ItemAttributes
| Plot Item Attributes.
typedef QFlags< ItemInterest > | ItemInterests
| Plot Item Interests.
typedef QFlags< RenderHint > | RenderHints
| Render hints.

## Public Member Functions
| QwtPlotItem (const QwtText &title=QwtText())
virtual | ~QwtPlotItem ()
| Destroy the QwtPlotItem.
void | attach (QwtPlot *plot)
| Attach the item to a plot. More...
void | detach ()
| This method detaches a QwtPlotItem from any QwtPlot it has been associated with. More...
QwtPlot * | plot () const
| Return attached plot.
void | setTitle (const QString &title)
void | setTitle (const QwtText &title)
const QwtText & | title () const
virtual int | rtti () const
void | setItemAttribute (ItemAttribute, bool on=true)
bool | testItemAttribute (ItemAttribute) const
void | setItemInterest (ItemInterest, bool on=true)
bool | testItemInterest (ItemInterest) const
void | setRenderHint (RenderHint, bool on=true)
bool | testRenderHint (RenderHint) const
void | setRenderThreadCount (uint numThreads)
uint | renderThreadCount () const
void | setLegendIconSize (const QSize &)
QSize | legendIconSize () const
double | z () const
void | setZ (double z)
| Set the z value. More...
void | show ()
| Show the item.
void | hide ()
| Hide the item.
virtual void | setVisible (bool)
bool | isVisible () const
void | setAxes (int xAxis, int yAxis)
void | setXAxis (int axis)
int | xAxis () const
| Return xAxis.
void | setYAxis (int axis)
int | yAxis () const
| Return yAxis.
virtual void | itemChanged ()
virtual void | legendChanged ()
virtual void | draw (QPainter *painter, const QwtScaleMap &xMap, const QwtScaleMap &yMap, const QRectF &canvasRect) const =0
| Draw the item. More...
virtual QRectF | boundingRect () const
virtual void | getCanvasMarginHint (const QwtScaleMap &xMap, const QwtScaleMap &yMap, const QRectF &canvasRect, double &left, double &top, double &right, double &bottom) const
| Calculate a hint for the canvas margin. More...
virtual void | updateScaleDiv (const QwtScaleDiv &, const QwtScaleDiv &)
| Update the item to changes of the axes scale division. More...
virtual void | updateLegend (const QwtPlotItem *, const QList< QwtLegendData > &)
| Update the item to changes of the legend info. More...
QRectF | scaleRect (const QwtScaleMap &, const QwtScaleMap &) const
| Calculate the bounding scale rectangle of 2 maps. More...
QRectF | paintRect (const QwtScaleMap &, const QwtScaleMap &) const
| Calculate the bounding paint rectangle of 2 maps. More...
virtual QList< QwtLegendData > | legendData () const
| Return all information, that is needed to represent the item on the legend. More...
virtual QwtGraphic | legendIcon (int index, const QSizeF &) const

## Protected Member Functions
QwtGraphic | defaultIcon (const QBrush &, const QSizeF &) const
| Return a default icon from a brush. More...

## Detailed Description

Base class for items on the plot canvas.

A plot item is "something", that can be painted on the plot canvas, or only affects the scales of the plot widget. They can be categorized as:

- Representator
  A "Representator" is an item that represents some sort of data on the plot canvas. The different representator classes are organized according to the characteristics of the data:
  - QwtPlotMarker Represents a point or a horizontal/vertical coordinate
  - QwtPlotCurve Represents a series of points
  - QwtPlotSpectrogram ( QwtPlotRasterItem ) Represents raster data
  - ...
- Decorators
  A "Decorator" is an item, that displays additional information, that is not related to any data:
  - QwtPlotGrid
  - QwtPlotScaleItem
  - QwtPlotSvgItem
  - ...

Depending on the QwtPlotItem::ItemAttribute flags, an item is included into autoscaling or has an entry on the legend.

Before misusing the existing item classes it might be better to implement a new type of plot item ( don't implement a watermark as spectrogram ). Deriving a new type of QwtPlotItem primarily means to implement the YourPlotItem::draw() method.

See also
  The cpuplot example shows the implementation of additional plot items.

## Member Enumeration Documentation

## ◆ ItemAttribute

enum QwtPlotItem::ItemAttribute

Plot Item Attributes.

Various aspects of a plot widget depend on the attributes of the attached plot items. If and how a single plot item participates in these updates depends on its attributes.

See also
  setItemAttribute(), testItemAttribute(), ItemInterest

Enumerator
Legend | The item is represented on the legend.
AutoScale | The boundingRect() of the item is included in the autoscaling calculation as long as its width or height is >= 0.0.
Margins | The item needs extra space to display something outside its bounding rectangle. See also getCanvasMarginHint()

## ◆ ItemInterest

enum QwtPlotItem::ItemInterest

Plot Item Interests.

Plot items might depend on the situation of the corresponding plot widget. By enabling an interest the plot item will be notified, when the corresponding attribute of the plot widgets has changed.

See also
  setItemAttribute(), testItemAttribute(), ItemInterest

Enumerator
ScaleInterest | The item is interested in updates of the scales See also updateScaleDiv()
LegendInterest | The item is interested in updates of the legend ( of other items ) This flag is intended for items, that want to implement a legend for displaying entries of other plot item. Note If the plot item wants to be represented on a legend enable QwtPlotItem::Legend instead. See also updateLegend()

## ◆ RenderHint

enum QwtPlotItem::RenderHint

Render hints.

Enumerator
RenderAntialiased | Enable antialiasing.

## ◆ RttiValues

enum QwtPlotItem::RttiValues

Runtime type information.

RttiValues is used to cast plot items, without having to enable runtime type information of the compiler.

Enumerator
Rtti_PlotItem | Unspecific value, that can be used, when it doesn't matter.
Rtti_PlotGrid | For QwtPlotGrid.
Rtti_PlotScale | For QwtPlotScaleItem.
Rtti_PlotLegend | For QwtPlotLegendItem.
Rtti_PlotMarker | For QwtPlotMarker.
Rtti_PlotCurve | For QwtPlotCurve.
Rtti_PlotSpectroCurve | For QwtPlotSpectroCurve.
Rtti_PlotIntervalCurve | For QwtPlotIntervalCurve.
Rtti_PlotHistogram | For QwtPlotHistogram.
Rtti_PlotSpectrogram | For QwtPlotSpectrogram.
Rtti_PlotSVG | For QwtPlotSvgItem.
Rtti_PlotTradingCurve | For QwtPlotTradingCurve.
Rtti_PlotBarChart | For QwtPlotBarChart.
Rtti_PlotMultiBarChart | For QwtPlotMultiBarChart.
Rtti_PlotShape | For QwtPlotShapeItem.
Rtti_PlotTextLabel | For QwtPlotTextLabel.
Rtti_PlotZone | For QwtPlotZoneItem.
Rtti_PlotUserItem | Values >= Rtti_PlotUserItem are reserved for plot items not implemented in the Qwt library.

## Constructor & Destructor Documentation

## ◆ QwtPlotItem()

QwtPlotItem::QwtPlotItem | ( | const QwtText & | title = `QwtText()` | ) |
| explicit

Constructor

Parameters

  title | Title of the item

## Member Function Documentation

## ◆ attach()

void QwtPlotItem::attach | ( | QwtPlot * | plot | ) |

Attach the item to a plot.

This method will attach a QwtPlotItem to the QwtPlot argument. It will first detach the QwtPlotItem from any plot from a previous call to attach (if necessary). If a NULL argument is passed, it will detach from any QwtPlot it was attached to.

Parameters

  plot | Plot widget

See also
  detach()

## ◆ boundingRect()

QRectF QwtPlotItem::boundingRect | ( |  | ) | const
| virtual

Returns
  An invalid bounding rect: QRectF(1.0, 1.0, -2.0, -2.0)

Note
  A width or height < 0.0 is ignored by the autoscaler

Reimplemented in QwtPlotTradingCurve, QwtPlotMarker, QwtPlotIntervalCurve, QwtPlotHistogram, QwtPlotRasterItem, QwtPlotShapeItem, QwtPlotBarChart, QwtPlotMultiBarChart, QwtPlotZoneItem, QwtPlotSeriesItem, and QwtPlotSvgItem.

## ◆ defaultIcon()

QwtGraphic QwtPlotItem::defaultIcon | ( | const QBrush & | brush,
|  | const QSizeF & | size
| ) |  | const
| protected

Return a default icon from a brush.

The default icon is a filled rectangle used in several derived classes as legendIcon().

Parameters

  brush | Fill brush
  size | Icon size

Returns
  A filled rectangle

## ◆ detach()

void QwtPlotItem::detach | ( |  | ) |

This method detaches a QwtPlotItem from any QwtPlot it has been associated with.

detach() is equivalent to calling attach( NULL )

See also
  attach()

## ◆ draw()

virtual void QwtPlotItem::draw | ( | QPainter * | painter,
|  | const QwtScaleMap & | xMap,
|  | const QwtScaleMap & | yMap,
|  | const QRectF & | canvasRect
| ) |  | const
| pure virtual

Draw the item.

Parameters

  painter | Painter
  xMap | Maps x-values into pixel coordinates.
  yMap | Maps y-values into pixel coordinates.
  canvasRect | Contents rect of the canvas in painter coordinates

Implemented in QwtPlotLegendItem, QwtPlotRasterItem, QwtPlotShapeItem, QwtPlotSpectrogram, QwtPlotScaleItem, QwtPlotGrid, QwtPlotSvgItem, QwtPlotMarker, QwtPlotSeriesItem, QwtPlotTextLabel, and QwtPlotZoneItem.

## ◆ getCanvasMarginHint()

void QwtPlotItem::getCanvasMarginHint | ( | const QwtScaleMap & | xMap,
|  | const QwtScaleMap & | yMap,
|  | const QRectF & | canvasRect,
|  | double & | left,
|  | double & | top,
|  | double & | right,
|  | double & | bottom
| ) |  | const
| virtual

Calculate a hint for the canvas margin.

When the QwtPlotItem::Margins flag is enabled the plot item indicates, that it needs some margins at the borders of the canvas. This is f.e. used by bar charts to reserve space for displaying the bars.

The margins are in target device coordinates ( pixels on screen )

Parameters

  xMap | Maps x-values into pixel coordinates.
  yMap | Maps y-values into pixel coordinates.
  canvasRect | Contents rectangle of the canvas in painter coordinates
  left | Returns the left margin
  top | Returns the top margin
  right | Returns the right margin
  bottom | Returns the bottom margin

The default implementation returns 0 for all margins

See also
  QwtPlot::getCanvasMarginsHint(), QwtPlot::updateCanvasMargins()

Reimplemented in QwtPlotAbstractBarChart.

## ◆ isVisible()

bool QwtPlotItem::isVisible | ( |  | ) | const

Returns
  true if visible

See also
  setVisible(), show(), hide()

## ◆ itemChanged()

void QwtPlotItem::itemChanged | ( |  | ) |
| virtual

Update the legend and call QwtPlot::autoRefresh() for the parent plot.

See also
  QwtPlot::legendChanged(), QwtPlot::autoRefresh()

## ◆ legendChanged()

void QwtPlotItem::legendChanged | ( |  | ) |
| virtual

Update the legend of the parent plot.

See also
  QwtPlot::updateLegend(), itemChanged()

## ◆ legendData()

QList< QwtLegendData > QwtPlotItem::legendData | ( |  | ) | const
| virtual

Return all information, that is needed to represent the item on the legend.

Most items are represented by one entry on the legend showing an icon and a text, but f.e. QwtPlotMultiBarChart displays one entry for each bar.

QwtLegendData is basically a list of QVariants that makes it possible to overload and reimplement legendData() to return almost any type of information, that is understood by the receiver that acts as the legend.

The default implementation returns one entry with the title() of the item and the legendIcon().

Returns
  Data, that is needed to represent the item on the legend

See also
  title(), legendIcon(), QwtLegend, QwtPlotLegendItem

Reimplemented in QwtPlotBarChart, and QwtPlotMultiBarChart.

## ◆ legendIcon()

QwtGraphic QwtPlotItem::legendIcon | ( | int | index,
|  | const QSizeF & | size
| ) |  | const
| virtual

Returns
  Icon representing the item on the legend

The default implementation returns an invalid icon

Parameters

  index | Index of the legend entry ( usually there is only one )
  size | Icon size

See also
  setLegendIconSize(), legendData()

Reimplemented in QwtPlotCurve, QwtPlotTradingCurve, QwtPlotMarker, QwtPlotIntervalCurve, QwtPlotHistogram, QwtPlotBarChart, QwtPlotShapeItem, and QwtPlotMultiBarChart.

## ◆ legendIconSize()

QSize QwtPlotItem::legendIconSize | ( |  | ) | const

Returns
  Legend icon size

See also
  setLegendIconSize(), legendIcon()

## ◆ paintRect()

QRectF QwtPlotItem::paintRect | ( | const QwtScaleMap & | xMap,
|  | const QwtScaleMap & | yMap
| ) |  | const

Calculate the bounding paint rectangle of 2 maps.

Parameters

  xMap | Maps x-values into pixel coordinates.
  yMap | Maps y-values into pixel coordinates.

Returns
  Bounding paint rectangle of the scale maps, not normalized

## ◆ renderThreadCount()

uint QwtPlotItem::renderThreadCount | ( |  | ) | const

Returns
  Number of threads to be used for rendering. If numThreads() is set to 0, the system specific ideal thread count is used.

## ◆ rtti()

int QwtPlotItem::rtti | ( |  | ) | const
| virtual

Return rtti for the specific class represented. QwtPlotItem is simply a virtual interface class, and base classes will implement this method with specific rtti values so a user can differentiate them.

The rtti value is useful for environments, where the runtime type information is disabled and it is not possible to do a dynamic_cast<...>.

Returns
  rtti value

See also
  RttiValues

Reimplemented in QwtPlotCurve, QwtPlotTradingCurve, QwtPlotShapeItem, QwtPlotSpectrogram, QwtPlotIntervalCurve, QwtPlotHistogram, QwtPlotMarker, QwtPlotBarChart, QwtPlotMultiBarChart, QwtPlotLegendItem, QwtPlotScaleItem, QwtPlotTextLabel, QwtPlotSpectroCurve, QwtPlotSvgItem, QwtPlotGrid, and QwtPlotZoneItem.

## ◆ scaleRect()

QRectF QwtPlotItem::scaleRect | ( | const QwtScaleMap & | xMap,
|  | const QwtScaleMap & | yMap
| ) |  | const

Calculate the bounding scale rectangle of 2 maps.

Parameters

  xMap | Maps x-values into pixel coordinates.
  yMap | Maps y-values into pixel coordinates.

Returns
  Bounding scale rect of the scale maps, not normalized

## ◆ setAxes()

void QwtPlotItem::setAxes | ( | int | xAxis,
|  | int | yAxis
| ) |  |

Set X and Y axis

The item will painted according to the coordinates of its Axes.

Parameters

  xAxis | X Axis ( QwtPlot::xBottom or QwtPlot::xTop )
  yAxis | Y Axis ( QwtPlot::yLeft or QwtPlot::yRight )

See also
  setXAxis(), setYAxis(), xAxis(), yAxis(), QwtPlot::Axis

## ◆ setItemAttribute()

void QwtPlotItem::setItemAttribute | ( | ItemAttribute | attribute,
|  | bool | on = `true`
| ) |  |

Toggle an item attribute

Parameters

  attribute | Attribute type
  on | true/false

See also
  testItemAttribute(), ItemInterest

## ◆ setItemInterest()

void QwtPlotItem::setItemInterest | ( | ItemInterest | interest,
|  | bool | on = `true`
| ) |  |

Toggle an item interest

Parameters

  interest | Interest type
  on | true/false

See also
  testItemInterest(), ItemAttribute

## ◆ setLegendIconSize()

void QwtPlotItem::setLegendIconSize | ( | const QSize & | size | ) |

Set the size of the legend icon

The default setting is 8x8 pixels

Parameters

  size | Size

See also
  legendIconSize(), legendIcon()

## ◆ setRenderHint()

void QwtPlotItem::setRenderHint | ( | RenderHint | hint,
|  | bool | on = `true`
| ) |  |

Toggle an render hint

Parameters

  hint | Render hint
  on | true/false

See also
  testRenderHint(), RenderHint

## ◆ setRenderThreadCount()

void QwtPlotItem::setRenderThreadCount | ( | uint | numThreads | ) |

On multi core systems rendering of certain plot item ( f.e QwtPlotRasterItem ) can be done in parallel in several threads.

The default setting is set to 1.

Parameters

  numThreads | Number of threads to be used for rendering. If numThreads is set to 0, the system specific ideal thread count is used.

The default thread count is 1 ( = no additional threads )

## ◆ setTitle() [1/2]

void QwtPlotItem::setTitle | ( | const QString & | title | ) |

Set a new title

Parameters

  title | Title

See also
  title()

## ◆ setTitle() [2/2]

void QwtPlotItem::setTitle | ( | const QwtText & | title | ) |

Set a new title

Parameters

  title | Title

See also
  title()

## ◆ setVisible()

void QwtPlotItem::setVisible | ( | bool | on | ) |
| virtual

Show/Hide the item

Parameters

  on | Show if true, otherwise hide

See also
  isVisible(), show(), hide()

## ◆ setXAxis()

void QwtPlotItem::setXAxis | ( | int | axis | ) |

Set the X axis

The item will painted according to the coordinates its Axes.

Parameters

  axis | X Axis ( QwtPlot::xBottom or QwtPlot::xTop )

See also
  setAxes(), setYAxis(), xAxis(), QwtPlot::Axis

## ◆ setYAxis()

void QwtPlotItem::setYAxis | ( | int | axis | ) |

Set the Y axis

The item will painted according to the coordinates its Axes.

Parameters

  axis | Y Axis ( QwtPlot::yLeft or QwtPlot::yRight )

See also
  setAxes(), setXAxis(), yAxis(), QwtPlot::Axis

## ◆ setZ()

void QwtPlotItem::setZ | ( | double | z | ) |

Set the z value.

Plot items are painted in increasing z-order.

Parameters

  z | Z-value

See also
  z(), QwtPlotDict::itemList()

## ◆ testItemAttribute()

bool QwtPlotItem::testItemAttribute | ( | ItemAttribute | attribute | ) | const

Test an item attribute

Parameters

  attribute | Attribute type

Returns
  true/false

See also
  setItemAttribute(), ItemInterest

## ◆ testItemInterest()

bool QwtPlotItem::testItemInterest | ( | ItemInterest | interest | ) | const

Test an item interest

Parameters

  interest | Interest type

Returns
  true/false

See also
  setItemInterest(), ItemAttribute

## ◆ testRenderHint()

bool QwtPlotItem::testRenderHint | ( | RenderHint | hint | ) | const

Test a render hint

Parameters

  hint | Render hint

Returns
  true/false

See also
  setRenderHint(), RenderHint

## ◆ title()

const QwtText & QwtPlotItem::title | ( |  | ) | const

Returns
  Title of the item

See also
  setTitle()

## ◆ updateLegend()

void QwtPlotItem::updateLegend | ( | const QwtPlotItem * | item,
|  | const QList< QwtLegendData > & | data
| ) |  |
| virtual

Update the item to changes of the legend info.

Plot items that want to display a legend ( not those, that want to be displayed on a legend ! ) will have to implement updateLegend().

updateLegend() is only called when the LegendInterest interest is enabled. The default implementation does nothing.

Parameters

  item | Plot item to be displayed on a legend
  data | Attributes how to display item on the legend

See also
  QwtPlotLegendItem

Note
  Plot items, that want to be displayed on a legend need to enable the QwtPlotItem::Legend flag and to implement legendData() and legendIcon()

Reimplemented in QwtPlotLegendItem.

## ◆ updateScaleDiv()

void QwtPlotItem::updateScaleDiv | ( | const QwtScaleDiv & | xScaleDiv,
|  | const QwtScaleDiv & | yScaleDiv
| ) |  |
| virtual

Update the item to changes of the axes scale division.

Update the item, when the axes of plot have changed. The default implementation does nothing, but items that depend on the scale division (like QwtPlotGrid()) have to reimplement updateScaleDiv()

updateScaleDiv() is only called when the ScaleInterest interest is enabled. The default implementation does nothing.

Parameters

  xScaleDiv | Scale division of the x-axis
  yScaleDiv | Scale division of the y-axis

See also
  QwtPlot::updateAxes(), ScaleInterest

Reimplemented in QwtPlotGrid, QwtPlotScaleItem, and QwtPlotSeriesItem.

## ◆ z()

double QwtPlotItem::z | ( |  | ) | const

Plot items are painted in increasing z-order.

Returns
  setZ(), QwtPlotDict::itemList()