En esta página

QTextLayout Class

La clase QTextLayout se utiliza para maquetar y visualizar texto. Más información...

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

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

struct FormatRange
enum CursorMode { SkipCharacters, SkipWords }
(since 6.5) enum GlyphRunRetrievalFlag { RetrieveGlyphIndexes, RetrieveGlyphPositions, RetrieveStringIndexes, RetrieveString, RetrieveAll }
flags GlyphRunRetrievalFlags

Funciones públicas

QTextLayout()
QTextLayout(const QString &text)
QTextLayout(const QString &text, const QFont &font, const QPaintDevice *paintdevice = nullptr)
~QTextLayout()
void beginLayout()
QRectF boundingRect() const
bool cacheEnabled() const
void clearFormats()
void clearLayout()
QTextLine createLine()
Qt::CursorMoveStyle cursorMoveStyle() const
void draw(QPainter *p, const QPointF &pos, const QList<QTextLayout::FormatRange> &selections = QList<FormatRange>(), const QRectF &clip = QRectF()) const
void drawCursor(QPainter *painter, const QPointF &position, int cursorPosition, int width) const
void drawCursor(QPainter *painter, const QPointF &position, int cursorPosition) const
void endLayout()
QFont font() const
QList<QTextLayout::FormatRange> formats() const
QList<QGlyphRun> glyphRuns(int from = -1, int length = -1) const
(since 6.5) QList<QGlyphRun> glyphRuns(int from, int length, QTextLayout::GlyphRunRetrievalFlags retrievalFlags) const
bool isValidCursorPosition(int pos) const
int leftCursorPosition(int oldPos) const
QTextLine lineAt(int i) const
int lineCount() const
QTextLine lineForTextPosition(int pos) const
qreal maximumWidth() const
qreal minimumWidth() const
int nextCursorPosition(int oldPos, QTextLayout::CursorMode mode = SkipCharacters) const
QPointF position() const
int preeditAreaPosition() const
QString preeditAreaText() const
int previousCursorPosition(int oldPos, QTextLayout::CursorMode mode = SkipCharacters) const
int rightCursorPosition(int oldPos) const
void setCacheEnabled(bool enable)
void setCursorMoveStyle(Qt::CursorMoveStyle style)
void setFont(const QFont &font)
void setFormats(const QList<QTextLayout::FormatRange> &formats)
void setPosition(const QPointF &p)
void setPreeditArea(int position, const QString &text)
void setText(const QString &string)
void setTextOption(const QTextOption &option)
QString text() const
const QTextOption &textOption() const

Descripción detallada

Ofrece muchas de las características que se esperan de un motor moderno de maquetación de texto, incluyendo la representación compatible con Unicode, los saltos de línea y la gestión de la posición del cursor. También puede generar y representar maquetaciones independientes del dispositivo, algo que resulta importante para las aplicaciones WYSIWYG.

La clase tiene una API de nivel bastante bajo y, a menos que pretendas implementar tu propia representación de texto para algún widget especializado, probablemente no necesitarás utilizarla directamente.

QTextLayout se puede utilizar tanto con texto sin formato como con texto enriquecido.

QTextLayout se puede utilizar para crear una secuencia de instancias de ` QTextLine ` con anchos determinados y colocarlas de forma independiente en la pantalla. Una vez completado el diseño, estas líneas se pueden dibujar en un dispositivo de dibujo.

El texto que se va a maquetar se puede proporcionar en el constructor o establecer mediante setText().

El diseño puede considerarse como una secuencia de objetos ` QTextLine `; utilice ` createLine()` para crear una instancia de ` QTextLine `, y ` lineAt()` o ` lineForTextPosition()` para recuperar las líneas creadas.

A continuación se muestra un fragmento de código que ilustra la fase de diseño:

int leading = fontMetrics.leading();
qreal height = 0;
textLayout.setCacheEnabled(true);
textLayout.beginLayout();
while (true) {
    QTextLine line = textLayout.createLine();
    if (!line.isValid())
        break;

    line.setLineWidth(lineWidth);
    height += leading;
    line.setPosition(QPointF(0, height));
    height += line.height();
}
textLayout.endLayout();

A continuación, el texto se puede renderizar llamando a la función ` draw()` del diseño:

QPainter painter(this);
textLayout.draw(&painter, QPoint(0, 0));

También es posible dibujar cada línea individualmente, por ejemplo, para dibujar la última línea que cabe en un widget elidido:

QPainter painter(this);
QFontMetrics fontMetrics = painter.fontMetrics();

int lineSpacing = fontMetrics.lineSpacing();
int y = 0;

QTextLayout textLayout(content, painter.font());
textLayout.beginLayout();
while (true) {
    QTextLine line = textLayout.createLine();

    if (!line.isValid())
        break;

    line.setLineWidth(width());
    const int nextLineY = y + lineSpacing;

    if (height() >= nextLineY + lineSpacing) {
        line.draw(&painter, QPoint(0, y));
        y = nextLineY;
    } else {
        const QString lastLine = content.mid(line.textStart());
        const QString elidedLastLine = fontMetrics.elidedText(lastLine, Qt::ElideRight, width());
        painter.drawText(QPoint(0, y + fontMetrics.ascent()), elidedLastLine);
        line = textLayout.createLine();
        break;
    }
}
textLayout.endLayout();

Para una posición determinada en el texto, se puede encontrar una posición válida del cursor con isValidCursorPosition(), nextCursorPosition() y previousCursorPosition().

El propio QTextLayout se puede posicionar con setPosition(); dispone de boundingRect(), minimumWidth() y maximumWidth().

Véase también QStaticText.

Documentación sobre los tipos de miembros

enum QTextLayout::CursorMode

ConstanteValor
QTextLayout::SkipCharacters0
QTextLayout::SkipWords1

[since 6.5] enum QTextLayout::GlyphRunRetrievalFlag
flags QTextLayout::GlyphRunRetrievalFlags

GlyphRunRetrievalFlag especifica los indicadores que se pasan a las funciones ` glyphRuns()` para determinar qué propiedades de la disposición se devuelven en los objetos ` QGlyphRun `. Dado que cada propiedad consume memoria y puede requerir asignaciones adicionales, se recomienda solicitar únicamente aquellas propiedades a las que se vaya a necesitar acceder posteriormente.

ConstanteValorDescripción
QTextLayout::RetrieveGlyphIndexes0x1Recupera los índices de la fuente que corresponden a los glifos.
QTextLayout::RetrieveGlyphPositions0x2Recupera las posiciones relativas de los glifos en el diseño.
QTextLayout::RetrieveStringIndexes0x4Recupera los índices de la cadena original que corresponden a cada uno de los glifos.
QTextLayout::RetrieveString0x8Recupera la cadena original a partir del diseño.
QTextLayout::RetrieveAll0xffffRecupera todas las propiedades disponibles del diseño.

Esta enumeración se introdujo en Qt 6.5.

El tipo `GlyphRunRetrievalFlags` es una definición de tipo (`typedef`) para ` QFlags<GlyphRunRetrievalFlag>`. Almacena una combinación OR de valores de `GlyphRunRetrievalFlag`.

Véase también glyphRuns() y QTextLine::glyphRuns().

Documentación de las funciones miembro

QTextLayout::QTextLayout()

Crea un diseño de texto vacío.

Véase también setText().

QTextLayout::QTextLayout(const QString &text)

Crea un diseño de texto para maquetar el archivo « text » proporcionado.

QTextLayout::QTextLayout(const QString &text, const QFont &font, const QPaintDevice *paintdevice = nullptr)

Crea un diseño de texto para maquetar el text dado con el font especificado.

Todos los cálculos métricos y de diseño se realizarán en función del dispositivo de pintura, paintdevice. Si paintdevice es nullptr, los cálculos se realizarán en métricas de pantalla.

[noexcept] QTextLayout::~QTextLayout()

Elimina el diseño.

void QTextLayout::beginLayout()

Inicia el proceso de maquetación.

Advertencia: esto invalidará la maquetación, por lo que todos los objetos « QTextLine » existentes que hagan referencia al contenido anterior deben descartarse ahora.

Véase también endLayout().

QRectF QTextLayout::boundingRect() const

El rectángulo más pequeño que contiene todas las líneas del diseño.

bool QTextLayout::cacheEnabled() const

Devuelve « true » si la información completa del diseño está almacenada en caché; en caso contrario, devuelve « false ».

Véase también setCacheEnabled().

void QTextLayout::clearFormats()

Borra la lista de formatos adicionales compatibles con el diseño de texto.

Véase también formats() y setFormats().

void QTextLayout::clearLayout()

Borra la información de línea del diseño. Tras llamar a esta función, ` lineCount()` devuelve 0.

Advertencia: Esto invalidará el diseño, por lo que todos los objetos ` QTextLine ` existentes que hagan referencia al contenido anterior deberán descartarse.

QTextLine QTextLayout::createLine()

Devuelve una nueva línea de texto para maquetar si hay texto que insertar en la maquetación; en caso contrario, devuelve una línea de texto no válida.

La maquetación de texto crea un nuevo objeto de línea que comienza después de la última línea de la maquetación, o al principio si la maquetación está vacía. La maquetación mantiene un cursor interno, y cada línea se rellena con texto a partir de la posición del cursor cuando se llama a la función QTextLine::setLineWidth().

Una vez llamada QTextLine::setLineWidth(), se puede crear una nueva línea y rellenarla con texto. Al repetir este proceso, se maquetará todo el bloque de texto contenido en ` QTextLayout`. Si no queda texto por insertar en la maquetación, el objeto ` QTextLine ` devuelto no será válido (isValid() devolverá «false»).

Qt::CursorMoveStyle QTextLayout::cursorMoveStyle() const

El estilo de movimiento del cursor de este QTextLayout. El valor predeterminado es Qt::LogicalMoveStyle.

Véase también setCursorMoveStyle().

void QTextLayout::draw(QPainter *p, const QPointF &pos, const QList<QTextLayout::FormatRange> &selections = QList<FormatRange>(), const QRectF &clip = QRectF()) const

Dibuja todo el diseño en el «painter» p en la posición especificada por pos. El diseño renderizado incluye el selections indicado y se recorta dentro del rectángulo especificado por clip.

void QTextLayout::drawCursor(QPainter *painter, const QPointF &position, int cursorPosition, int width) const

Dibuja un cursor de texto con el lápiz actual y el « width » especificado en la « position » indicada, utilizando el « painter » especificado. La posición correspondiente dentro del texto se especifica mediante « cursorPosition ».

void QTextLayout::drawCursor(QPainter *painter, const QPointF &position, int cursorPosition) const

Dibuja un cursor de texto con el lápiz actual en el punto dado ` position `, utilizando el ` painter ` especificado. La posición correspondiente dentro del texto viene determinada por ` cursorPosition`.

Se trata de una función sobrecargada.

void QTextLayout::endLayout()

Finaliza el proceso de maquetación.

Véase también beginLayout().

QFont QTextLayout::font() const

Devuelve la fuente actual que se utiliza para el diseño, o una fuente predeterminada si no se ha establecido ninguna.

Véase también setFont().

QList<QTextLayout::FormatRange> QTextLayout::formats() const

Devuelve la lista de formatos adicionales compatibles con el diseño de texto.

Véase también setFormats() y clearFormats().

QList<QGlyphRun> QTextLayout::glyphRuns(int from = -1, int length = -1) const

Devuelve los índices y las posiciones de todos los glifos correspondientes a los caracteres length a partir de la posición from en este QTextLayout. Se trata de una función que consume muchos recursos, por lo que no debe invocarse en un contexto en el que el tiempo sea un factor crítico.

Si from es menor que cero, la secuencia de glifos comenzará en el primer carácter del diseño. Si length es menor que cero, abarcará toda la cadena desde la posición inicial.

Nota: Esto equivale a llamar a `glyphRuns(from, length, QTextLayout::GlyphRunRetrievalFlag::GlyphIndexes | QTextLayout::GlyphRunRetrievalFlag::GlyphPositions)`.

Esta es una función sobrecargada.

Véase también draw() y QPainter::drawGlyphRun().

[since 6.5] QList<QGlyphRun> QTextLayout::glyphRuns(int from, int length, QTextLayout::GlyphRunRetrievalFlags retrievalFlags) const

Devuelve los índices y las posiciones de todos los glifos correspondientes a los caracteres length a partir de la posición from en este QTextLayout. Se trata de una función que consume muchos recursos, por lo que no debe llamarse en un contexto en el que el tiempo sea un factor crítico.

Si from es menor que cero, la secuencia de glifos comenzará en el primer carácter del diseño. Si length es menor que cero, abarcará toda la cadena desde la posición inicial.

retrievalFlags especifica qué propiedades de QGlyphRun se recuperarán del diseño. Para minimizar las asignaciones y el consumo de memoria, debe configurarse de modo que solo incluya las propiedades a las que se vaya a acceder posteriormente.

Se trata de una función sobrecargada.

Esta función se introdujo en Qt 6.5.

Véase también ` draw()` y ` QPainter::drawGlyphRun()`.

bool QTextLayout::isValidCursorPosition(int pos) const

Devuelve « true » si la posición « pos » es una posición válida del cursor.

En un contexto Unicode, algunas posiciones del texto no son posiciones válidas del cursor, ya que se encuentran dentro de un sustituto Unicode o de un grupo de grafemas.

Un clúster de grafemas es una secuencia de dos o más caracteres Unicode que forman una entidad indivisible en la pantalla. Por ejemplo, el carácter latino `Ä' puede representarse en Unicode mediante dos caracteres: `A' (0x41) y la diéresis combinatoria (0x308). Un cursor de texto solo puede situarse válidamente antes o después de estos dos caracteres, nunca entre ellos, ya que eso no tendría sentido. En las lenguas índicas, cada sílaba forma un grupo de grafemas.

int QTextLayout::leftCursorPosition(int oldPos) const

Devuelve la posición del cursor a la izquierda de oldPos, justo al lado de este. Depende de la posición visual de los caracteres, tras la reordenación bidireccional.

Véase también ` rightCursorPosition()` y ` previousCursorPosition()`.

QTextLine QTextLayout::lineAt(int i) const

Devuelve la línea número i del texto en este diseño de texto.

Véase también lineCount() y lineForTextPosition().

int QTextLayout::lineCount() const

Devuelve el número de líneas de este diseño de texto.

Véase también lineAt().

QTextLine QTextLayout::lineForTextPosition(int pos) const

Devuelve la línea que contiene la posición del cursor especificada por pos.

Véanse también « isValidCursorPosition()» y « lineAt()».

qreal QTextLayout::maximumWidth() const

El ancho máximo al que podría expandirse el diseño; se trata, básicamente, del ancho total del texto.

Advertencia: Esta función solo devuelve un valor válido una vez que se ha realizado el diseño.

Véase también minimumWidth().

qreal QTextLayout::minimumWidth() const

El ancho mínimo que necesita la disposición. Se trata del ancho de la subcadena más pequeña de la disposición que no se puede dividir.

Advertencia: Esta función solo devuelve un valor válido una vez que se ha completado la distribución.

Véase también maximumWidth().

int QTextLayout::nextCursorPosition(int oldPos, QTextLayout::CursorMode mode = SkipCharacters) const

Devuelve la siguiente posición válida del cursor después de oldPos que respete la posición del cursor indicada mode. Devuelve el valor de oldPos si oldPos no es una posición válida del cursor.

Véanse también isValidCursorPosition() y previousCursorPosition().

QPointF QTextLayout::position() const

La posición global del diseño. Es independiente del rectángulo delimitador y del proceso de diseño.

Véase también setPosition().

int QTextLayout::preeditAreaPosition() const

Devuelve la posición del área en la maquetación del texto que se procesará antes de que se realice la edición.

Véase también preeditAreaText().

QString QTextLayout::preeditAreaText() const

Devuelve el texto que se inserta en el diseño antes de que se realice la edición.

Véase también preeditAreaPosition().

int QTextLayout::previousCursorPosition(int oldPos, QTextLayout::CursorMode mode = SkipCharacters) const

Devuelve la primera posición válida del cursor antes de oldPos que respete la posición del cursor indicada mode. Devuelve el valor de oldPos si oldPos no es una posición válida del cursor.

Véase también isValidCursorPosition() y nextCursorPosition().

int QTextLayout::rightCursorPosition(int oldPos) const

Devuelve la posición del cursor a la derecha de oldPos, justo al lado. Depende de la posición visual de los caracteres, tras la reordenación bidireccional.

Véanse también ` leftCursorPosition()` y ` nextCursorPosition()`.

void QTextLayout::setCacheEnabled(bool enable)

Habilita el almacenamiento en caché de toda la información de maquetación si enable es verdadero; en caso contrario, deshabilita el almacenamiento en caché de la maquetación. Normalmente, QTextLayout descarta la mayor parte de la información de maquetación tras una llamada a endLayout() para reducir el consumo de memoria. Sin embargo, si deseas dibujar el texto maquetado inmediatamente después, habilitar el almacenamiento en caché podría acelerar el dibujo de forma significativa.

Véase también cacheEnabled().

void QTextLayout::setCursorMoveStyle(Qt::CursorMoveStyle style)

Establece el estilo de movimiento del cursor visual en el valor indicado en style. Si el QTextLayout está respaldado por un documento, puedes ignorar esta opción y utilizar la que se indica en QTextDocument; esta opción está pensada para widgets como QLineEdit o widgets personalizados sin un QTextDocument. El valor por defecto es Qt::LogicalMoveStyle.

Véase también cursorMoveStyle().

void QTextLayout::setFont(const QFont &font)

Establece la fuente del diseño en la especificada en font. El diseño queda invalidado y debe volver a generarse.

Véase también font().

void QTextLayout::setFormats(const QList<QTextLayout::FormatRange> &formats)

Establece los formatos adicionales admitidos por el diseño de texto en formats. Los formatos se aplican sin modificar el texto del área de preedición.

Véase también formats() y clearFormats().

void QTextLayout::setPosition(const QPointF &p)

Cambia la disposición del texto para que apunte a p.

Véase también position().

void QTextLayout::setPreeditArea(int position, const QString &text)

Establece los valores de « position » y « text » del área del diseño que se procesa antes de que se realice la edición. El diseño queda invalidado y debe volver a maquetarse.

Véase también preeditAreaPosition() y preeditAreaText().

void QTextLayout::setText(const QString &string)

Establece el texto del diseño en el string especificado. El diseño queda invalidado y debe volver a generarse.

Ten en cuenta que, si utilizas este ` QTextLayout ` como parte de un ` QTextDocument `, este método no tendrá ningún efecto.

Véase también text().

void QTextLayout::setTextOption(const QTextOption &option)

Establece la estructura de opciones de texto que controla el proceso de maquetación en el valor indicado: option.

Véase también textOption().

QString QTextLayout::text() const

Devuelve el texto del diseño.

Véase también setText().

const QTextOption &QTextLayout::textOption() const

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

Véase también setTextOption().

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