Класс QSyntaxHighlighter

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

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

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

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

• 32 открытые функции унаследованы от QObject

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

• 1 открытый слот унаследован от QObject

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

• 9 защищенных функций унаследованы от QObject

Дополнительные унаследованные члены

• 1 свойство унаследовано от QObject
• 2 сигналы унаследованы от QObject
• 11 статических открытых членов, унаследованных от QObject

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

Класс 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() возвращают значение типа int. Если состояние не установлено, возвращаемое значение равно -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(QObject *parent)

Конструктор QSyntaxHighlighter с заданным parent.

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

QSyntaxHighlighter::QSyntaxHighlighter(QTextDocument *parent)

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

[virtual] QSyntaxHighlighter::~QSyntaxHighlighter()

Деструктор. Отключает выделение синтаксиса из документа текста.

[protected] QTextBlock QSyntaxHighlighter::currentBlock() const

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

Эта функция была добавлена в Qt 4.4.

[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().

[slot] void QSyntaxHighlighter::rehighlight()

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

Эта функция была добавлена в Qt 4.2.

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

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

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

Эта функция была добавлена в Qt 4.6.

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

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

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

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

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

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

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

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

struct ParenthesisInfo
{
    QChar char;
    int position;
};

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

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

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

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

void QSyntaxHighlighter::setDocument(QTextDocument *doc)

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

См. также 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().