Qwt User's Guide: QwtGraphic Class Reference

Qwt User's Guide 6.1.5

Public Types | Public Member Functions | Protected Member Functions | List of all members
QwtGraphic Class Reference

A paint device for scalable graphics. More...

`#include <qwt_graphic.h>`

Inheritance diagram for QwtGraphic:
[legend]

## Public Types
enum | RenderHint { RenderPensUnscaled = 0x1 }
typedef QFlags< RenderHint > | RenderHints
| Render hints. More...
Public Types inherited from QwtNullPaintDevice
enum | Mode { NormalMode, PolygonPathMode, PathMode }
| Render mode. More...

## Public Member Functions
| QwtGraphic ()
| Constructor. More...
| QwtGraphic (const QwtGraphic &)
| Copy constructor. More...
virtual | ~QwtGraphic ()
| Destructor.
QwtGraphic & | operator= (const QwtGraphic &)
| Assignment operator. More...
void | reset ()
| Clear all stored commands. More...
bool | isNull () const
bool | isEmpty () const
void | render (QPainter *) const
| Replay all recorded painter commands. More...
void | render (QPainter *, const QSizeF &, Qt::AspectRatioMode=Qt::IgnoreAspectRatio) const
| Replay all recorded painter commands. More...
void | render (QPainter *, const QRectF &, Qt::AspectRatioMode=Qt::IgnoreAspectRatio) const
| Replay all recorded painter commands. More...
void | render (QPainter *, const QPointF &, Qt::Alignment=Qt::AlignTop|Qt::AlignLeft) const
| Replay all recorded painter commands. More...
QPixmap | toPixmap () const
| Convert the graphic to a QPixmap. More...
QPixmap | toPixmap (const QSize &, Qt::AspectRatioMode=Qt::IgnoreAspectRatio) const
| Convert the graphic to a QPixmap. More...
QImage | toImage () const
| Convert the graphic to a QImage. More...
QImage | toImage (const QSize &, Qt::AspectRatioMode=Qt::IgnoreAspectRatio) const
| Convert the graphic to a QImage. More...
QRectF | scaledBoundingRect (double sx, double sy) const
| Calculate the target rectangle for scaling the graphic. More...
QRectF | boundingRect () const
QRectF | controlPointRect () const
const QVector< QwtPainterCommand > & | commands () const
void | setCommands (QVector< QwtPainterCommand > &)
| Append paint commands. More...
void | setDefaultSize (const QSizeF &)
| Set a default size. More...
QSizeF | defaultSize () const
| Default size. More...
void | setRenderHint (RenderHint, bool on=true)
bool | testRenderHint (RenderHint) const
Public Member Functions inherited from QwtNullPaintDevice
| QwtNullPaintDevice ()
| Constructor.
virtual | ~QwtNullPaintDevice ()
| Destructor.
void | setMode (Mode)
Mode | mode () const
virtual QPaintEngine * | paintEngine () const
| See QPaintDevice::paintEngine()
virtual int | metric (PaintDeviceMetric) const
virtual void | drawRects (const QRect *, int)
| See QPaintEngine::drawRects()
virtual void | drawRects (const QRectF *, int)
| See QPaintEngine::drawRects()
virtual void | drawLines (const QLine *, int)
| See QPaintEngine::drawLines()
virtual void | drawLines (const QLineF *, int)
| See QPaintEngine::drawLines()
virtual void | drawEllipse (const QRectF &)
| See QPaintEngine::drawEllipse()
virtual void | drawEllipse (const QRect &)
| See QPaintEngine::drawEllipse()
virtual void | drawPoints (const QPointF *, int)
| See QPaintEngine::drawPoints()
virtual void | drawPoints (const QPoint *, int)
| See QPaintEngine::drawPoints()
virtual void | drawPolygon (const QPointF *, int, QPaintEngine::PolygonDrawMode)
| See QPaintEngine::drawPolygon()
virtual void | drawPolygon (const QPoint *, int, QPaintEngine::PolygonDrawMode)
| See QPaintEngine::drawPolygon()
virtual void | drawTextItem (const QPointF &, const QTextItem &)
| See QPaintEngine::drawTextItem()
virtual void | drawTiledPixmap (const QRectF &, const QPixmap &, const QPointF &)
| See QPaintEngine::drawTiledPixmap()

## Protected Member Functions
virtual QSize | sizeMetrics () const
virtual void | drawPath (const QPainterPath &)
virtual void | drawPixmap (const QRectF &, const QPixmap &, const QRectF &)
| Store a pixmap command in the command list. More...
virtual void | drawImage (const QRectF &, const QImage &, const QRectF &, Qt::ImageConversionFlags)
| Store a image command in the command list. More...
virtual void | updateState (const QPaintEngineState &state)
| Store a state command in the command list. More...

## Detailed Description

A paint device for scalable graphics.

QwtGraphic is the representation of a graphic that is tailored for scalability. Like QPicture it will be initialized by QPainter operations and can be replayed later to any target paint device.

While the usual image representations QImage and QPixmap are not scalable Qt offers two paint devices, that might be candidates for representing a vector graphic:

- QPicture
  Unfortunately QPicture had been forgotten, when Qt4 introduced floating point based render engines. Its API is still on integers, what make it unusable for proper scaling.
- QSvgRenderer/QSvgGenerator
  Unfortunately QSvgRenderer hides to much information about its nodes in internal APIs, that are necessary for proper layout calculations. Also it is derived from QObject and can't be copied like QImage/QPixmap.

QwtGraphic maps all scalable drawing primitives to a QPainterPath and stores them together with the painter state changes ( pen, brush, transformation ... ) in a list of QwtPaintCommands. For being a complete QPaintDevice it also stores pixmaps or images, what is somehow against the idea of the class, because these objects can't be scaled without a loss in quality.

The main issue about scaling a QwtGraphic object are the pens used for drawing the outlines of the painter paths. While non cosmetic pens ( QPen::isCosmetic() ) are scaled with the same ratio as the path, cosmetic pens have a fixed width. A graphic might have paths with different pens - cosmetic and non-cosmetic.

QwtGraphic caches 2 different rectangles:

- control point rectangle
  The control point rectangle is the bounding rectangle of all control point rectangles of the painter paths, or the target rectangle of the pixmaps/images.
- bounding rectangle
  The bounding rectangle extends the control point rectangle by what is needed for rendering the outline with an unscaled pen.

Because the offset for drawing the outline depends on the shape of the painter path ( the peak of a triangle is different than the flat side ) scaling with a fixed aspect ratio always needs to be calculated from the control point rectangle.

See also
  QwtPainterCommand

## Member Typedef Documentation

## ◆ RenderHints

typedef QFlags<RenderHint> QwtGraphic::RenderHints

Render hints.

The default setting is to disable all hints

## Member Enumeration Documentation

## ◆ RenderHint

enum QwtGraphic::RenderHint

Hint how to render a graphic

See also
  setRenderHint(), testRenderHint()

Enumerator
RenderPensUnscaled | When rendering a QwtGraphic a specific scaling between the controlPointRect() and the coordinates of the target rectangle is set up internally in render(). When RenderPensUnscaled is set this specific scaling is applied for the control points only, but not for the pens. All other painter transformations ( set up by application code ) are supposed to work like usual. See also render();

## Constructor & Destructor Documentation

## ◆ QwtGraphic() [1/2]

QwtGraphic::QwtGraphic | ( |  | ) |

Constructor.

Initializes a null graphic

See also
  isNull()

## ◆ QwtGraphic() [2/2]

QwtGraphic::QwtGraphic | ( | const QwtGraphic & | other | ) |

Copy constructor.

Parameters

  other | Source

See also
  operator=()

## Member Function Documentation

## ◆ boundingRect()

QRectF QwtGraphic::boundingRect | ( |  | ) | const

The bounding rectangle is the controlPointRect() extended by the areas needed for rendering the outlines with unscaled pens.

Returns
  Bounding rectangle of the graphic

See also
  controlPointRect(), scaledBoundingRect()

## ◆ commands()

const QVector< QwtPainterCommand > & QwtGraphic::commands | ( |  | ) | const

Returns
  List of recorded paint commands

See also
  setCommands()

## ◆ controlPointRect()

QRectF QwtGraphic::controlPointRect | ( |  | ) | const

The control point rectangle is the bounding rectangle of all control points of the paths and the target rectangles of the images/pixmaps.

Returns
  Control point rectangle

See also
  boundingRect(), scaledBoundingRect()

## ◆ defaultSize()

QSizeF QwtGraphic::defaultSize | ( |  | ) | const

Default size.

When a non empty size has been assigned by setDefaultSize() this size will be returned. Otherwise the default size is the size of the bounding rectangle.

The default size is used in all methods rendering the graphic, where no size is explicitly specified.

Returns
  Default size

See also
  setDefaultSize(), boundingRect()

## ◆ drawImage()

void QwtGraphic::drawImage | ( | const QRectF & | rect,
|  | const QImage & | image,
|  | const QRectF & | subRect,
|  | Qt::ImageConversionFlags | flags
| ) |  |
| protectedvirtual

Store a image command in the command list.

Parameters

  rect | traget rectangle
  image | Image to be painted
  subRect | Reactangle of the pixmap to be painted
  flags | Image conversion flags

See also
  QPaintEngine::drawImage()

Reimplemented from QwtNullPaintDevice.

## ◆ drawPath()

void QwtGraphic::drawPath | ( | const QPainterPath & | path | ) |
| protectedvirtual

Store a path command in the command list

Parameters

  path | Painter path

See also
  QPaintEngine::drawPath()

Reimplemented from QwtNullPaintDevice.

## ◆ drawPixmap()

void QwtGraphic::drawPixmap | ( | const QRectF & | rect,
|  | const QPixmap & | pixmap,
|  | const QRectF & | subRect
| ) |  |
| protectedvirtual

Store a pixmap command in the command list.

Parameters

  rect | target rectangle
  pixmap | Pixmap to be painted
  subRect | Reactangle of the pixmap to be painted

See also
  QPaintEngine::drawPixmap()

Reimplemented from QwtNullPaintDevice.

## ◆ isEmpty()

bool QwtGraphic::isEmpty | ( |  | ) | const

Returns
  True, when the bounding rectangle is empty

See also
  boundingRect(), isNull()

## ◆ isNull()

bool QwtGraphic::isNull | ( |  | ) | const

Returns
  True, when no painter commands have been stored

See also
  isEmpty(), commands()

## ◆ operator=()

QwtGraphic & QwtGraphic::operator= | ( | const QwtGraphic & | other | ) |

Assignment operator.

Parameters

  other | Source

Returns
  A reference of this object

## ◆ render() [1/4]

void QwtGraphic::render | ( | QPainter * | painter | ) | const

Replay all recorded painter commands.

Parameters

  painter | Qt painter

## ◆ render() [2/4]

void QwtGraphic::render | ( | QPainter * | painter,
|  | const QPointF & | pos,
|  | Qt::Alignment | alignment = `Qt::AlignTop | Qt::AlignLeft`
| ) |  | const

Replay all recorded painter commands.

The graphic is scaled to the defaultSize() and aligned to a position.

Parameters

  painter | Qt painter
  pos | Reference point, where to render
  alignment | Flags how to align the target rectangle to pos.

## ◆ render() [3/4]

void QwtGraphic::render | ( | QPainter * | painter,
|  | const QRectF & | rect,
|  | Qt::AspectRatioMode | aspectRatioMode = `Qt::IgnoreAspectRatio`
| ) |  | const

Replay all recorded painter commands.

The graphic is scaled to fit into the given rectangle

Parameters

  painter | Qt painter
  rect | Rectangle for the scaled graphic
  aspectRatioMode | Mode how to scale - See Qt::AspectRatioMode

## ◆ render() [4/4]

void QwtGraphic::render | ( | QPainter * | painter,
|  | const QSizeF & | size,
|  | Qt::AspectRatioMode | aspectRatioMode = `Qt::IgnoreAspectRatio`
| ) |  | const

Replay all recorded painter commands.

The graphic is scaled to fit into the rectangle of the given size starting at ( 0, 0 ).

Parameters

  painter | Qt painter
  size | Size for the scaled graphic
  aspectRatioMode | Mode how to scale - See Qt::AspectRatioMode

## ◆ reset()

void QwtGraphic::reset | ( |  | ) |

Clear all stored commands.

See also
  isNull()

## ◆ scaledBoundingRect()

QRectF QwtGraphic::scaledBoundingRect | ( | double | sx,
|  | double | sy
| ) |  | const

Calculate the target rectangle for scaling the graphic.

Parameters

  sx | Horizontal scaling factor
  sy | Vertical scaling factor

Note
  In case of paths that are painted with a cosmetic pen ( see QPen::isCosmetic() ) the target rectangle is different to multiplying the bounding rectangle.

Returns
  Scaled bounding rectangle

See also
  boundingRect(), controlPointRect()

## ◆ setCommands()

void QwtGraphic::setCommands | ( | QVector< QwtPainterCommand > & | commands | ) |

Append paint commands.

Parameters

  commands | Paint commands

See also
  commands()

## ◆ setDefaultSize()

void QwtGraphic::setDefaultSize | ( | const QSizeF & | size | ) |

Set a default size.

The default size is used in all methods rendering the graphic, where no size is explicitly specified. Assigning an empty size means, that the default size will be calculated from the bounding rectangle.

The default setting is an empty size.

Parameters

  size | Default size

See also
  defaultSize(), boundingRect()

## ◆ setRenderHint()

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

Toggle an render hint

Parameters

  hint | Render hint
  on | true/false

See also
  testRenderHint(), RenderHint

## ◆ sizeMetrics()

QSize QwtGraphic::sizeMetrics | ( |  | ) | const
| protectedvirtual

Returns
  Ceiled defaultSize()

Implements QwtNullPaintDevice.

## ◆ testRenderHint()

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

Test a render hint

Parameters

  hint | Render hint

Returns
  true/false

See also
  setRenderHint(), RenderHint

## ◆ toImage() [1/2]

QImage QwtGraphic::toImage | ( |  | ) | const

Convert the graphic to a QImage.

All pixels of the image get initialized by 0 ( transparent ) before the graphic is scaled and rendered on it.

The format of the image is QImage::Format_ARGB32_Premultiplied.

The size of the image is the default size ( ceiled to integers ) of the graphic.

Returns
  The graphic as image in default size

See also
  defaultSize(), toPixmap(), render()

## ◆ toImage() [2/2]

QImage QwtGraphic::toImage | ( | const QSize & | size,
|  | Qt::AspectRatioMode | aspectRatioMode = `Qt::IgnoreAspectRatio`
| ) |  | const

Convert the graphic to a QImage.

All pixels of the image get initialized by 0 ( transparent ) before the graphic is scaled and rendered on it.

The format of the image is QImage::Format_ARGB32_Premultiplied.

Parameters

  size | Size of the image
  aspectRatioMode | Aspect ratio how to scale the graphic

Returns
  The graphic as image

See also
  toPixmap(), render()

## ◆ toPixmap() [1/2]

QPixmap QwtGraphic::toPixmap | ( |  | ) | const

Convert the graphic to a QPixmap.

All pixels of the pixmap get initialized by Qt::transparent before the graphic is scaled and rendered on it.

The size of the pixmap is the default size ( ceiled to integers ) of the graphic.

Returns
  The graphic as pixmap in default size

See also
  defaultSize(), toImage(), render()

## ◆ toPixmap() [2/2]

QPixmap QwtGraphic::toPixmap | ( | const QSize & | size,
|  | Qt::AspectRatioMode | aspectRatioMode = `Qt::IgnoreAspectRatio`
| ) |  | const

Convert the graphic to a QPixmap.

All pixels of the pixmap get initialized by Qt::transparent before the graphic is scaled and rendered on it.

Parameters

  size | Size of the image
  aspectRatioMode | Aspect ratio how to scale the graphic

Returns
  The graphic as pixmap

See also
  toImage(), render()

## ◆ updateState()

void QwtGraphic::updateState | ( | const QPaintEngineState & | state | ) |
| protectedvirtual

Store a state command in the command list.

Parameters

  state | State to be stored

See also
  QPaintEngine::updateState()

Reimplemented from QwtNullPaintDevice.