Back to Doc.qt.io
Contact Us Blog Download Qt
On this page

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

Properties

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.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.