Back to Qt.io
Contact Us Blog Download Qt
En esta página

QSyntaxHighlighter Class

La clase QSyntaxHighlighter le permite definir reglas de resaltado de sintaxis, y además puede utilizar la clase para consultar el formato actual de un documento o los datos de usuario. Más...

Cabecera: #include <QSyntaxHighlighter>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Hereda: QObject

Nota: Todas las funciones de esta clase son reentrantes.

Funciones Públicas

QSyntaxHighlighter(QObject *parent)
QSyntaxHighlighter(QTextDocument *parent)
virtual ~QSyntaxHighlighter()
QTextDocument *document() const
void setDocument(QTextDocument *doc)

Ranuras Públicas

void rehighlight()
void rehighlightBlock(const QTextBlock &block)

Funciones Protegidas

QTextBlock currentBlock() const
int currentBlockState() const
QTextBlockUserData *currentBlockUserData() const
QTextCharFormat format(int position) const
virtual void highlightBlock(const QString &text) = 0
int previousBlockState() const
void setCurrentBlockState(int newState)
void setCurrentBlockUserData(QTextBlockUserData *data)
void setFormat(int start, int count, const QTextCharFormat &format)
void setFormat(int start, int count, const QColor &color)
void setFormat(int start, int count, const QFont &font)

Descripción detallada

La clase QSyntaxHighlighter es una clase base para implementar resaltadores de sintaxis QTextDocument. Un resaltador de sintaxis resalta automáticamente partes del texto en un QTextDocument. Los resaltadores de sintaxis se utilizan a menudo cuando el usuario está introduciendo texto en un formato específico (por ejemplo código fuente) y ayudan al usuario a leer el texto e identificar errores de sintaxis.

Para proporcionar tu propio resaltador de sintaxis, debes subclasificar QSyntaxHighlighter y reimplementar highlightBlock().

Cuando crees una instancia de tu subclase QSyntaxHighlighter, pásale el QTextDocument al que quieres que se aplique el resaltado de sintaxis. Por ejemplo:

QTextEdit *editor = new QTextEdit;
MyHighlighter *highlighter = new MyHighlighter(editor->document());

Después de esto tu función highlightBlock() será llamada automáticamente cuando sea necesario. Usa tu función highlightBlock() para aplicar formato (por ejemplo, establecer la fuente y el color) al texto que se le pasa. QSyntaxHighlighter provee la función setFormat() que aplica un determinado QTextCharFormat en el bloque de texto actual. Por ejemplo:

void MyHighlighter::highlightBlock(const QString &text)
{
    QTextCharFormat myClassFormat;
    myClassFormat.setFontWeight(QFont::Bold);
    myClassFormat.setForeground(Qt::darkMagenta);

    QRegularExpression expression("\\bMy[A-Za-z]+\\b");
    QRegularExpressionMatchIterator i = expression.globalMatch(text);
    while (i.hasNext()) {
        QRegularExpressionMatch match = i.next();
        setFormat(match.capturedStart(), match.capturedLength(), myClassFormat);
    }
}

Algunas sintaxis pueden tener construcciones que abarcan varios bloques de texto. Por ejemplo, un resaltador de sintaxis de C++ debería poder hacer frente a /*...* / comentarios multilínea. Para tratar estos casos es necesario conocer el estado final del bloque de texto anterior (por ejemplo, "en comentario").

Dentro de su implementación de highlightBlock() puede consultar el estado final del bloque de texto anterior utilizando la función previousBlockState(). Después de analizar el bloque, puede guardar el último estado utilizando setCurrentBlockState().

Las funciones currentBlockState() y previousBlockState() devuelven un valor int. Si no se establece ningún estado, el valor devuelto es -1. Puede designar cualquier otro valor para identificar un estado determinado utilizando la función setCurrentBlockState(). Una vez establecido el estado, QTextBlock mantiene ese valor hasta que se vuelve a establecer o hasta que se borra el párrafo de texto correspondiente.

Por ejemplo, si estás escribiendo un simple resaltador de sintaxis C++, podrías designar 1 para significar "en comentario":

QTextCharFormat multiLineCommentFormat;
multiLineCommentFormat.setForeground(Qt::red);

QRegularExpression startExpression("/\\*");
QRegularExpression endExpression("\\*/");

setCurrentBlockState(0);

int startIndex = 0;
if (previousBlockState() != 1)
    startIndex = text.indexOf(startExpression);

while (startIndex >= 0) {
    QRegularExpressionMatch endMatch;
    int endIndex = text.indexOf(endExpression, startIndex, &endMatch);
    int commentLength;
    if (endIndex == -1) {
        setCurrentBlockState(1);
        commentLength = text.length() - startIndex;
    } else {
        commentLength = endIndex - startIndex
                        + endMatch.capturedLength();
    }
    setFormat(startIndex, commentLength, multiLineCommentFormat);
    startIndex = text.indexOf(startExpression,
                              startIndex + commentLength);
}

En el ejemplo anterior, primero establecemos el estado del bloque actual en 0. A continuación, si el bloque anterior terminaba dentro de un comentario, resaltamos desde el principio del bloque actual (startIndex = 0). En caso contrario, buscamos la expresión de inicio indicada. Si la expresión final especificada no se encuentra en el bloque de texto, cambiamos el estado actual del bloque llamando a setCurrentBlockState(), y nos aseguramos de que el resto del bloque queda resaltado.

Además, puede consultar el formato actual y los datos de usuario mediante las funciones format() y currentBlockUserData() respectivamente. También puede adjuntar datos de usuario al bloque de texto actual mediante la función setCurrentBlockUserData(). QTextBlockUserData puede utilizarse para almacenar ajustes personalizados. En el caso del resaltado de sintaxis, resulta especialmente interesante como almacenamiento en caché de información que puede averiguar mientras analiza el texto del párrafo. Para ver un ejemplo, consulte la documentación de setCurrentBlockUserData().

Véase también QTextDocument y Ejemplo de resaltador de sintaxis.

Documentación de funciones miembro

[explicit] QSyntaxHighlighter::QSyntaxHighlighter(QObject *parent)

Construye un QSyntaxHighlighter con la dirección parent.

Si el padre es un QTextEdit, instala el resaltador de sintaxis en el documento padre. El QTextEdit especificado también se convierte en el propietario del QSyntaxHighlighter.

[explicit] QSyntaxHighlighter::QSyntaxHighlighter(QTextDocument *parent)

Construye un QSyntaxHighlighter y lo instala en parent. El QTextDocument especificado también se convierte en el propietario del QSyntaxHighlighter.

[virtual noexcept] QSyntaxHighlighter::~QSyntaxHighlighter()

Destructor. Desinstala este resaltador de sintaxis del documento de texto.

[protected] QTextBlock QSyntaxHighlighter::currentBlock() const

Devuelve el bloque de texto actual.

[protected] int QSyntaxHighlighter::currentBlockState() const

Devuelve el estado del bloque de texto actual. Si no se establece ningún valor, el valor devuelto es -1.

Véase también setCurrentBlockState().

[protected] QTextBlockUserData *QSyntaxHighlighter::currentBlockUserData() const

Devuelve el objeto QTextBlockUserData adjuntado previamente al bloque de texto actual.

Véase también QTextBlock::userData() y setCurrentBlockUserData().

QTextDocument *QSyntaxHighlighter::document() const

Devuelve la dirección QTextDocument en la que está instalado este resaltador de sintaxis.

Véase también setDocument().

[protected] QTextCharFormat QSyntaxHighlighter::format(int position) const

Devuelve el formato en position dentro del bloque de texto actual del resaltador de sintaxis.

Véase también setFormat().

[pure virtual protected] void QSyntaxHighlighter::highlightBlock(const QString &text)

Resalta el bloque de texto dado. El motor de texto enriquecido llama a esta función cuando es necesario, es decir, en los bloques de texto que han cambiado.

Para proporcionar su propio resaltado de sintaxis, debe subclasificar QSyntaxHighlighter y reimplementar highlightBlock(). En su reimplementación debe analizar el bloque text y llamar a setFormat() tantas veces como sea necesario para aplicar los cambios de fuente y color que necesite. Por ejemplo:

void MyHighlighter::highlightBlock(const QString &text)
{
    QTextCharFormat myClassFormat;
    myClassFormat.setFontWeight(QFont::Bold);
    myClassFormat.setForeground(Qt::darkMagenta);

    QRegularExpression expression("\\bMy[A-Za-z]+\\b");
    QRegularExpressionMatchIterator i = expression.globalMatch(text);
    while (i.hasNext()) {
        QRegularExpressionMatch match = i.next();
        setFormat(match.capturedStart(), match.capturedLength(), myClassFormat);
    }
}

En Detailed Description encontrará ejemplos de uso de setCurrentBlockState(), currentBlockState() y previousBlockState() para manejar sintaxis con construcciones que abarcan varios bloques de texto.

Véase también previousBlockState(), setFormat() y setCurrentBlockState().

[protected] int QSyntaxHighlighter::previousBlockState() const

Devuelve el estado final del bloque de texto anterior al bloque actual del resaltador de sintaxis. Si no se estableció ningún valor previamente, el valor devuelto es -1.

Véase también highlightBlock() y setCurrentBlockState().

[slot] void QSyntaxHighlighter::rehighlight()

Vuelve a aplicar el resaltado a todo el documento.

Véase también rehighlightBlock().

[slot] void QSyntaxHighlighter::rehighlightBlock(const QTextBlock &block)

Vuelve a aplicar el resaltado a la dirección QTextBlock block .

Véase también rehighlight().

[protected] void QSyntaxHighlighter::setCurrentBlockState(int newState)

Establece el estado del bloque de texto actual en newState.

Véase también currentBlockState() y highlightBlock().

[protected] void QSyntaxHighlighter::setCurrentBlockUserData(QTextBlockUserData *data)

Adjunta el data dado al bloque de texto actual. La propiedad se pasa al documento de texto subyacente, es decir, el objeto QTextBlockUserData proporcionado se borrará si se borra el bloque de texto correspondiente.

QTextBlockUserData puede utilizarse para almacenar configuraciones personalizadas. En el caso del resaltado de sintaxis, resulta especialmente interesante como caché para almacenar información que puede obtenerse mientras se analiza el texto del párrafo.

Por ejemplo, mientras analiza el texto, puede realizar un seguimiento de los caracteres de paréntesis que encuentre ('{[(' y similares), y almacenar su posición relativa y el QChar real en una clase simple derivada de QTextBlockUserData:

struct ParenthesisInfo
{
    QChar character;
    int position;
};

struct BlockData : public QTextBlockUserData
{
    QList<ParenthesisInfo> parentheses;
};

Durante la navegación del cursor en el editor asociado, puede preguntar al QTextBlock actual (recuperado usando la función QTextCursor::block()) si tiene un objeto de datos de usuario establecido y lanzarlo a su objeto BlockData. A continuación, puede comprobar si la posición actual del cursor coincide con una posición de paréntesis registrada previamente y, en función del tipo de paréntesis (apertura o cierre), encontrar el siguiente paréntesis de apertura o cierre en el mismo nivel.

De esta forma puede hacer una coincidencia visual de paréntesis y resaltar desde la posición actual del cursor hasta el paréntesis coincidente. Esto hace más fácil detectar un paréntesis que falta en el código y encontrar dónde está el paréntesis de apertura/cierre correspondiente cuando se edita código con muchos paréntesis.

Véase también currentBlockUserData() y QTextBlock::setUserData().

void QSyntaxHighlighter::setDocument(QTextDocument *doc)

Instala el resaltador de sintaxis en la dirección QTextDocument doc . QSyntaxHighlighter sólo puede utilizarse con un documento a la vez.

Véase también document().

[protected] void QSyntaxHighlighter::setFormat(int start, int count, const QTextCharFormat &format)

Esta función se aplica al bloque de texto actual del resaltador de sintaxis (es decir, el texto que se pasa a la función highlightBlock()).

El format especificado se aplica al texto desde la posición start durante una longitud de count caracteres (si count es 0, no se hace nada). Las propiedades de formato definidas en format se combinan en el momento de la visualización con la información de formato almacenada directamente en el documento, por ejemplo, la definida previamente con las funciones de QTextCursor. Tenga en cuenta que el documento en sí no se modifica por el formato establecido a través de esta función.

Véase también format() y highlightBlock().

[protected] void QSyntaxHighlighter::setFormat(int start, int count, const QColor &color)

El color especificado se aplica al bloque de texto actual desde la posición start para una longitud de count caracteres.

Los demás atributos del bloque de texto actual, por ejemplo el tipo de letra y el color de fondo, se restablecen a los valores predeterminados.

Se trata de una función sobrecargada.

Véase también format() y highlightBlock().

[protected] void QSyntaxHighlighter::setFormat(int start, int count, const QFont &font)

El font especificado se aplica al bloque de texto actual desde la posición start para una longitud de count caracteres.

Los demás atributos del bloque de texto actual, por ejemplo el tipo de letra y el color de fondo, se restablecen a los valores predeterminados.

Se trata de una función sobrecargada.

Véase también format() y highlightBlock().

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