QStaticText Class
QStaticText 클래스는 텍스트와 그 레이아웃이 드물게 업데이트될 때 텍스트를 최적화된 방식으로 그릴 수 있게 해줍니다. 더 보기...
| 헤더: | #include <QStaticText> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
- 상속된 멤버를 포함한 모든 멤버 목록
- QStaticText는 암시적 공유 클래스의 일부입니다.
공개 유형
| 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::PlainText 와 Qt::RichText 를 전달하십시오.
QStaticText는 텍스트만 표현할 수 있으므로, 텍스트의 레이아웃이나 모양을 변경하는 HTML 태그만 반영됩니다. 예를 들어, 입력 HTML에 이미지를 추가하면 해당 이미지가 레이아웃의 일부로 포함되어 텍스트 글리프의 위치에 영향을 미치지만, 실제로는 표시되지 않습니다. 그 결과 출력물에는 이미지 크기와 동일한 빈 영역이 나타납니다. 마찬가지로, 테이블을 사용하면 텍스트가 테이블 형식으로 배치되지만 테두리는 그려지지 않습니다.
정적 텍스트가 처음 그려지는 경우이거나, 마지막으로 그려진 이후 정적 텍스트나 페인터의 글꼴이 변경된 경우, 텍스트의 레이아웃을 다시 계산해야 합니다. 일부 페인트 엔진에서는 페인터의 매트릭스를 변경해도 레이아웃이 다시 계산됩니다. 특히, OpenGL2 페인트 엔진을 제외한 모든 엔진에서 이러한 현상이 발생합니다. 레이아웃을 재계산하면 해당 호출이 발생하는 QPainter::drawStaticText() 호출에 오버헤드가 발생합니다. 페인트 이벤트에서 이러한 오버헤드를 피하려면, prepare()를 미리 호출하여 레이아웃이 이미 계산되었는지 확인할 수 있습니다.
QPainter::drawText(), QPainter::drawStaticText(), QTextLayout 및 QTextDocument도 참조하십시오 .
멤버 유형 문서
enum QStaticText::PerformanceHint
이 열거형은 ` QStaticText`에 설정할 수 있는 다양한 성능 힌트를 나열합니다. 이러한 힌트를 사용하면, 메모리 사용량을 증가시키는 대신 성능을 향상시키기 위해 ` QStaticText `가 가능한 경우 추가 캐시를 사용하도록 지시할 수 있습니다. 특히, ` QStaticText `에 `AggressiveCaching` 성능 힌트를 설정하면 OpenGL 그래픽 시스템을 사용하거나 ` QOpenGLWidget`에 그리기를 수행할 때 성능이 향상됩니다.
| 상수 | 값 | 설명 |
|---|---|---|
QStaticText::ModerateCaching | 0 | 낮은 메모리 비용으로 높은 성능을 얻기 위해 기본 캐싱을 수행합니다. |
QStaticText::AggressiveCaching | 1 | 가능한 경우 추가 캐싱을 사용합니다. 이렇게 하면 메모리 소모는 더 커지지만 성능이 향상될 수 있습니다. |
멤버 함수 문서
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() 함수를 사용하여 텍스트를 그릴 때 사용할 것으로 예상되는 matrix 와 font 를 전달할 수 있습니다.
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 로 설정합니다. 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()도 참조하십시오 .
[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)
other 를 이 QStaticText 에 할당합니다.
bool QStaticText::operator==(const QStaticText &other) const
other 와 QStaticText 을 비교합니다. 텍스트, 글꼴 및 텍스트 너비가 모두 일치하면 true 를 반환합니다.
© 2026 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.