Класс QTextLayout

Класс QTextLayout используется для выкладки и отрисовки текста. Подробнее...

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

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

Публичные типы

Публичные функции

Подробное описание

Он предоставляет множество функций, ожидаемых от современного движка выкладки текста, включая поддержку Unicode, перенос слов и обработку позиционирования курсора. Он также может создавать и отрисовывать независимую от устройства выкладку, что важно для WYSIWYG-приложений.

Класс имеет довольно низкоуровневый API, и если вы не планируете реализовывать собственное рендеринг текста для какого-то специализированного виджета, вам, вероятно, не нужно его использовать напрямую.

QTextLayout можно использовать с обычным и форматированным текстом.

QTextLayout можно использовать для создания последовательности объектов QTextLine с заданными ширинами и независимо позиционировать их на экране. После завершения выкладки эти строки можно отрисовать на устройстве рисования.

Текст для выкладки можно указать в конструкторе или установить с помощью setText().

Выкладку можно рассматривать как последовательность объектов QTextLine; используйте createLine() для создания экземпляра QTextLine, а lineAt() или lineForTextPosition() для получения созданных строк.

Вот фрагмент кода, демонстрирующий фазу выкладки:

int leading = fontMetrics.leading();
qreal height = 0;
textLayout.setCacheEnabled(true);
textLayout.beginLayout();
while (1) {
    QTextLine line = textLayout.createLine();
    if (!line.isValid())
        break;

    line.setLineWidth(lineWidth);
    height += leading;
    line.setPosition(QPointF(0, height));
    height += line.height();
}
textLayout.endLayout();

Затем текст можно отобразить, вызвав функцию выкладки draw():

QPainter painter(this);
textLayout.draw(&painter, QPoint(0, 0));

Для заданной позиции в тексте можно найти допустимую позицию курсора с помощью isValidCursorPosition(), nextCursorPosition() и previousCursorPosition().

Сам QTextLayout можно позиционировать с помощью setPosition; он имеет boundingRect, minimumWidth() и maximumWidth().

См. также QStaticText.

Документация по типам членов

enum QTextLayout::CursorMode

Документация функций-членов

[since 5.13] QTextLayout::QTextLayout(const QString &text, const QFont &font, const QPaintDevice *paintdevice = nullptr)

Создаёт макет текста для заданного text с указанным font.

Все метрические и расчётные операции макета выполняются в отношении устройства рисования paintdevice. Если paintdevice nullptr, расчёт выполняется в метриках экрана.

Данная функция была добавлена в Qt 5.13.

QTextLayout::QTextLayout(const QString &text)

Создаёт макет текста для заданного text.

QTextLayout::QTextLayout()

Создаёт пустой макет текста.

См. также setText().

QTextLayout::~QTextLayout()

Уничтожает макет.

void QTextLayout::beginLayout()

Начинает процесс макета.

Предупреждение: Это действие делает макет недействительным, поэтому все существующие объекты QTextLine, которые ссылаются на предыдущее содержимое, должны быть удалены.

См. также endLayout().

QRectF QTextLayout::boundingRect() const

Самый маленький прямоугольник, содержащий все строки в макете.

bool QTextLayout::cacheEnabled() const

Возвращает true если вся информация о макете кэшируется, в противном случае возвращает false.

См. также setCacheEnabled().

[since 5.6] void QTextLayout::clearFormats()

Очищает список дополнительных форматов, поддерживаемых макетом текста.

Данная функция была добавлена в Qt 5.6.

См. также formats() и setFormats().

void QTextLayout::clearLayout()

Очищает информацию о строках в макете. После вызова этой функции lineCount() возвращает 0.

Предупреждение: Это действие делает макет недействительным, поэтому все существующие объекты QTextLine, которые ссылаются на предыдущее содержимое, должны быть удалены.

QTextLine QTextLayout::createLine()

Возвращает новую строку текста для макета, если в макете есть текст для вставки; в противном случае возвращает недействительную строку.

Макет создаёт новый объект строки, который начинается после последней строки в макете или в начале, если макет пуст. Макет поддерживает внутренний курсор, и каждая строка заполняется текстом с позиции курсора, когда вызывается функция QTextLine::setLineWidth().

После вызова QTextLine::setLineWidth() можно создать новую строку и заполнить её текстом. Повторение этого процесса выведет весь блок текста, содержащийся в QTextLayout. Если текст для вставки в макет отсутствует, возвращённая QTextLine не будет действительной (isValid() вернёт false).

Qt::CursorMoveStyle QTextLayout::cursorMoveStyle() const

Стиль перемещения курсора для этого QTextLayout. По умолчанию – Qt::LogicalMoveStyle.

См. также setCursorMoveStyle().

void QTextLayout::draw(QPainter *p, const QPointF &pos, const QList<QTextLayout::FormatRange> &selections = QList<FormatRange>(), const QRectF &clip = QRectF()) const

Отображает весь макет на рисовальщике p в позиции, заданной pos. Отображаемый макет включает заданные selections и ограничен прямоугольником clip.

void QTextLayout::drawCursor(QPainter *painter, const QPointF &position, int cursorPosition, int width) const

Рисует курсор текста с текущей кистью и заданной width в указанной position с использованием заданного painter. Соответствующая позиция в тексте задаётся cursorPosition.

void QTextLayout::drawCursor(QPainter *painter, const QPointF &position, int cursorPosition) const

Перегруженная функция.

Рисует курсор текста с текущей кистью в заданной position с использованием заданного painter. Соответствующая позиция в тексте задаётся cursorPosition.

void QTextLayout::endLayout()

Завершает процесс макета.

См. также beginLayout().

QFont QTextLayout::font() const

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

См. также setFont().

[since 5.6] QList<QTextLayout::FormatRange> QTextLayout::formats() const

Возвращает список дополнительных форматов, поддерживаемых макетом текста.

Данная функция была добавлена в Qt 5.6.

См. также setFormats() и clearFormats().

QList<QGlyphRun> QTextLayout::glyphRuns(int from = -1, int length = -1) const

Возвращает индексы и позиции глифов для всех глифов, соответствующих length символам, начиная с позиции from в этом QTextLayout. Эта функция ресурсоёмкая и не должна вызываться в контексте, чувствительном к времени.

Если from меньше нуля, то глиф-ряд начнётся с первого символа в макете. Если length меньше нуля, он охватит всю строку с начальной позиции.

См. также draw() и QPainter::drawGlyphRun().

bool QTextLayout::isValidCursorPosition(int pos) const

/ Возвращает true если позиция pos является допустимой позицией курсора.

В контексте Unicode некоторые позиции в тексте не являются допустимыми позициями курсора, потому что позиция находится внутри суррогата Unicode или кластера графем.

Кластер графем — это последовательность из двух или более символов Unicode, которые образуют одну неделимую сущность на экране. Например, латинский символ `Ä' может быть представлен в Unicode двумя символами, `A' (0x41) и диакритический знак диэреза (0x308). Курсор текста может быть размещён только перед или после этих двух символов, а не между ними, так как это не имеет смысла. Во всех индийских языках каждая слога образует кластер графем.

int QTextLayout::leftCursorPosition(int oldPos) const

Возвращает позицию курсора слева от oldPos, рядом с ним. Зависит от визуального расположения символов после переупорядочивания в прямом и обратном порядке.

См. также rightCursorPosition() и previousCursorPosition().

QTextLine QTextLayout::lineAt(int i) const

Возвращает i-ую строку текста в этом макете текста.

См. также lineCount() и lineForTextPosition().

int QTextLayout::lineCount() const

Возвращает количество строк в этом макете текста.

См. также lineAt().

QTextLine QTextLayout::lineForTextPosition(int pos) const

Возвращает строку, содержащую позицию курсора, заданную pos.

См. также isValidCursorPosition() и lineAt().

qreal QTextLayout::maximumWidth() const

Максимальная ширина, до которой может расшириться макет; по существу, это ширина всего текста.

Предупреждение: Эта функция возвращает корректное значение только после того, как макет был создан.

См. также minimumWidth().

qreal QTextLayout::minimumWidth() const

Минимальная ширина, необходимая для вывода макета. Это ширина самой маленькой неразрывной подстроки макета.

Предупреждение: Эта функция возвращает корректное значение только после завершения расчета макета.

См. также maximumWidth().

int QTextLayout::nextCursorPosition(int oldPos, QTextLayout::CursorMode mode = SkipCharacters) const

Возвращает следующее допустимое положение курсора после oldPos, учитывая заданный режим курсора mode. Возвращает значение oldPos, если oldPos не является допустимым положением курсора.

См. также isValidCursorPosition() и previousCursorPosition().

QPointF QTextLayout::position() const

Глобальное положение макета. Оно независимо от ограничивающей прямоугольной области и от процесса вычисления макета.

См. также setPosition().

int QTextLayout::preeditAreaPosition() const

Возвращает положение области в текстовом макете, которая будет обработана перед редактированием.

См. также preeditAreaText().

QString QTextLayout::preeditAreaText() const

Возвращает текст, который вставляется в макет перед началом редактирования.

См. также preeditAreaPosition().

int QTextLayout::previousCursorPosition(int oldPos, QTextLayout::CursorMode mode = SkipCharacters) const

Возвращает первое допустимое положение курсора перед oldPos, учитывая заданный режим курсора mode. Возвращает значение oldPos, если oldPos не является допустимым положением курсора.

См. также isValidCursorPosition() и nextCursorPosition().

int QTextLayout::rightCursorPosition(int oldPos) const

Возвращает положение курсора справа от oldPos, рядом с ним. Зависит от визуального положения символов после двунаправленной перестановки.

См. также leftCursorPosition() и nextCursorPosition().

void QTextLayout::setCacheEnabled(bool enable)

Включает кэширование всей информации о макете, если enable равно true; иначе отключает кэширование. Обычно QTextLayout отбрасывает большую часть информации о макете после вызова endLayout() для экономии памяти. Если вы хотите отобразить отформатированный текст непосредственно после этого, включение кэширования может значительно ускорить отрисовку.

См. также cacheEnabled().

void QTextLayout::setCursorMoveStyle(Qt::CursorMoveStyle style)

Устанавливает визуальный стиль перемещения курсора на заданный style. Если QTextLayout поддерживает документ, вы можете проигнорировать это и использовать опцию в QTextDocument; эта опция предназначена для виджетов, таких как QLineEdit или пользовательские виджеты без QTextDocument. Значение по умолчанию — Qt::LogicalMoveStyle.

См. также cursorMoveStyle().

void QTextLayout::setFont(const QFont &font)

Устанавливает шрифт макета на заданный font. Макет считается недействительным и должен быть пересчитан.

См. также font().

void QTextLayout::setFormats(const QList<QTextLayout::FormatRange> &formats)

Устанавливает дополнительные форматы, поддерживаемые текстовым макетом, на formats. Форматы применяются с текстом предварительной области.

Эта функция была введена в Qt 5.6.

См. также formats() и clearFormats().

void QTextLayout::setPosition(const QPointF &p)

Перемещает текстовый макет в точку p.

См. также position().

void QTextLayout::setPreeditArea(int position, const QString &text)

Устанавливает position и text для области в макете, которая обрабатывается перед редактированием. Макет считается недействительным и должен быть пересчитан.

См. также preeditAreaPosition() и preeditAreaText().

void QTextLayout::setText(const QString &string)

Устанавливает текст макета на заданный string. Макет считается недействительным и должен быть пересчитан.

Обратите внимание, что при использовании QTextLayout как части QTextDocument этот метод не окажет никакого влияния.

См. также text().

void QTextLayout::setTextOption(const QTextOption &option)

Устанавливает структуру параметров форматирования текста, которая управляет процессом вычисления макета, на заданный option.

См. также textOption().

QString QTextLayout::text() const

Возвращает текст макета.

См. также setText().

const QTextOption &QTextLayout::textOption() const

Возвращает текущие параметры форматирования текста, используемые для управления процессом вычисления макета.

См. также setTextOption().