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

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

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

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

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

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

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

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

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

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

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

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

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