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