Класс QSyntaxHighlighter

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

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

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

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

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

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

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

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

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

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

• 1 свойство, унаследованное от QObject
• 2 сигнала, унаследованные от QObject
• 11 статических открытых членов, унаследованных от 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);
    QString pattern = "\\bMy[A-Za-z]+\\b";

    QRegExp expression(pattern);
    int index = text.indexOf(expression);
    while (index >= 0) {
        int length = expression.matchedLength();
        setFormat(index, length, myClassFormat);
        index = text.indexOf(expression, index + length);
    }
}

Некоторые синтаксисы могут иметь конструкции, охватывающие несколько блоков текста. Например, подсветка синтаксиса C++ должна уметь обрабатывать /*...*/ многострочные комментарии. Для обработки таких случаев необходимо знать конечное состояние предыдущего блока текста (например, "в комментарии").

В реализации highlightBlock() вы можете запросить конечное состояние предыдущего блока текста, используя функцию previousBlockState(). После анализа блока вы можете сохранить последнее состояние, используя setCurrentBlockState().

Функции currentBlockState() и previousBlockState() возвращают значение типа int. Если состояние не установлено, возвращаемое значение равно -1. Вы можете назначить любое другое значение для идентификации любого заданного состояния, используя функцию setCurrentBlockState(). После установки состояния QTextBlock сохраняет это значение до тех пор, пока оно не будет установлено снова или пока соответствующий абзац текста не будет удалён.

Например, если вы пишете подсветку синтаксиса для C++, вы можете назначить 1, чтобы обозначить "в комментарии":

QTextCharFormat multiLineCommentFormat;
multiLineCommentFormat.setForeground(Qt::red);

QRegExp startExpression("/\\*");
QRegExp endExpression("\\*/");

setCurrentBlockState(0);

int startIndex = 0;
if (previousBlockState() != 1)
    startIndex = text.indexOf(startExpression);

while (startIndex >= 0) {
   int endIndex = text.indexOf(endExpression, startIndex);
   int commentLength;
   if (endIndex == -1) {
       setCurrentBlockState(1);
       commentLength = text.length() - startIndex;
   } else {
       commentLength = endIndex - startIndex
                       + endExpression.matchedLength();
   }
   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);
    QString pattern = "\\bMy[A-Za-z]+\\b";

    QRegExp expression(pattern);
    int index = text.indexOf(expression);
    while (index >= 0) {
        int length = expression.matchedLength();
        setFormat(index, length, myClassFormat);
        index = text.indexOf(expression, index + length);
     }
 }

Некоторые синтаксисы могут иметь конструкции, охватывающие несколько блоков текста. Например, выделение синтаксиса C++ должно уметь обрабатывать /*...*/ многострочные комментарии. Для обработки этих случаев необходимо знать конечное состояние предыдущего блока текста (например, "в комментарии").

Внутри вашей реализации highlightBlock() вы можете запросить конечное состояние предыдущего блока текста с помощью функции previousBlockState(). После анализа блока вы можете сохранить последнее состояние с помощью setCurrentBlockState().

Функции currentBlockState() и previousBlockState() возвращают целое число. Если состояние не задано, возвращаемое значение равно -1. Вы можете назначить любое другое значение, чтобы идентифицировать любое заданное состояние, используя функцию setCurrentBlockState(). После установки состояния QTextBlock сохраняет это значение до тех пор, пока оно не будет установлено снова или соответствующий абзац текста не будет удален.

Например, если вы пишете выделение синтаксиса для C++, вы можете назначить 1 для обозначения "в комментарии". Для блока текста, закончившегося посреди комментария, вы установите 1 с помощью setCurrentBlockState, а для других абзацев вы установите 0. В вашем коде анализа, если возвращаемое значение previousBlockState() равно 1, вы будете выделять текст как комментарий C++ до тех пор, пока не достигнете закрывающего */.

См. также 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().