W3cubDocs

/Qt 6.9

QPainterStateGuard Class

The QPainterStateGuard is a RAII convenience class for balanced QPainter::save() and QPainter::restore() calls. More...

Header: #include <QPainterStateGuard>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Since: Qt 6.9

Note: All functions in this class are reentrant.

Public Functions

QPainterStateGuard(QPainter *painter, QPainterStateGuard::InitialState state = InitialState::Save)
QPainterStateGuard(QPainterStateGuard &&other)
~QPainterStateGuard()
void restore()
void save()
void swap(QPainterStateGuard &other)
QPainterStateGuard & operator=(QPainterStateGuard &&other)

Detailed Description

QPainterStateGuard should be used everywhere as a replacement for QPainter::save() to make sure that the corresponding QPainter::restore() is called upon finishing of the painting routine to avoid unbalanced calls between those two functions.

Example with QPainter::save()/QPainter::restore():

void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter painter(this);
    painter.setPen(Qt::red);
    if (drawText) {
        painter.save();
        painter.setPen(Qt::blue);
        painter.setFont(QFont("Arial", 30));
        painter.drawText(rect(), Qt::AlignCenter, "Qt");
        painter.restore();  // don't forget to restore previous painter state
    }
    painter.drawLine(line);
}

Example with QPainterStateGuard:

void MyGuardWidget::paintEvent(QPaintEvent *)
{
    QPainter painter(this);
    painter.setPen(Qt::red);
    if (drawText) {
        QPainterStateGuard guard(&painter)
        painter.setPen(Qt::blue);
        painter.setFont(QFont("Arial", 30));
        painter.drawText(rect(), Qt::AlignCenter, "Qt");
    }
    painter.drawLine(line);
}

See also QPainter.

Member Function Documentation

[explicit] QPainterStateGuard::QPainterStateGuard(QPainter *painter, QPainterStateGuard::InitialState state = InitialState::Save)

Constructs a QPainterStateGuard and calls save() on painter if state is InitialState::Save (which is the default). When QPainterStateGuard is destroyed, restore() is called as often as save() was called to restore the QPainter's state.

[noexcept] QPainterStateGuard::QPainterStateGuard(QPainterStateGuard &&other)

Move-constructs a painter state guard from other.

[noexcept] QPainterStateGuard::~QPainterStateGuard()

Destroys the QPainterStateGuard instance and calls restore() as often as save() was called to restore the QPainter's state.

void QPainterStateGuard::restore()

Calls QPainter::restore() if the internal save/restore counter is greater than zero.

Note: This function asserts in debug builds if the counter has already reached zero.

void QPainterStateGuard::save()

Calls QPainter::save() and increases the internal save/restore counter by one.

[noexcept] void QPainterStateGuard::swap(QPainterStateGuard &other)

Swaps the other with this painter state guard. This operation is very fast and never fails.

[noexcept] QPainterStateGuard &QPainterStateGuard::operator=(QPainterStateGuard &&other)

Move-assigns other to this painter state guard.

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.9/qpainterstateguard.html