Auf dieser Seite

QStaticText Class

Die Klasse „QStaticText“ ermöglicht eine optimierte Darstellung von Text, wenn der Text und sein Layout nur selten aktualisiert werden. Mehr...

Überschrift: #include <QStaticText>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

Öffentliche Typen

enum PerformanceHint { ModerateCaching, AggressiveCaching }

Öffentliche Funktionen

QStaticText()
QStaticText(const QString &text)
QStaticText(const QStaticText &other)
~QStaticText()
QStaticText::PerformanceHint performanceHint() const
void prepare(const QTransform &matrix = QTransform(), const QFont &font = QFont())
void setPerformanceHint(QStaticText::PerformanceHint performanceHint)
void setText(const QString &text)
void setTextFormat(Qt::TextFormat textFormat)
void setTextOption(const QTextOption &textOption)
void setTextWidth(qreal textWidth)
QSizeF size() const
void swap(QStaticText &other)
QString text() const
Qt::TextFormat textFormat() const
QTextOption textOption() const
qreal textWidth() const
bool operator!=(const QStaticText &other) const
QStaticText &operator=(const QStaticText &other)
bool operator==(const QStaticText &other) const

Ausführliche Beschreibung

QStaticText bietet eine Möglichkeit, Layoutdaten für einen Textblock zwischenzuspeichern, sodass dieser effizienter gezeichnet werden kann als bei Verwendung von ` QPainter::drawText()`, bei dem die Layoutinformationen bei jedem Aufruf neu berechnet werden.

Die Klasse dient in erster Linie als Optimierung für Fälle, in denen der Text, seine Schriftart und die Transformationen des Painters über mehrere Zeichnungsereignisse hinweg statisch bleiben. Wenn der Text oder sein Layout bei jeder Iteration geändert wird, ist ` QPainter::drawText()` die effizientere Alternative, da das Layout des statischen Textes neu berechnet werden müsste, um den neuen Zustand zu berücksichtigen.

Das Verschieben des Painters führt nicht zu einer Neuberechnung des Textlayouts, hat jedoch sehr geringe Auswirkungen auf die Leistung von `drawStaticText()`. Die Änderung anderer Teile der Transformation des Painters oder der Schriftart des Painters führt hingegen zu einer Neuberechnung des Layouts des statischen Textes. Dies sollte so oft wie möglich vermieden werden, um den Leistungsvorteil durch die Verwendung von `QStaticText` zu maximieren.

Zudem werden von `drawStaticText()` nur affine Transformationen unterstützt. Der Aufruf von `drawStaticText()` für einen projizierten Painter führt zu einer geringfügig schlechteren Leistung als die Verwendung des regulären `drawText()`-Aufrufs; dies sollte daher vermieden werden.

class MyWidget: public QWidget
{
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent), m_staticText("This is static text")

protected:
    void paintEvent(QPaintEvent *)
    {
        QPainter painter(this);
        painter.drawStaticText(0, 0, m_staticText);
    }

private:
    QStaticText m_staticText;
};

Die Klasse `QStaticText` kann verwendet werden, um das Verhalten von ` QPainter::drawText()` bis zu einem bestimmten Punkt ohne Begrenzungen nachzuahmen, sowie in Fällen, in denen ` QPainter::drawText()` mit einem Begrenzungsrechteck aufgerufen wird.

Wenn kein Begrenzungsrechteck erforderlich ist, erstellen Sie ein `QStaticText`-Objekt, ohne eine bevorzugte Textbreite festzulegen. Der Text nimmt dann eine einzige Zeile ein.

Wenn Sie eine Textbreite für das QStaticText-Objekt festlegen, wird der Text dadurch begrenzt. Der Text wird so formatiert, dass keine Zeile die angegebene Breite überschreitet. Die für `QStaticText` festgelegte Textbreite wird nicht automatisch für das Beschneiden verwendet. Um zusätzlich zu Zeilenumbrüchen ein Beschneiden zu erzielen, verwenden Sie ` QPainter::setClipRect()`. Die Position des Textes wird durch das an ` QPainter::drawStaticText()` übergebene Argument bestimmt und kann sich von Aufruf zu Aufruf ändern, wobei die Auswirkungen auf die Leistung minimal sind.

Für zusätzlichen Komfort ist es möglich, den Text mithilfe der von ` QTextDocument` unterstützten HTML-Teilmenge zu formatieren. `QStaticText` versucht, das Format des Eingabetextes mithilfe von ` Qt::mightBeRichText()` zu ermitteln, und interpretiert ihn als Rich Text, wenn diese Funktion ` true` zurückgibt. Um QStaticText zu zwingen, seinen Inhalt entweder als einfachen Text oder als Rich Text anzuzeigen, verwenden Sie die Funktion ` QStaticText::setTextFormat()` und übergeben Sie jeweils ` Qt::PlainText ` bzw. ` Qt::RichText`.

QStaticText kann nur Text darstellen, daher werden nur HTML-Tags berücksichtigt, die das Layout oder das Erscheinungsbild des Textes verändern. Das Hinzufügen eines Bildes zum Eingabe-HTML führt beispielsweise dazu, dass das Bild als Teil des Layouts einbezogen wird und die Positionen der Textzeichen beeinflusst, es wird jedoch nicht angezeigt. Das Ergebnis ist ein leerer Bereich in der Größe des Bildes in der Ausgabe. Ebenso führt die Verwendung von Tabellen dazu, dass der Text im Tabellenformat angeordnet wird, die Rahmen werden jedoch nicht gezeichnet.

Wenn der statische Text zum ersten Mal gezeichnet wird oder wenn sich der statische Text oder die Schriftart des Painters seit dem letzten Zeichnungsvorgang geändert hat, muss das Layout des Textes neu berechnet werden. Bei einigen Paint-Engines führt auch eine Änderung der Matrix des Painters dazu, dass das Layout neu berechnet wird. Dies gilt insbesondere für alle Engines mit Ausnahme der OpenGL2-Zeichen-Engine. Die Neuberechnung des Layouts verursacht einen Mehraufwand beim Aufruf von ` QPainter::drawStaticText()`, wo dieser erfolgt. Um diesen Mehraufwand im Zeichenereignis zu vermeiden, können Sie vorab ` prepare()` aufrufen, um sicherzustellen, dass das Layout berechnet wird.

Siehe auch QPainter::drawText(), QPainter::drawStaticText(), QTextLayout und QTextDocument.

Dokumentation zu Mitgliedstypen

enum QStaticText::PerformanceHint

Diese Aufzählung enthält die verschiedenen Leistungshinweise, die für die „ QStaticText “ festgelegt werden können. Mit diesen Hinweisen kann angegeben werden, dass der „ QStaticText “ nach Möglichkeit zusätzliche Caches nutzen soll, um die Leistung auf Kosten des Arbeitsspeichers zu verbessern. Insbesondere führt die Festlegung des Leistungshinweises „AggressiveCaching“ für die „ QStaticText “ zu einer Leistungssteigerung bei der Verwendung des OpenGL-Grafiksystems oder beim Zeichnen auf eine „ QOpenGLWidget “.

KonstanteWertBeschreibung
QStaticText::ModerateCaching0Führt grundlegendes Caching durch, um hohe Leistung bei geringem Speicherbedarf zu erzielen.
QStaticText::AggressiveCaching1Verwendet zusätzliches Caching, sofern verfügbar. Dies kann die Leistung auf Kosten von mehr Speicher verbessern.

Dokumentation der Mitgliedsfunktionen

QStaticText::QStaticText()

Erstellt ein leeres QStaticText-Objekt

[explicit] QStaticText::QStaticText(const QString &text)

Erstellt ein QStaticText-Objekt mit dem angegebenen „ text “.

QStaticText::QStaticText(const QStaticText &other)

Erstellt ein QStaticText-Objekt, das eine Kopie von „ other “ ist.

[noexcept] QStaticText::~QStaticText()

Zerstört den „ QStaticText “.

QStaticText::PerformanceHint QStaticText::performanceHint() const

Gibt zurück, welcher Performance-Hinweis für die „ QStaticText “ festgelegt ist.

Siehe auch setPerformanceHint().

void QStaticText::prepare(const QTransform &matrix = QTransform(), const QFont &font = QFont())

Bereitet das „ QStaticText “-Objekt darauf vor, mit dem angegebenen „ matrix “ und dem angegebenen „ font “ gezeichnet zu werden, um Overhead beim eigentlichen Aufruf von „drawStaticText()“ zu vermeiden.

Wenn drawStaticText() aufgerufen wird, wird das Layout des „ QStaticText “ neu berechnet, falls sich seit dem letzten Zeichnungsvorgang ein Teil des „ QStaticText “-Objekts geändert hat. Es wird ebenfalls neu berechnet, wenn die Schriftart des Painters nicht mit derjenigen übereinstimmt, die beim letzten Zeichnen des „ QStaticText “ verwendet wurde, oder – bei einer anderen Paint-Engine als der OpenGL2-Engine – wenn die Matrix des Painters seit dem letzten Zeichnen des statischen Texts geändert wurde.

Um den Mehraufwand für die Erstellung des Layouts beim ersten Zeichnen des „ QStaticText “ nach vorgenommenen Änderungen zu vermeiden, können Sie die Funktion `prepare()` verwenden und das ` matrix ` sowie den ` font ` übergeben, die Sie beim Zeichnen des Textes voraussichtlich verwenden werden.

Siehe auch ` QPainter::setFont()` und ` QPainter::setWorldTransform()`.

void QStaticText::setPerformanceHint(QStaticText::PerformanceHint performanceHint)

Legt den Performance-Hinweis für den „ QStaticText “ entsprechend dem angegebenen „ performanceHint “ fest. Der „ performanceHint “ wird verwendet, um anzupassen, in welchem Umfang intern zwischengespeichert wird, um die Leistung zu verbessern.

Der Standardwert ist „ QStaticText::ModerateCaching “.

Hinweis: Diese Funktion führt dazu, dass das Layout des Textes neu berechnet werden muss.

Siehe auch performanceHint().

void QStaticText::setText(const QString &text)

Setzt den Text von „ QStaticText “ auf „ text “.

Hinweis: Diese Funktion führt dazu, dass das Layout des Textes neu berechnet werden muss.

Siehe auch text().

void QStaticText::setTextFormat(Qt::TextFormat textFormat)

Legt das Textformat von „ QStaticText “ auf „ textFormat “ fest. Wenn „ textFormat “ auf „ Qt::AutoText “ gesetzt ist (Standardeinstellung), wird versucht, das Textformat mithilfe der Funktion „ Qt::mightBeRichText()“ zu ermitteln. Wenn das Textformat „ Qt::PlainText “ lautet, wird der Text unverändert angezeigt, während er als HTML interpretiert wird, wenn das Format „ Qt::RichText “ ist. HTML-Tags, die die Schriftart, die Farbe oder das Layout des Textes verändern, werden von „ QStaticText “ unterstützt.

Hinweis: Diese Funktion führt dazu, dass das Layout des Textes neu berechnet werden muss.

Siehe auch textFormat(), setText() und text().

void QStaticText::setTextOption(const QTextOption &textOption)

Setzt die Textoptionsstruktur, die den Layoutprozess steuert, auf den angegebenen Wert „ textOption “.

Siehe auch textOption().

void QStaticText::setTextWidth(qreal textWidth)

Legt die bevorzugte Breite für dieses ` QStaticText` fest. Ist der Text breiter als die angegebene Breite, wird er in mehrere Zeilen umgebrochen und dehnt sich vertikal aus. Kann der Text nicht in mehrere Zeilen umgebrochen werden, ist er größer als das angegebene ` textWidth`.

Wird die bevorzugte Textbreite auf einen negativen Wert gesetzt, ist der Text unbegrenzt.

Verwenden Sie ` size()``, um die tatsächliche Größe des Textes abzurufen.

Hinweis: Diese Funktion führt dazu, dass das Layout des Textes neu berechnet werden muss.

Siehe auch textWidth() und size().

QSizeF QStaticText::size() const

Gibt die Größe des Begrenzungsrechtecks für dieses ` QStaticText` zurück.

Siehe auch textWidth().

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

Ersetzt diese statische Textinstanz durch „ other “. Dieser Vorgang ist sehr schnell und schlägt niemals fehl.

QString QStaticText::text() const

Gibt den Text der „ QStaticText “ zurück.

Siehe auch setText().

Qt::TextFormat QStaticText::textFormat() const

Gibt das Textformat des „ QStaticText “ zurück.

Siehe auch setTextFormat(), setText() und text().

QTextOption QStaticText::textOption() const

Gibt die aktuell verwendete Textoption zurück, die zur Steuerung des Layoutprozesses dient.

Siehe auch „ setTextOption()“.

qreal QStaticText::textWidth() const

Gibt die bevorzugte Breite für dieses QStaticText zurück.

Siehe auch setTextWidth().

bool QStaticText::operator!=(const QStaticText &other) const

Vergleicht other mit dieser Seite: QStaticText. Gibt „ true “ zurück, wenn sich die Texte, Schriftarten oder maximalen Größen unterscheiden.

QStaticText &QStaticText::operator=(const QStaticText &other)

Weist „ other “ diesem „ QStaticText “ zu.

bool QStaticText::operator==(const QStaticText &other) const

Vergleicht other mit dieser Seite: QStaticText. Gibt true zurück, wenn die Texte, Schriftarten und Textbreiten identisch sind.

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