QStaticText Class

QStaticText 클래스는 텍스트와 레이아웃이 드물게 업데이트될 때 텍스트 그리기를 최적화할 수 있도록 합니다. 더 보기...

Header: #include <QStaticText>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

공용 형

enum PerformanceHint { ModerateCaching, AggressiveCaching }

공용 함수

QStaticText()
QStaticText(const QString &text)
QStaticText(const QStaticText &other)
~QStaticText()
QStaticText::PerformanceHint performanceHint() const
void prepare(const QTransform &matrix = QTransform(), const QFont &font = QFont())
void setPerformanceHint(QStaticText::PerformanceHint performanceHint)
void setText(const QString &text)
void setTextFormat(Qt::TextFormat textFormat)
void setTextOption(const QTextOption &textOption)
void setTextWidth(qreal textWidth)
QSizeF size() const
void swap(QStaticText &other)
QString text() const
Qt::TextFormat textFormat() const
QTextOption textOption() const
qreal textWidth() const
bool operator!=(const QStaticText &other) const
QStaticText &operator=(const QStaticText &other)
bool operator==(const QStaticText &other) const

상세 설명

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()에 전달된 인수에 의해 결정되며, 성능에 미치는 영향을 최소화하면서 호출마다 변경할 수 있습니다.

추가 편의를 위해 QTextDocument 에서 지원하는 HTML 하위 집합을 사용하여 텍스트에 서식을 적용할 수 있습니다. QStaticText는 Qt::mightBeRichText()를 사용하여 입력 텍스트의 형식을 추측하고 이 함수가 true 을 반환하면 리치 텍스트로 해석하려고 시도합니다. QStaticText가 내용을 일반 텍스트 또는 서식 있는 텍스트로 표시하도록 하려면 QStaticText::setTextFormat() 함수를 사용하고 Qt::PlainTextQt::RichText 를 각각 전달합니다.

QStaticText는 텍스트만 표현할 수 있으므로 텍스트의 레이아웃이나 모양을 변경하는 HTML 태그만 존중됩니다. 예를 들어 입력 HTML에 이미지를 추가하면 이미지가 레이아웃의 일부로 포함되어 텍스트 글리프의 위치에 영향을 미치지만 표시되지는 않습니다. 그 결과 출력에 이미지 크기만큼의 빈 영역이 표시됩니다. 마찬가지로 표를 사용하면 텍스트가 표 형식으로 배치되지만 테두리는 그려지지 않습니다.

정적 텍스트가 처음 그려지거나 정적 텍스트 또는 페인트 글꼴이 마지막으로 그려진 이후 변경된 경우 텍스트의 레이아웃을 다시 계산해야 합니다. 일부 페인트 엔진에서는 페인터의 매트릭스를 변경해도 레이아웃이 다시 계산됩니다. 특히 OpenGL2 페인트 엔진을 제외한 모든 엔진에서 이 문제가 발생합니다. 레이아웃을 다시 계산하면 QPainter::drawStaticText() 호출에 오버헤드가 발생합니다. 페인트 이벤트에서 이러한 오버헤드를 피하려면 prepare()를 미리 호출하여 레이아웃이 계산되도록 할 수 있습니다.

QPainter::drawText(), QPainter::drawStaticText(), QTextLayout, 및 QTextDocument도 참조하세요 .

멤버 유형 문서

enum QStaticText::PerformanceHint

QStaticText 에 설정할 수 있는 다양한 성능 힌트를 열거한 것입니다. 이러한 힌트를 사용하여 QStaticText 에 가능한 경우 추가 캐시를 사용하여 메모리를 희생하면서 성능을 향상시킬 수 있습니다. 특히 QStaticText 에 성능 힌트 AggressiveCaching을 설정하면 OpenGL 그래픽 시스템을 사용하거나 QOpenGLWidget 로 그릴 때 성능이 향상됩니다.

Constant설명
QStaticText::ModerateCaching0낮은 메모리 비용으로 고성능을 위해 기본 캐싱을 수행합니다.
QStaticText::AggressiveCaching1사용 가능한 경우 추가 캐싱을 사용합니다. 이렇게 하면 메모리 비용이 높아지지만 성능이 향상될 수 있습니다.

멤버 함수 문서

QStaticText::QStaticText()

빈 QStaticText를 생성합니다.

[explicit] QStaticText::QStaticText(const QString &text)

주어진 text 로 QStaticText 객체를 생성합니다.

QStaticText::QStaticText(const QStaticText &other)

other 의 복사본인 QStaticText 객체를 생성합니다.

[noexcept] QStaticText::~QStaticText()

QStaticText 를 파괴합니다.

QStaticText::PerformanceHint QStaticText::performanceHint() const

QStaticText 에 설정된 성능 힌트를 반환합니다.

setPerformanceHint()도 참조하세요 .

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

실제 drawStaticText() 호출 시 오버헤드를 피하기 위해 주어진 matrix 및 주어진 font 로 칠할 QStaticText 객체를 준비합니다.

drawStaticText()가 호출될 때 마지막으로 그려진 이후 QStaticText 객체의 일부가 변경된 경우 QStaticText 의 레이아웃이 다시 계산됩니다. 또한 페인터의 글꼴이 QStaticText 을 마지막으로 그릴 때와 같지 않은 경우 또는 OpenGL2 엔진이 아닌 다른 페인트 엔진의 경우 정적 텍스트가 마지막으로 그려진 이후 페인터의 매트릭스가 변경된 경우에도 다시 계산됩니다.

변경 후 QStaticText 을 처음 그릴 때 레이아웃을 만드는 오버헤드를 피하려면 prepare() 함수를 사용하여 텍스트를 그릴 때 사용할 matrixfont 을 전달할 수 있습니다.

QPainter::setFont() 및 QPainter::setWorldTransform()도 참조하세요 .

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

제공된 performanceHint 에 따라 QStaticText 의 성능 힌트를 설정합니다. performanceHint 은 성능 향상을 위해 내부적으로 수행되는 캐싱의 양을 사용자 지정하는 데 사용됩니다.

기본값은 QStaticText::ModerateCaching 입니다.

참고: 이 함수를 사용하면 텍스트 레이아웃을 다시 계산해야 합니다.

performanceHint()도 참조하세요 .

void QStaticText::setText(const QString &text)

QStaticText 의 텍스트를 text 로 설정합니다.

참고: 이 함수를 사용하면 텍스트의 레이아웃을 다시 계산해야 합니다.

text()도 참조하세요 .

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

QStaticText 의 텍스트 형식을 textFormat 으로 설정합니다. textFormatQt::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()도 참조하세요 .

[noexcept] void QStaticText::swap(QStaticText &other)

이 정적 텍스트 인스턴스를 other 로 바꿉니다. 이 작업은 매우 빠르며 실패하지 않습니다.

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 을 반환합니다.

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

QStaticTextother 을 할당합니다.

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

other 과 이 QStaticText 을 비교합니다. 텍스트, 글꼴, 텍스트 너비가 같으면 true 을 반환합니다.

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.