Класс QSyntaxHighlighter

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

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

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

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

• 34 открытых функций, унаследованных от QObject

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

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

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

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

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

• 1 свойство, унаследованное от QObject
• 2 сигнала, унаследованные от QObject
• 1 открытая переменная, унаследованная от QObject
• 10 статических открытых членов, унаследованных от QObject
• 2 защищенные переменные, унаследованные от 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. 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().