QStaticText Class
La clase QStaticText permite el dibujo optimizado de texto cuando el texto y su diseño se actualizan raramente. Más...
| Cabecera: | #include <QStaticText> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
- Lista de todos los miembros, incluyendo los heredados
- QStaticText es parte de Clases Implícitamente Compartidas.
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 proporciona una manera de almacenar en caché los datos de diseño de un bloque de texto para que pueda ser dibujado de manera más eficiente que utilizando QPainter::drawText() en el que la información de diseño se vuelve a calcular con cada llamada.
La clase proporciona principalmente una optimización para los casos en que el texto, su fuente y las transformaciones en el pintor son estáticos a lo largo de varios eventos de pintura. Si el texto o su disposición cambian en cada iteración, QPainter::drawText() es la alternativa más eficiente, ya que la disposición del texto estático tendría que recalcularse para tener en cuenta el nuevo estado.
Traducir el pintor no hará que se recalcule el diseño del texto, pero tendrá un impacto muy pequeño en el rendimiento de drawStaticText(). Alterar cualquier otra parte de la transformación del pintor o la fuente del pintor hará que se recalcule el diseño del texto estático. Esto debe evitarse tan a menudo como sea posible para maximizar el beneficio en rendimiento del uso de QStaticText.
Además, drawStaticText() sólo admite transformaciones afines. Llamar a drawStaticText() en un pintor proyectado tendrá un rendimiento ligeramente peor que usar la llamada normal a drawText(), por lo que debería 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 se puede utilizar para imitar el comportamiento de QPainter::drawText() a un punto específico sin límites, y también cuando QPainter::drawText() se llama con un rectángulo delimitador.
Si no se requiere un rectángulo delimitador, cree un objeto QStaticText sin establecer un ancho de texto preferido. El texto ocupará entonces una sola línea.
Si se establece una anchura de texto en el objeto QStaticText, se delimitará el texto. El texto será formateado de manera que ninguna línea exceda el ancho dado. 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, utilice QPainter::setClipRect(). La posición del texto se decide por el argumento pasado a QPainter::drawStaticText() y puede cambiar de llamada a llamada con un impacto mínimo en el rendimiento.
Para mayor comodidad, es posible aplicar formato al texto utilizando el subconjunto HTML soportado por QTextDocument. QStaticText intentará adivinar el formato del texto de entrada utilizando Qt::mightBeRichText(), y lo interpretará como texto enriquecido si esta función devuelve true. Para forzar a QStaticText a mostrar su contenido como texto plano o como texto enriquecido, utilice la función QStaticText::setTextFormat() e introduzca, respectivamente, Qt::PlainText y Qt::RichText.
QStaticText sólo puede representar texto, por lo que sólo se respetarán las etiquetas HTML que alteren el diseño o la apariencia del texto. Añadir una imagen al HTML de entrada, por ejemplo, hará que la imagen se incluya como parte del diseño, afectando a las posiciones de los glifos del 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 disponga en formato de tabla, pero no se dibujarán los bordes.
Si es la primera vez que se dibuja el texto estático, o si el texto estático, o la fuente del pintor ha sido alterada desde la última vez que se dibujó, la disposición del texto tiene que ser recalculada. En algunos motores de pintura, el cambio de la matriz del pintor también hará que se recalcule el diseño. En particular, esto ocurrirá para cualquier motor excepto para el motor de pintura OpenGL2. Recalcular el diseño impondrá una sobrecarga en la llamada a QPainter::drawStaticText() cuando ocurra. Para evitar esta sobrecarga en el evento paint, puedes llamar a prepare() con antelación para asegurarte de que el layout está calculado.
Véase también QPainter::drawText(), QPainter::drawStaticText(), QTextLayout, y QTextDocument.
Documentación de tipos de miembros
enum QStaticText::PerformanceHint
Este enumera las diferentes sugerencias de rendimiento que se pueden establecer en QStaticText. Estas sugerencias se pueden utilizar para indicar que QStaticText debe utilizar cachés adicionales, si es posible, para mejorar el rendimiento a expensas de la memoria. En particular, si se establece la sugerencia de rendimiento AggressiveCaching en QStaticText se mejorará el rendimiento cuando se utilice el sistema gráfico OpenGL o cuando se dibuje en QOpenGLWidget.
| Constante | Valor | Descripción |
|---|---|---|
QStaticText::ModerateCaching | 0 | Realiza un almacenamiento en caché básico para obtener un alto rendimiento con un bajo coste de memoria. |
QStaticText::AggressiveCaching | 1 | Utilizar caché adicional cuando esté disponible. Esto puede mejorar el rendimiento con un mayor coste de memoria. |
Documentación de las funciones miembro
QStaticText::QStaticText()
Construye un QStaticText vacío
[explicit] QStaticText::QStaticText(const QString &text)
Construye un objeto QStaticText con la dirección text.
QStaticText::QStaticText(const QStaticText &other)
Construye un objeto QStaticText que es una copia de other.
[noexcept] QStaticText::~QStaticText()
Destruye el QStaticText.
QStaticText::PerformanceHint QStaticText::performanceHint() const
Devuelve qué pista de rendimiento está configurada para QStaticText.
Véase también setPerformanceHint().
void QStaticText::prepare(const QTransform &matrix = QTransform(), const QFont &font = QFont())
Prepara el objeto QStaticText para ser pintado con el matrix dado y el font dado para evitar sobrecarga cuando se hace la llamada real a drawStaticText().
Cuando se llama a drawStaticText(), el diseño de QStaticText será recalculado si alguna parte del objeto QStaticText ha cambiado desde la última vez que fue dibujado. También se recalculará si la fuente del pintor no es la misma que la última vez que se dibujó QStaticText, o, en cualquier otro motor de pintura que no sea el motor OpenGL2, si la matriz del pintor ha sido alterada desde la última vez que se dibujó el texto estático.
Para evitar la sobrecarga de crear el diseño la primera vez que dibuje el QStaticText después de hacer cambios, puede utilizar la función prepare() y pasar los matrix y font que espera utilizar al dibujar el texto.
Véase también QPainter::setFont() y QPainter::setWorldTransform().
void QStaticText::setPerformanceHint(QStaticText::PerformanceHint performanceHint)
Establece la sugerencia de rendimiento del QStaticText de acuerdo con el performanceHint proporcionado. performanceHint se utiliza para personalizar la cantidad de almacenamiento en caché que se realiza internamente para mejorar el rendimiento.
El valor por defecto es QStaticText::ModerateCaching.
Nota: Esta función hará que sea necesario recalcular 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 obligará a recalcular 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 (el valor predeterminado), se intentará determinar el formato del texto mediante la función Qt::mightBeRichText(). Si el formato del texto es Qt::PlainText, entonces el texto se mostrará tal cual, mientras que se interpretará como HTML si el formato es Qt::RichText. Las etiquetas HTML que alteran la fuente del texto, su color o su disposición son soportadas por QStaticText.
Nota: Esta función hará que sea necesario recalcular la disposición 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 en la dirección textOption.
Véase también textOption().
void QStaticText::setTextWidth(qreal textWidth)
Establece la anchura preferida para este QStaticText. Si el texto es más ancho que la anchura especificada, se dividirá en varias líneas y crecerá verticalmente. Si el texto no puede dividirse en varias líneas, será mayor que la anchura especificada textWidth.
Si el ancho de texto preferido es negativo, el texto no tendrá límites.
Utilice 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)
Intercambia esta instancia de texto estático con 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 de 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 la anchura preferida para este QStaticText.
Véase también setTextWidth().
bool QStaticText::operator!=(const QStaticText &other) const
Compara other con este QStaticText. Devuelve true si los textos, fuentes o tamaños máximos son diferentes.
QStaticText &QStaticText::operator=(const QStaticText &other)
Asigna other a este QStaticText.
bool QStaticText::operator==(const QStaticText &other) const
Compara other con este QStaticText. Devuelve true si los textos, fuentes y 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.