Класс QStaticText

Класс QStaticText позволяет оптимизировать отрисовку текста, когда текст и его расположение обновляются редко. Подробнее...

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

Типы публичного доступа

Функции публичного доступа

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

QStaticText предоставляет способ кеширования данных разметки блока текста, чтобы его можно было отрисовать более эффективно, чем с помощью QPainter::drawText(), в котором информация о разметке пересчитывается при каждом вызове.

Класс в первую очередь предназначен для оптимизации случаев, когда текст, его шрифт и преобразования в отрисовщике являются статическими в течение нескольких событий отрисовки. Если текст или его разметка изменяются для каждой итерации, QPainter::drawText() является более эффективной альтернативой, так как разметка статического текста должна пересчитываться для учета нового состояния.

Преобразование отрисовщика не приведет к пересчету разметки текста, но окажет очень небольшое влияние на производительность drawStaticText(). Изменение других частей преобразования отрисовщика или шрифта отрисовщика приведет к пересчету разметки статического текста. Это следует избегать по возможности, чтобы максимизировать преимущества производительности использования QStaticText.

Кроме того, drawStaticText() поддерживает только аффинные преобразования. Вызов drawStaticText() на проецируемом отрисовщике будет работать немного хуже, чем обычный вызов drawText(), поэтому этого следует избегать.

class MyWidget: public QWidget
{
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent), m_staticText("This is static text")

protected:
    void paintEvent(QPaintEvent *)
    {
        QPainter painter(this);
        painter.drawStaticText(0, 0, m_staticText);
    }

private:
    QStaticText m_staticText;
};

Класс QStaticText может использоваться для имитации поведения QPainter::drawText() в определенной точке без границ, а также когда QPainter::drawText() вызывается с ограничительной прямоугольной областью.

Если ограничительная прямоугольная область не требуется, создайте объект QStaticText без задания предпочтительной ширины текста. Тогда текст займет одну строку.

Если вы зададите ширину текста в объекте QStaticText, это ограничит текст. Текст будет отформатирован таким образом, что ни одна строка не будет превышать заданную ширину. Ширина текста, заданная для QStaticText, не будет автоматически использоваться для обрезки. Чтобы получить обрезку в дополнение к переносу строк, используйте QPainter::setClipRect(). Положение текста определяется аргументом, переданным в QPainter::drawStaticText(), и может меняться от вызова к вызову с минимальным влиянием на производительность.

Для дополнительного удобства можно применять форматирование к тексту, используя подмножество HTML, поддерживаемое QTextDocument. QStaticText попытается угадать формат входного текста с помощью Qt::mightBeRichText(), и интерпретировать его как форматированный текст, если эта функция возвращает true. Чтобы принудительно заставить QStaticText отображать содержимое как обычный текст или форматированный текст, используйте функцию QStaticText::setTextFormat() и передайте соответственно Qt::PlainText и Qt::RichText.

QStaticText может представлять только текст, поэтому будут соблюдаться только те теги HTML, которые изменяют расположение или внешний вид текста. Добавление изображения в входной HTML, например, приведет к включению изображения в разметку, повлияет на позиции глифов текста, но оно не будет отображено. Результатом будет пустая область размером с изображение в выводе. Аналогично, использование таблиц приведет к выкладке текста в формате таблицы, но границы не будут нарисованы.

Если статический текст рисуется впервые или если статический текст или шрифт отрисовщика были изменены с момента последнего рисования, разметка текста должна быть пересчитана. В некоторых графических движках изменение матрицы отрисовщика также приведет к пересчету разметки. В частности, это произойдет для любого движка, кроме графического движка OpenGL2. Пересчет разметки наложит на вызов QPainter::drawStaticText() издержки, где это происходит. Чтобы избежать этих издержек в событии отрисовки, вы можете вызвать prepare() заранее, чтобы убедиться, что разметка вычислена.

См. также QPainter::drawText(), QPainter::drawStaticText(), QTextLayout и QTextDocument.

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

Перечисление QStaticText::PerformanceHint

Это перечисление различных подсказок производительности, которые можно задать для QStaticText. Эти подсказки могут использоваться для указания того, что QStaticText должен использовать дополнительные кеши, если это возможно, чтобы повысить производительность за счет памяти. В частности, установка подсказки производительности AggressiveCaching для QStaticText повысит производительность при использовании графической системы OpenGL или при отрисовке в QOpenGLWidget.

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

QStaticText::QStaticText(const QStaticText &other)

Создает объект QStaticText, который является копией other.

QStaticText::QStaticText(const QString &text)

Создает объект QStaticText с заданным текстом.

QStaticText::QStaticText()

Создает пустой QStaticText

QStaticText &QStaticText::operator=(const QStaticText &other)

Присваивает other этому QStaticText.

QStaticText::~QStaticText()

Удаляет QStaticText.

QStaticText::PerformanceHint QStaticText::performanceHint() const

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

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

void QStaticText::prepare(const QTransform &matrix = QTransform(), const QFont &font = QFont())

Подготавливает объект QStaticText для отрисовки с заданной matrix и font, чтобы избежать накладных расходов при вызове drawStaticText().

При вызове drawStaticText() макет QStaticText будет пересчитан, если какая-либо часть объекта QStaticText изменилась с момента последнего отрисовки. Он также будет пересчитан, если шрифт painter не совпадает со шрифтом, использованным при последнем отрисовке QStaticText, или, в случае использования любого движка отрисовки, отличного от OpenGL2, если матрица painter была изменена с момента последнего отрисовки статического текста.

Чтобы избежать накладных расходов при создании макета в первый раз при отрисовке QStaticText после внесения изменений, можно использовать функцию prepare() и передать ожидаемые matrix и font, которые будут использоваться при отрисовке текста.

См. также QPainter::setFont() и QPainter::setWorldTransform().

void QStaticText::setPerformanceHint(QStaticText::PerformanceHint performanceHint)

Устанавливает параметр производительности QStaticText в соответствии с заданным performanceHint. Параметр performanceHint используется для настройки степени кэширования, что улучшает производительность.

Значение по умолчанию — QStaticText::ModerateCaching.

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

void QStaticText::setText(const QString &text)

Устанавливает текст QStaticText на text.

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

void QStaticText::setTextFormat(Qt::TextFormat textFormat)

Устанавливает формат текста QStaticText на textFormat. Если textFormat установлен на Qt::AutoText (значение по умолчанию), формат текста будет определяться с помощью функции Qt::mightBeRichText(). Если формат текста Qt::PlainText, текст будет отображаться как есть, а при формате Qt::RichText он будет интерпретироваться как HTML. HTML-теги, изменяющие шрифт, цвет или структуру вывода текста, поддерживаются QStaticText.

См. также textFormat(), setText() и text().

void QStaticText::setTextOption(const QTextOption &textOption)

Устанавливает структуру параметров текста, контролирующую процесс вывода, на заданные textOption.

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

void QStaticText::setTextWidth(qreal textWidth)

Устанавливает предпочтительную ширину для QStaticText. Если текст шире указанной ширины, он будет разбиваться на несколько строк и увеличиваться по вертикали. Если текст нельзя разбить на несколько строк, его размер будет больше, чем заданная textWidth.

Установка предпочтительной ширины текста в отрицательное значение сделает ширину неограниченной.

Используйте size(), чтобы получить фактический размер текста.

См. также textWidth() и size().

QSizeF QStaticText::size() const

Возвращает размер ограничивающей рамки для QStaticText.

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

[since 5.0] void QStaticText::swap(QStaticText &other)

Меняет местами этот экземпляр статического текста с other. Эта функция очень быстрая и никогда не терпит неудачу.

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

QString QStaticText::text() const

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

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

Qt::TextFormat QStaticText::textFormat() const

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

См. также setTextFormat(), setText() и text().

QTextOption QStaticText::textOption() const

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

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

qreal QStaticText::textWidth() const

Возвращает предпочтительную ширину для QStaticText.

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

bool QStaticText::operator!=(const QStaticText &other) const

Сравнивает other с этим QStaticText. Возвращает true если тексты, шрифты или максимальные размеры отличаются.

bool QStaticText::operator==(const QStaticText &other) const

Сравнивает other с этим QStaticText. Возвращает true если тексты, шрифты и ширины текста совпадают.