Класс QSyntaxHighlighter

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

Этот класс был представлен в Qt 4.1.

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

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

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

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

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

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

Класс 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()

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

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

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

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

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

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

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

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

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