QPainterStateGuard Class Reference

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

#include <qpainterstateguard.h>

Collaboration diagram for QPainterStateGuard:

Public Types
enum class	InitialState : quint8 { Save , NoSave }

Public Member Functions
	QPainterStateGuard (QPainterStateGuard &&other) noexcept
	Move-constructs a painter state guard from other.
void	swap (QPainterStateGuard &other) noexcept
	Swaps the other with this painter state guard.
Q_NODISCARD_CTOR	QPainterStateGuard (QPainter *painter, InitialState state=InitialState::Save)
	Constructs a QPainterStateGuard and calls save() on painter if state is InitialState::Save (which is the default).
	~QPainterStateGuard ()
	Destroys the QPainterStateGuard instance and calls restore() as often as save() was called to restore the QPainter's state.
void	save ()
	Calls QPainter::save() and increases the internal save/restore counter by one.
void	restore ()
	Calls QPainter::restore() if the internal save/restore counter is greater than zero.

Detailed Description

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

Since

6.9

\inmodule QtGui

\reentrant

See also

QPainter

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()/QPainterrestore():

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);
}

Definition at line 12 of file qpainterstateguard.h.

Member Enumeration Documentation

InitialState

enum class QPainterStateGuard::InitialState : quint8

strong

Enumerator
Save
NoSave

Definition at line 16 of file qpainterstateguard.h.

Constructor & Destructor Documentation

QPainterStateGuard() [1/2]

QPainterStateGuard::QPainterStateGuard ( QPainterStateGuard && other )

inlinenoexcept

Move-constructs a painter state guard from other.

Definition at line 21 of file qpainterstateguard.h.

QPainterStateGuard() [2/2]

Q_NODISCARD_CTOR QPainterStateGuard::QPainterStateGuard ( QPainter * painter, InitialState state = InitialState::Save )

inlineexplicit

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.

Definition at line 33 of file qpainterstateguard.h.

~QPainterStateGuard()

QPainterStateGuard::~QPainterStateGuard ( )

inline

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

Definition at line 41 of file qpainterstateguard.h.

Member Function Documentation

restore()

void QPainterStateGuard::restore ( )

inline

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.

Definition at line 54 of file qpainterstateguard.h.

save()

void QPainterStateGuard::save ( )

inline

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

Definition at line 47 of file qpainterstateguard.h.

swap()

void QPainterStateGuard::swap ( QPainterStateGuard & other )

inlinenoexcept

Swaps the other with this painter state guard.

This operation is very fast and never fails.

Definition at line 26 of file qpainterstateguard.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/gui/painting/qpainterstateguard.h (5c20f9aa5c31d30a2dccfc617e93c6d6ac0fc96c)
• qtbase/src/gui/painting/qpainterstateguard.cpp (ec3a5f4994a2bafc65fa8e01fb0861219580f622)