- Qt 6.11
- Qt Canvas Painter
- C++ Classes
- QtCanvasPainter (Technical Preview)
- QCanvasPainterItem
- Qt Canvas Painter | Commercial or GPLv3

# QCanvasPainterItem Class

The QCanvasPainterItem class provides a way to use the Qt Canvas Painter API in the QML Scene Graph. More...

Header: | `#include <QCanvasPainterItem>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)` `target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)`
Since: | Qt 6.11
Inherits: | QQuickRhiItem
Status: | Technical Preview

- List of all members, including inherited members

## Properties

- debug : QVariantMap
- fillColor : QColor

## Public Functions

| QCanvasPainterItem(QQuickItem *parent = nullptr)
virtual | ~QCanvasPainterItem() override
QColor | fillColor() const
void | setFillColor(const QColor &color)

## Signals

void | debugChanged()
void | fillColorChanged()

## Protected Functions

virtual QCanvasPainterItemRenderer * | createItemRenderer() const = 0

## Reimplemented Protected Functions

virtual QQuickRhiItemRenderer * | createRenderer() override

## Detailed Description

To write your own painted item, you first create a subclass of QCanvasPainterItem, and then start by implementing its only pure virtual public function: createItemRenderer(), which returns an object that performs the actual painting.

The below code snippet shows the typical structure of a QCanvasPainterItem subclass. See QCanvasPainterItemRenderer for an example of the `MyRenderer` class.

     class MyItem : public QCanvasPainterItem
     {
         Q_OBJECT
         QML_NAMED_ELEMENT(MyItem) // exposed to QML, instantiate as MyItem { ... }

         // a custom property
         Q_PROPERTY(float value READ value WRITE setValue NOTIFY valueChanged)

     public:
         HelloItem(QQuickItem *parent = nullptr)
             : QCanvasPainterItem(parent)
         {
         }

         QCanvasPainterItemRenderer *createItemRenderer() const override
         {
             return new MyRenderer;
         }

         float value() const { return m_value; }
         void setValue(float newValue)
         {
             if (m_value != newValue) {
                 m_value = newValue;
                 emit valueChanged();
             }
         }
         float m_value = 0.0f;
     };

See also QCanvasPainterItemRenderer.

## Property Documentation

### `[read-only]` debug : QVariantMap

Contains a key - value map of rendering statistics. The data is only collected when the environment variable `QCPAINTER_DEBUG_COLLECT` is set to a non-zero value.

The data is updated periodically, not every time the item repaints. The interval is currently one second. Therefore, the data received will in many cases refer to a previous drawing of the item. This is not usually an issue when displaying the statistics interactively, but it is important to be aware of.

To automatically show the data within the item in form of an overlay, set the environment variable `QCPAINTER_DEBUG_RENDER` instead. This provides a convenient shortcut when the intention is anyway to show the values on-screen.

The list of keys is currently the following:

- fillDrawCallCount
- strokeDrawCallCount
- textDrawCallCount
- fillTriangleCount
- strokeTriangleCount
- textTriangleCount
- drawCallCount
- triangleCount

Notifier signal:

void | debugChanged()

### fillColor : QColor

This property holds the color to use for filling the item ie. the item background.

The default color is black.

Access functions:

QColor | fillColor() const
void | setFillColor(const QColor &color)

Notifier signal:

void | fillColorChanged()

## Member Function Documentation

### QCanvasPainterItem::QCanvasPainterItem(QQuickItem *parent = nullptr)

Constructs a QCanvasPainterItem with the given parent item.

### `[override virtual noexcept]` QCanvasPainterItem::~QCanvasPainterItem()

Destroys the QCanvasPainterItem.

### `[pure virtual protected]` QCanvasPainterItemRenderer *QCanvasPainterItem::createItemRenderer() const

Implement this method to (re)create a painter for this item. The painter class should be inherited from QCanvasPainterItemRenderer. QCanvasPainterItem takes the ownership of the created object and deletes it when needed.

Example code:

QCanvasPainterItemRenderer* MyItem::createItemRenderer() const { return new MyItemPainter(); }

### `[override virtual protected]` QQuickRhiItemRenderer *QCanvasPainterItem::createRenderer()

Reimplements: QQuickRhiItem::createRenderer().

### QColor QCanvasPainterItem::fillColor() const

Returns the current fill color.

Note: Getter function for property fillColor.

See also setFillColor().

### void QCanvasPainterItem::setFillColor(const QColor &color)

Set the fill color to color. This color will be used to draw the background of the item. The default color is black.

Note: When setting the fill color to not fully opaque (alpha channel less than 255), remember to set also alphaBlending to `true`.

Note: Setter function for property fillColor.

See also fillColor() and QQuickRhiItem::alphaBlending.