Класс QTextLayout

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

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

перечисление QTextLayout::CursorMode

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

QTextLayout::QTextLayout()

Конструирует пустой макет текста.

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

QTextLayout::QTextLayout(const QString &text)

Конструирует макет текста для вывода заданного text.

QTextLayout::QTextLayout(const QString &text, const QFont &font, QPaintDevice *paintdevice = Q_NULLPTR)

Конструирует макет текста для вывода заданного text с указанным font.

Все метрические и макетообразующие вычисления будут выполняться относительно устройства рисования paintdevice. Если paintdevice равен 0, вычисления будут выполняться относительно метрик экрана.

QTextLayout::~QTextLayout()

Деструктор макета.

void QTextLayout::beginLayout()

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

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

QRectF QTextLayout::boundingRect() const

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

bool QTextLayout::cacheEnabled() const

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

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

void QTextLayout::clearFormats()

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

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

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

void QTextLayout::clearLayout()

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

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

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 QVector<FormatRange> &selections = QVector<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().

QVector<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 меньше нуля, то он охватывает всю строку с начальной позиции.

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

См. также 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, CursorMode mode = SkipCharacters) const

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

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

QPointF QTextLayout::position() const

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

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

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

int QTextLayout::preeditAreaPosition() const

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

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

QString QTextLayout::preeditAreaText() const

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

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

int QTextLayout::previousCursorPosition(int oldPos, 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 QVector<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().

bool QTextLayout::operator!=(const FormatRange &lhs, const FormatRange &rhs)

Возвращает true, если какие-либо из start, length, или format полей в lhs и rhs соответственно содержат разные значения.

bool QTextLayout::operator==(const FormatRange &lhs, const FormatRange &rhs)

Возвращает true, если start, length, и format поля в lhs и rhs соответственно содержат одинаковые значения.