QStaticText Class
La classe QStaticText permet un affichage optimisé du texte lorsque celui-ci et sa mise en page sont rarement mis à jour. En savoir plus...
| En-tête : | #include <QStaticText> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake : | QT += gui |
- Liste de tous les membres, y compris les membres hérités
- QStaticText fait partie des classes partagées implicitement.
Types publics
| enum | PerformanceHint { ModerateCaching, AggressiveCaching } |
Fonctions publiques
| 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 |
Description détaillée
QStaticText permet de mettre en cache les données de mise en page d’un bloc de texte afin de le dessiner plus efficacement qu’en utilisant QPainter::drawText(), où les informations de mise en page sont recalculées à chaque appel.
Cette classe offre principalement une optimisation dans les cas où le texte, sa police et les transformations appliquées au peintre restent statiques sur plusieurs événements de dessin. Si le texte ou sa mise en page est modifié à chaque itération, la méthode QPainter::drawText() constitue l'alternative la plus efficace, car la mise en page du texte statique devrait être recalculée pour prendre en compte le nouvel état.
La translation du « painter » n’entraînera pas le recalcul de la mise en page du texte, mais aura un impact très faible sur les performances de la méthode `drawStaticText()`. La modification de tout autre élément de la transformation du « painter » ou de sa police entraînera le recalcul de la mise en page du texte statique. Il convient d’éviter cela autant que possible afin de maximiser le gain de performances lié à l’utilisation de QStaticText.
De plus, seules les transformations affines sont prises en charge par `drawStaticText()`. L’appel de `drawStaticText()` sur un « painter » projeté sera légèrement moins performant que l’appel standard à `drawText()` ; il convient donc de l’éviter.
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;
};La classe QStaticText peut être utilisée pour imiter le comportement de la fonction ` QPainter::drawText()` sur un point spécifique sans limites, ainsi que lorsque la fonction ` QPainter::drawText()` est appelée avec un rectangle de délimitation.
Si aucun rectangle de délimitation n’est nécessaire, créez un objet QStaticText sans définir de largeur de texte préférentielle. Le texte s’affichera alors sur une seule ligne.
Si vous définissez une largeur de texte sur l’objet QStaticText, celle-ci servira de limite au texte. Le texte sera formaté de manière à ce qu’aucune ligne ne dépasse la largeur indiquée. La largeur de texte définie pour QStaticText ne sera pas automatiquement utilisée pour le rognage. Pour effectuer un rognage en plus des sauts de ligne, utilisez QPainter::setClipRect(). La position du texte est déterminée par l’argument passé à QPainter::drawStaticText() et peut varier d’un appel à l’autre avec un impact minimal sur les performances.
Pour plus de commodité, il est possible d’appliquer une mise en forme au texte à l’aide du sous-ensemble HTML pris en charge par QTextDocument. QStaticText tentera de deviner le format du texte d’entrée à l’aide de Qt::mightBeRichText() et l’interprétera comme du texte enrichi si cette fonction renvoie true. Pour forcer QStaticText à afficher son contenu sous forme de texte brut ou de texte enrichi, utilisez la fonction QStaticText::setTextFormat() et passez-lui, respectivement, Qt::PlainText et Qt::RichText.
QStaticText ne peut représenter que du texte ; par conséquent, seules les balises HTML qui modifient la mise en page ou l’apparence du texte seront prises en compte. L’ajout d’une image au code HTML d’entrée, par exemple, entraînera l’intégration de cette image dans la mise en page, ce qui affectera la position des caractères, mais l’image ne s’affichera pas. Il en résultera une zone vide de la taille de l'image dans la sortie. De même, l’utilisation de tableaux entraînera la mise en page du texte au format tableau, mais les bordures ne seront pas dessinées.
Si c'est la première fois que le texte statique est dessiné, ou si le texte statique ou la police du moteur de dessin a été modifié depuis le dernier dessin, la mise en page du texte doit être recalculée. Sur certains moteurs de dessin, la modification de la matrice du moteur de dessin entraînera également le recalcul de la mise en page. Cela se produit notamment pour tous les moteurs, à l’exception du moteur de dessin OpenGL2. Le recalcul de la mise en page entraîne une surcharge sur l’appel à ` QPainter::drawStaticText()` à l’endroit où il se produit. Pour éviter cette surcharge lors de l’événement de dessin, vous pouvez appeler ` prepare()` à l’avance afin de vous assurer que la mise en page est bien calculée.
Voir également QPainter::drawText(), QPainter::drawStaticText(), QTextLayout et QTextDocument.
Documentation sur les types de membres
enum QStaticText::PerformanceHint
Cette énumération répertorie les différentes indications de performances pouvant être définies sur l'objet ` QStaticText`. Ces indications permettent de préciser que l'objet ` QStaticText ` doit utiliser des caches supplémentaires, si possible, afin d'améliorer les performances au détriment de la mémoire. En particulier, la définition de l'indication de performances `AggressiveCaching` sur l'objet ` QStaticText ` améliorera les performances lors de l'utilisation du système graphique OpenGL ou lors du dessin sur un objet ` QOpenGLWidget`.
| Constante | Valeur | Description |
|---|---|---|
QStaticText::ModerateCaching | 0 | Effectuer une mise en cache de base pour des performances élevées avec un faible coût en mémoire. |
QStaticText::AggressiveCaching | 1 | Utilise une mise en cache supplémentaire lorsqu’elle est disponible. Cela peut améliorer les performances au prix d’une consommation de mémoire plus importante. |
Documentation sur les fonctions membres
QStaticText::QStaticText()
Crée un objet QStaticText vide
[explicit] QStaticText::QStaticText(const QString &text)
Crée un objet QStaticText avec l'text on fournie.
QStaticText::QStaticText(const QStaticText &other)
Crée un objet `QStaticText` qui est une copie de other.
[noexcept] QStaticText::~QStaticText()
Supprime le fichier « QStaticText ».
QStaticText::PerformanceHint QStaticText::performanceHint() const
Renvoie l'indicateur de performances défini pour le fichier « QStaticText ».
Voir également setPerformanceHint().
void QStaticText::prepare(const QTransform &matrix = QTransform(), const QFont &font = QFont())
Prépare l'objet ` QStaticText ` pour qu'il soit dessiné avec le texte statique ( matrix ) et le texte dynamique ( font ) fournis, afin d'éviter toute surcharge lors de l'appel effectif de la méthode `drawStaticText()`.
Lorsque drawStaticText() est appelé, la mise en page de l’ QStaticText sera recalculée si une partie quelconque de l’objet QStaticText a changé depuis le dernier tracé. Elle sera également recalculée si la police du peintre n’est pas la même que lors du dernier affichage de l’ QStaticText, ou, sur tout moteur de rendu autre que le moteur OpenGL2, si la matrice du peintre a été modifiée depuis le dernier affichage du texte statique.
Pour éviter la surcharge liée à la création de la mise en page lors du premier dessin de l’ QStaticText après avoir effectué des modifications, vous pouvez utiliser la fonction prepare() et lui passer l’ matrix et l’ font que vous prévoyez d’utiliser lors du dessin du texte.
Voir également QPainter::setFont() et QPainter::setWorldTransform().
void QStaticText::setPerformanceHint(QStaticText::PerformanceHint performanceHint)
Définit le paramètre de performance de l'QStaticText en fonction de la valeur fournie par ` performanceHint `. Le paramètre ` performanceHint ` permet de personnaliser le niveau de mise en cache interne afin d'améliorer les performances.
La valeur par défaut est QStaticText::ModerateCaching.
Remarque : cette fonction entraîne le recalcul de la mise en page du texte.
Voir également performanceHint().
void QStaticText::setText(const QString &text)
Définit le texte de l'QStaticText e sur « text ».
Remarque : cette fonction entraîne un recalcul de la mise en page du texte.
Voir également text().
void QStaticText::setTextFormat(Qt::TextFormat textFormat)
Définit le format de texte de l'QStaticText e sur textFormat. Si textFormat est défini sur Qt::AutoText (valeur par défaut), le format du texte sera déterminé, dans la mesure du possible, à l'aide de la fonction Qt::mightBeRichText(). Si le format du texte est Qt::PlainText, le texte s’affichera tel quel, tandis qu’il sera interprété comme du HTML si le format est Qt::RichText. Les balises HTML qui modifient la police, la couleur ou la mise en page du texte sont prises en charge par QStaticText.
Remarque : cette fonction entraîne un recalcul de la mise en page du texte.
Voir également textFormat(), setText() et text().
void QStaticText::setTextOption(const QTextOption &textOption)
Définit la structure des options de texte qui contrôle le processus de mise en page sur la valeur indiquée textOption.
Voir également textOption().
void QStaticText::setTextWidth(qreal textWidth)
Définit la largeur souhaitée pour cet QStaticText. Si le texte dépasse la largeur spécifiée, il sera réparti sur plusieurs lignes et s'étendra verticalement. Si le texte ne peut pas être réparti sur plusieurs lignes, il dépassera la textWidth spécifiée.
Si vous définissez la largeur de texte souhaitée sur une valeur négative, le texte n'aura pas de limite.
Utilisez size() pour obtenir la taille réelle du texte.
Remarque : cette fonction entraîne un recalcul de la mise en page du texte.
Voir également textWidth() et size().
QSizeF QStaticText::size() const
Renvoie la taille du rectangle englobant de cet objet ` QStaticText`.
Voir également textWidth().
[noexcept] void QStaticText::swap(QStaticText &other)
Remplace cette instance de texte statique par other. Cette opération est très rapide et ne rencontre jamais d'échec.
QString QStaticText::text() const
Renvoie le texte de l'QStaticText.
Voir aussi setText().
Qt::TextFormat QStaticText::textFormat() const
Renvoie le format texte de l'QStaticText.
Voir également setTextFormat(), setText() et text().
QTextOption QStaticText::textOption() const
Renvoie l'option de texte actuellement utilisée pour contrôler le processus de mise en page.
Voir aussi setTextOption().
qreal QStaticText::textWidth() const
Renvoie la largeur recommandée pour cet élément QStaticText.
Voir aussi setTextWidth().
bool QStaticText::operator!=(const QStaticText &other) const
Compare other à cette page QStaticText. Renvoie true si les textes, les polices ou les tailles maximales diffèrent.
QStaticText &QStaticText::operator=(const QStaticText &other)
Attribue l'adresse other à cette adresse QStaticText.
bool QStaticText::operator==(const QStaticText &other) const
Compare other à cette page QStaticText. Renvoie true si les textes, les polices et les largeurs de texte sont identiques.
© 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.
