En esta página

QStaticText Class

La clase QStaticText permite optimizar el dibujo del texto cuando este y su diseño se actualizan con poca frecuencia. Más información...

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

Tipos públicos

enum PerformanceHint { ModerateCaching, AggressiveCaching }

Funciones públicas

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

Descripción detallada

QStaticText ofrece una forma de almacenar en caché los datos de diseño de un bloque de texto, de modo que se pueda dibujar de forma más eficiente que utilizando ` QPainter::drawText()` —en cuyo caso la información de diseño se recalcula con cada llamada—.

La clase ofrece principalmente una optimización para aquellos casos en los que el texto, su fuente y las transformaciones del pintor permanecen estáticas a lo largo de varios eventos de dibujo. Si el texto o su diseño cambian en cada iteración, QPainter::drawText() es la alternativa más eficiente, ya que habría que volver a calcular el diseño del texto estático para tener en cuenta el nuevo estado.

La traslación del «painter» no provocará que se recalcule el diseño del texto, pero sí tendrá un impacto muy leve en el rendimiento de `drawStaticText()`. La modificación de cualquier otra parte de la transformación del «painter» o de su fuente provocará que se recalcule el diseño del texto estático. Esto debe evitarse en la medida de lo posible para maximizar la mejora de rendimiento que supone el uso de QStaticText.

Además, drawStaticText() solo admite transformaciones afines. Llamar a drawStaticText() sobre un pintor proyectado tendrá un rendimiento ligeramente inferior al de la llamada habitual a drawText(), por lo que debe evitarse.

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 clase `QStaticText` puede utilizarse para imitar el comportamiento de ` QPainter::drawText()` en un punto específico sin límites, así como cuando se llama a ` QPainter::drawText()` con un rectángulo delimitador.

Si no se requiere un rectángulo delimitador, crea un objeto QStaticText sin establecer un ancho de texto preferido. De este modo, el texto ocupará una sola línea.

Si se establece un ancho de texto en el objeto QStaticText, esto limitará el texto. El texto se formateará de manera que ninguna línea supere el ancho especificado. El ancho de texto establecido para QStaticText no se utilizará automáticamente para el recorte. Para lograr el recorte además de los saltos de línea, utiliza QPainter::setClipRect(). La posición del texto viene determinada por el argumento pasado a QPainter::drawStaticText() y puede cambiar de una llamada a otra con un impacto mínimo en el rendimiento.

Para mayor comodidad, es posible aplicar formato al texto utilizando el subconjunto HTML compatible con QTextDocument. QStaticText intentará adivinar el formato del texto de entrada utilizando Qt::mightBeRichText() e interpretarlo como texto enriquecido si esta función devuelve true. Para forzar a QStaticText a mostrar su contenido como texto sin formato o como texto enriquecido, utilice la función QStaticText::setTextFormat() y pásele, respectivamente, Qt::PlainText y Qt::RichText.

QStaticText solo puede representar texto, por lo que únicamente se respetarán las etiquetas HTML que modifiquen el diseño o la apariencia del texto. Añadir una imagen al código HTML de entrada, por ejemplo, hará que la imagen se incluya como parte del diseño, lo que afectará a la posición de los glifos de texto, pero no se mostrará. El resultado será un área vacía del tamaño de la imagen en la salida. Del mismo modo, el uso de tablas hará que el texto se maquetará en formato de tabla, pero los bordes no se dibujarán.

Si es la primera vez que se dibuja el texto estático, o si el texto estático o la fuente del pintor se han modificado desde la última vez que se dibujó, es necesario volver a calcular el diseño del texto. En algunos motores de pintura, cambiar la matriz del pintor también provocará que se vuelva a calcular el diseño. En concreto, esto ocurrirá en cualquier motor excepto en el motor de pintura OpenGL2. El recálculo del diseño supondrá una sobrecarga en la llamada a ` QPainter::drawStaticText()` donde se produzca. Para evitar esta sobrecarga en el evento de pintura, puedes llamar a ` prepare()` con antelación para asegurarte de que se calcule el diseño.

Véase también QPainter::drawText(), QPainter::drawStaticText(), QTextLayout y QTextDocument.

Documentación sobre tipos de miembros

enum QStaticText::PerformanceHint

Esta enumeración recoge las diferentes indicaciones de rendimiento que se pueden establecer en el objeto ` QStaticText`. Estas indicaciones pueden utilizarse para indicar que el objeto ` QStaticText ` debe utilizar cachés adicionales, si es posible, para mejorar el rendimiento a costa de la memoria. En concreto, establecer la indicación de rendimiento `AggressiveCaching` en el objeto ` QStaticText ` mejorará el rendimiento al utilizar el sistema gráfico OpenGL o al dibujar en un objeto ` QOpenGLWidget`.

ConstanteValorDescripción
QStaticText::ModerateCaching0Realiza un almacenamiento en caché básico para obtener un alto rendimiento con un bajo coste de memoria.
QStaticText::AggressiveCaching1Utiliza almacenamiento en caché adicional cuando esté disponible. Esto puede mejorar el rendimiento a costa de un mayor consumo de memoria.

Documentación de las funciones de miembro

QStaticText::QStaticText()

Crea un objeto QStaticText vacío

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

Crea un objeto QStaticText con el texto dado ` text`.

QStaticText::QStaticText(const QStaticText &other)

Crea un objeto QStaticText que es una copia de other.

[noexcept] QStaticText::~QStaticText()

Destruye el « QStaticText ».

QStaticText::PerformanceHint QStaticText::performanceHint() const

Devuelve qué indicación de rendimiento está configurada para el ` QStaticText`.

Véase también setPerformanceHint().

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

Prepara el objeto « QStaticText » para que se dibuje con el texto « matrix » y el formato « font » proporcionados, con el fin de evitar sobrecarga cuando se realice la llamada efectiva a «drawStaticText()».

Cuando se llama a drawStaticText(), se recalculará el diseño del objeto QStaticText si alguna parte del objeto QStaticText ha cambiado desde la última vez que se dibujó. También se recalculará si la fuente del pintor no es la misma que cuando se dibujó por última vez el ` QStaticText `, o, en cualquier motor de pintura distinto del motor OpenGL2, si la matriz del pintor se ha modificado desde la última vez que se dibujó el texto estático.

Para evitar la sobrecarga que supone crear el diseño la primera vez que se dibuja el « QStaticText » tras realizar cambios, se puede utilizar la función `prepare()` y pasarle el ` matrix ` y el ` font ` que se prevé utilizar al dibujar el texto.

Véanse también QPainter::setFont() y QPainter::setWorldTransform().

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

Establece la configuración de rendimiento de QStaticText según el valor proporcionado en performanceHint. El parámetro performanceHint se utiliza para personalizar el nivel de almacenamiento en caché interno con el fin de mejorar el rendimiento.

El valor por defecto es QStaticText::ModerateCaching.

Nota: Esta función provocará que sea necesario volver a calcular el diseño del texto.

Véase también performanceHint().

void QStaticText::setText(const QString &text)

Establece el texto de « QStaticText » en « text ».

Nota: Esta función provocará que sea necesario volver a calcular el diseño del texto.

Véase también text().

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

Establece el formato de texto de ` QStaticText ` en ` textFormat`. Si ` textFormat ` se establece en ` Qt::AutoText ` (valor por defecto), se intentará determinar el formato del texto mediante la función ` Qt::mightBeRichText()`. Si el formato del texto es Qt::PlainText, el texto se mostrará tal cual, mientras que se interpretará como HTML si el formato es Qt::RichText. Las etiquetas HTML que modifican la fuente del texto, su color o su diseño son compatibles con QStaticText.

Nota: Esta función provocará que sea necesario volver a calcular el diseño del texto.

Véase también textFormat(), setText() y text().

void QStaticText::setTextOption(const QTextOption &textOption)

Establece la estructura de opciones de texto que controla el proceso de maquetación según el valor indicado en textOption.

Véase también textOption().

void QStaticText::setTextWidth(qreal textWidth)

Establece el ancho preferido para este QStaticText. Si el texto tiene un ancho superior al especificado, se dividirá en varias líneas y se ampliará verticalmente. Si el texto no se puede dividir en varias líneas, su tamaño será mayor que el especificado en textWidth.

Si se establece el ancho de texto preferido en un número negativo, el texto no tendrá límites.

Utiliza size() para obtener el tamaño real del texto.

Nota: Esta función hará que sea necesario recalcular el diseño del texto.

Véase también textWidth() y size().

QSizeF QStaticText::size() const

Devuelve el tamaño del rectángulo delimitador de este ` QStaticText`.

Véase también textWidth().

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

Sustituye esta instancia de texto estático por other. Esta operación es muy rápida y nunca falla.

QString QStaticText::text() const

Devuelve el texto de QStaticText.

Véase también setText().

Qt::TextFormat QStaticText::textFormat() const

Devuelve el formato de texto del QStaticText.

Véase también setTextFormat(), setText() y text().

QTextOption QStaticText::textOption() const

Devuelve la opción de texto actual utilizada para controlar el proceso de maquetación.

Véase también setTextOption().

qreal QStaticText::textWidth() const

Devuelve el ancho preferido para este QStaticText.

Véase también setTextWidth().

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

Compara other con esta página QStaticText. Devuelve true si los textos, las fuentes o los tamaños máximos son diferentes.

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

Asigna other a esta dirección QStaticText.

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

Compara other con esto: QStaticText. Devuelve true si los textos, las fuentes y los anchos de texto son iguales.

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