Класс QSyntaxHighlighter

Класс QSyntaxHighlighter позволяет определять правила подсветки синтаксиса и, кроме того, позволяет запросить текущий формат документа или данные пользователя. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются перевходозащищёнными.

Открытые функции

Открытые слоты

Защищённые функции

Подробное описание

Класс QSyntaxHighlighter — базовый класс для реализации подсветок синтаксиса QTextDocument. Подсветка синтаксиса автоматически подсвечивает части текста в QTextDocument. Подсветки синтаксиса часто используются при вводе пользователем текста в определенном формате (например, исходного кода) и помогают пользователю читать текст и выявлять синтаксические ошибки.

Для предоставления собственной подсветки синтаксиса необходимо создать подкласс QSyntaxHighlighter и переопределить highlightBlock().

При создании экземпляра подкласса QSyntaxHighlighter передайте ему QTextDocument, к которому должна применяться подсветка синтаксиса. Например:

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

После этого ваша функция highlightBlock() будет вызываться автоматически при необходимости. Используйте функцию highlightBlock() для применения форматирования (например, настройки шрифта и цвета) к тексту, который передаётся в неё. QSyntaxHighlighter предоставляет функцию setFormat(), которая применяет заданный QTextCharFormat к текущему блоку текста. Например:

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);
    }
}

Некоторые синтаксисы могут иметь конструкции, охватывающие несколько блоков текста. Например, подсветка синтаксиса C++ должна уметь обрабатывать /*...*/ многострочные комментарии. Для решения таких случаев необходимо знать конечное состояние предыдущего блока текста (например, "в комментарии").

Внутри реализации highlightBlock() можно запросить конечное состояние предыдущего блока текста, используя функцию previousBlockState(). После обработки блока можно сохранить последнее состояние, используя setCurrentBlockState().

Функции currentBlockState() и previousBlockState() возвращают целое значение. Если состояние не установлено, возвращаемое значение равно -1. Вы можете назначить любое другое значение для идентификации любого заданного состояния, используя функцию setCurrentBlockState(). После установки состояние QTextBlock сохраняет это значение до тех пор, пока оно не будет установлено повторно или пока соответствующий абзац текста не будет удален.

Например, если вы пишете простую подсветку синтаксиса C++, вы можете назначить 1 для обозначения "в комментарии":

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);
}

В примере выше, мы сначала устанавливаем состояние текущего блока в 0. Затем, если предыдущий блок завершился внутри комментария, мы подсвечиваем текст с начала текущего блока (startIndex = 0). В противном случае мы ищем заданный начальный фрагмент. Если заданный конечный фрагмент не найден в блоке текста, мы изменяем состояние текущего блока, вызывая setCurrentBlockState(), и убеждаемся, что остальная часть блока подсвечивается.

Кроме того, вы можете запросить текущее форматирование и данные пользователя, используя функции format() и currentBlockUserData() соответственно. Вы также можете добавить данные пользователя к текущему блоку текста, используя функцию setCurrentBlockUserData(). QTextBlockUserData может использоваться для хранения пользовательских настроек. В случае подсветки синтаксиса, это особенно интересно как хранилище кэша для информации, которую вы можете получить во время анализа текста абзаца. Пример см. в документации setCurrentBlockUserData().

См. также QTextDocument и Пример подсветки синтаксиса.

Документация по функциям-членам

QSyntaxHighlighter::QSyntaxHighlighter(QTextDocument *parent)

Создаёт QSyntaxHighlighter и устанавливает его на parent. Указанный QTextDocument также становится владельцем QSyntaxHighlighter.

QSyntaxHighlighter::QSyntaxHighlighter(QObject *parent)

Создаёт QSyntaxHighlighter с заданным parent.

Если родитель — QTextEdit, он устанавливает подсветку синтаксиса на документ родителя. Указанный QTextEdit также становится владельцем QSyntaxHighlighter.

[slot] void QSyntaxHighlighter::rehighlight()

Переприменяет подсветку ко всему документу.

См. также rehighlightBlock().

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

Переприменяет подсветку к заданному QTextBlock block.

См. также rehighlight().

[virtual] QSyntaxHighlighter::~QSyntaxHighlighter()

Деструктор. Удаляет эту подсветку синтаксиса из документа.

[protected] QTextBlock QSyntaxHighlighter::currentBlock() const

Возвращает текущий блок текста.

[protected] int QSyntaxHighlighter::currentBlockState() const

Возвращает состояние текущего блока текста. Если значение не установлено, возвращаемое значение равно -1.

См. также setCurrentBlockState().

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

Возвращает объект QTextBlockUserData, ранее присоединённый к текущему блоку текста.

См. также QTextBlock::userData() и setCurrentBlockUserData().

QTextDocument *QSyntaxHighlighter::document() const

Возвращает QTextDocument, на котором установлен этот синтаксический выделение.

См. также setDocument().

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

Возвращает форматирование в позиции position внутри текущего блока текста синтаксического выделения.

См. также setFormat().

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

Выделяет заданный блок текста. Эта функция вызывается по мере необходимости движком форматированного текста, т.е. для блоков текста, которые изменились.

Для реализации собственного синтаксического выделения необходимо создать подкласс QSyntaxHighlighter и переопределить метод highlightBlock(). В своём переопределении необходимо проанализировать блок text и вызвать setFormat() столько раз, сколько необходимо, для применения требуемых изменений шрифта и цвета. Например:

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);
    }
}

См. Подробное описание для примеров использования setCurrentBlockState(), currentBlockState() и previousBlockState() для обработки синтаксисов со структурами, охватывающими несколько блоков текста

См. также previousBlockState(), setFormat() и setCurrentBlockState().

[protected] int QSyntaxHighlighter::previousBlockState() const

Возвращает конечное состояние блока текста, предшествующего текущему блоку синтаксического выделения. Если ранее значение не устанавливалось, возвращается значение -1.

См. также highlightBlock() и setCurrentBlockState().

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

Устанавливает состояние текущего блока текста в значение newState.

См. также currentBlockState() и highlightBlock().

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

Присоединяет указанный data к текущему блоку текста. Владение передаётся в подлежащий документу, т.е. предоставленный объект QTextBlockUserData будет удалён, если соответствующий блок текста будет удалён.

QTextBlockUserData можно использовать для хранения пользовательских настроек. В случае синтаксического выделения особенно интересно, как хранилище кэша для информации, которую вы можете получить при разборе текста абзаца.

Например, при разборе текста вы можете отслеживать скобки, которые вы встречаете ('{[(' и т.п.), и хранить их относительную позицию и фактический QChar в простом классе, производном от QTextBlockUserData:

struct ParenthesisInfo
{
    QChar character;
    int position;
};

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

Во время навигации курсора в связанном редакторе вы можете спросить текущий QTextBlock (полученный с помощью функции QTextCursor::block()), есть ли в нём установленный объект пользовательских данных, и привести его к своему BlockData объекту. Затем вы можете проверить, соответствует ли текущая позиция курсора ранее записанной позиции скобки, и в зависимости от типа скобки (открывающая или закрывающая) найти следующую открывающую или закрывающую скобку на том же уровне.

Таким образом, вы можете выполнить визуальное сопоставление скобок и выделить от текущей позиции курсора до соответствующей скобки. Это облегчит обнаружение отсутствующей скобки в вашем коде и нахождение соответствующей открывающей/закрывающей скобки при редактировании кода, интенсивно использующего скобки.

См. также currentBlockUserData() и QTextBlock::setUserData().

void QSyntaxHighlighter::setDocument(QTextDocument *doc)

Устанавливает синтаксическое выделение на заданный QTextDocument doc. QSyntaxHighlighter может использоваться только с одним документом за раз.

См. также document().

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

Эта функция применяется к текущему блоку текста синтаксического выделения (т.е. тексту, переданному в функцию highlightBlock()).

Указанное format применяется к тексту с позиции start на длине count символов (если count равно 0, ничего не делается). Свойства форматирования, установленные в format, объединяются во время отображения с информацией о форматировании, хранящейся непосредственно в документе, например, предварительно установленной с помощью функций QTextCursor. Обратите внимание, что сам документ не изменяется форматированием, установленным через эту функцию.

См. также format() и highlightBlock().

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

Это перегруженная функция.

Указанный color применяется к текущему блоку текста с позиции start на длине count символов.

Другие атрибуты текущего блока текста, например, шрифт и цвет фона, сбрасываются до значений по умолчанию.

См. также format() и highlightBlock().

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

Это перегруженная функция.

Указанный font применяется к текущему блоку текста с позиции start на длине count символов.

Другие атрибуты текущего блока текста, например, шрифт и цвет фона, сбрасываются до значений по умолчанию.

См. также format() и highlightBlock().