Класс QSyntaxHighlighter

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

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

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

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

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

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

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

Статические открытые члены

• 9 статических открытых членов унаследовано от QObject

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

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

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

• 1 свойство унаследовано от 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().