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

QQuickCPainterItem Class

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

Header: #include <QQuickCPainterItem>
Inherits: QQuickRhiItem

Properties

Public Functions

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

Signals

void debugChanged()
void fillColorChanged()

Protected Functions

virtual QQuickCPainterRenderer *createItemRenderer() const = 0

Reimplemented Protected Functions

virtual QQuickRhiItemRenderer *createRenderer() override

Detailed Description

To write your own painted item, you first create a subclass of QQuickCPainterItem, 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 QQuickCPainterItem subclass. See QQuickCPainterRenderer for an example of the MyRenderer class.

class MyItem : public QQuickCPainterItem
{
    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)
        : QQuickCPainterItem(parent)
    {
    }

    QQuickCPainterRenderer *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 QQuickCPainterRenderer.

Property Documentation

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

QQuickCPainterItem::QQuickCPainterItem(QQuickItem *parent = nullptr)

Constructs a QQuickCPainterItem with the given parent item.

[override virtual noexcept] QQuickCPainterItem::~QQuickCPainterItem()

Destroys the QQuickCPainterItem.

[pure virtual protected] QQuickCPainterRenderer *QQuickCPainterItem::createItemRenderer() const

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

Example code:

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

[override virtual protected] QQuickRhiItemRenderer *QQuickCPainterItem::createRenderer()

Reimplements: QQuickRhiItem::createRenderer().

QColor QQuickCPainterItem::fillColor() const

Returns the current fill color.

Note: Getter function for property fillColor.

See also setFillColor().

void QQuickCPainterItem::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.

© 2025 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.