QSGTextNode Class
QSGTextNode 클래스는 ‘ Qt Quick ’ 씬 그래프에서 텍스트 레이아웃과 텍스트 문서를 그리는 데 사용되는 클래스입니다. 더 보기...
| 헤더: | #include <QSGTextNode> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| 다음부터: | Qt 6.7 |
| 상속: | QSGTransformNode |
공개 유형
| enum | RenderType { QtRendering, NativeRendering, CurveRendering } |
| enum | TextStyle { Normal, Outline, Raised, Sunken } |
공개 함수
| void | addTextDocument(QPointF position, QTextDocument *document, int selectionStart = -1, int selectionCount = -1) |
| void | addTextLayout(QPointF position, QTextLayout *layout, int selectionStart = -1, int selectionCount = -1, int lineStart = 0, int lineCount = -1) |
| virtual void | clear() = 0 |
| virtual QColor | color() const = 0 |
| virtual QSGTexture::Filtering | filtering() const = 0 |
| virtual QColor | linkColor() const = 0 |
| virtual QSGTextNode::RenderType | renderType() const = 0 |
| virtual int | renderTypeQuality() const = 0 |
| virtual QColor | selectionColor() const = 0 |
| virtual QColor | selectionTextColor() const = 0 |
| virtual void | setColor(QColor color) = 0 |
| virtual void | setFiltering(QSGTexture::Filtering filtering) = 0 |
| virtual void | setLinkColor(QColor linkColor) = 0 |
| virtual void | setRenderType(QSGTextNode::RenderType renderType) = 0 |
| virtual void | setRenderTypeQuality(int renderTypeQuality) = 0 |
| virtual void | setSelectionColor(QColor color) = 0 |
| virtual void | setSelectionTextColor(QColor selectionTextColor) = 0 |
| virtual void | setStyleColor(QColor styleColor) = 0 |
| virtual void | setTextStyle(QSGTextNode::TextStyle textStyle) = 0 |
| virtual void | setViewport(const QRectF &viewport) = 0 |
| virtual QColor | styleColor() const = 0 |
| virtual QSGTextNode::TextStyle | textStyle() = 0 |
| virtual QRectF | viewport() const = 0 |
비공개 함수
| virtual void | doAddTextDocument(QPointF position, QTextDocument *document, int selectionStart, int selectionCount) = 0 |
| virtual void | doAddTextLayout(QPointF position, QTextLayout *layout, int selectionStart, int selectionCount, int lineStart, int lineCount) = 0 |
상세 설명
QSGTextNode는 텍스트가 필요한 사용자 정의 Qt Quick 항목을 생성하는 데 유용할 수 있습니다. 이는 Qt Quick 에서 Text, TextEdit 및 TextInput 요소에 의해 사용됩니다.
QQuickWindow::createTextNode()를 사용하여 QSGTextNode 객체를 생성할 수 있습니다. addTextLayout() 및 addTextDocument() 함수는 QSGTextNode에 텍스트를 추가하는 방법을 제공합니다. 텍스트는 이미 레이아웃이 설정되어 있어야 합니다.
참고: 속성이 적용되려면 addTextLayout() 또는 addTextDocument()을 호출하기 전에속성을 설정해야 합니다.
참고: QSGTextNode의소멸 처리는 신중하게 관리해야 합니다. 특히, 이 노드는 그래픽 리소스를 참조하므로 Qt Quick 장면 그래프가 무효화될 때 삭제되어야 합니다. 노드가 그래프의 일부이고 OwnedByParent 플래그가 설정되어 있는 경우(기본값), 이 작업은 자동으로 수행됩니다. 그러나 OwnedByParent 플래그가 해제되어 있고 노드를 수동으로 해제하는 경우, 씬 그래프가 무효화될 때 이를 수행하도록 주의해야 합니다. 이는 QQuickWindow::sceneGraphInvalidated() 신호에 연결하거나, QQuickItem 서브클래스에서 invalidateSceneGraph() 라는 이름의 슬롯을 구현하여 수행할 수 있습니다. 자세한 내용은 QQuickItem 문서를 참조하십시오.
멤버 유형 문서
enum QSGTextNode::RenderType
이 열거형 유형은 텍스트 렌더링에 사용되는 글리프 노드의 유형을 나타냅니다.
| 상수 | 값 | 설명 |
|---|---|---|
QSGTextNode::QtRendering | 0 | 각 글리프에 대해 확장 가능한 거리 필드를 사용하여 텍스트가 렌더링됩니다. |
QSGTextNode::NativeRendering | 1 | 텍스트는 플랫폼별 기법을 사용하여 렌더링됩니다. |
QSGTextNode::CurveRendering | 2 | 텍스트는 그래픽 하드웨어에서 직접 실행되는 커브 래스터라이저를 사용하여 렌더링됩니다. |
대상 플랫폼에서 텍스트가 네이티브처럼 보이기를 원하고 텍스트 변환과 같은 고급 기능이 필요하지 않은 경우 NativeRendering 를 선택하십시오. NativeRendering 렌더링 유형과 함께 이러한 기능을 사용하면 결과가 좋지 않거나 때로는 픽셀화될 수 있습니다.
Text.QtRendering 과 Text.CurveRendering 은 모두 하드웨어 가속 기술입니다. QtRendering 이 두 가지 중 더 빠르지만, 더 많은 메모리를 사용하며 큰 크기에서는 렌더링 아티팩트가 나타납니다. QtRendering 이 만족스러운 시각적 결과를 제공하지 않거나 그래픽 메모리 소비를 줄이는 것이 우선순위인 경우에는 CurveRendering 을 대안으로 고려해야 합니다.
setRenderType() 및 setRenderTypeQuality()도 참조하십시오 .
enum QSGTextNode::TextStyle
이 열거형 유형은 텍스트 렌더링에 적용할 수 있는 스타일을 정의합니다.
| 상수 | 값 | 설명 |
|---|---|---|
QSGTextNode::Normal | 0 | 텍스트에 어떤 스타일도 적용되지 않은 상태로 그려집니다. |
QSGTextNode::Outline | 1 | 텍스트에 윤곽선이 그려집니다. |
QSGTextNode::Raised | 2 | 텍스트가 돌출되어 그려집니다. |
QSGTextNode::Sunken | 3 | 텍스트가 오목하게 그려집니다. |
setTextStyle() 및 setStyleColor()도 참조하십시오 .
멤버 함수 문서
void QSGTextNode::addTextDocument(QPointF position, QTextDocument *document, int selectionStart = -1, int selectionCount = -1)
document 의 내용을 position 에 있는 텍스트 노드에 추가합니다. selectionStart 가 0 이상인 경우, 이는 selectionCount 개 문자로 구성된 선택 영역의 첫 번째 문자를 표시합니다. 선택 영역은 selectionColor()을 사용하여 배경 채우기로 표현되며, 선택된 텍스트는 selectionTextColor()을 통해 렌더링됩니다.
이 함수는 인수를 가상 함수 doAddTextDocument()로 전달합니다.
clear()도 참조하십시오 .
void QSGTextNode::addTextLayout(QPointF position, QTextLayout *layout, int selectionStart = -1, int selectionCount = -1, int lineStart = 0, int lineCount = -1)
layout 의 내용을 position 에 있는 텍스트 노드에 추가합니다. selectionStart 가 0 이상인 경우, 이는 selectionCount 개 문자로 구성된 선택 영역의 첫 번째 문자를 표시합니다. 선택 영역은 selectionColor()을 사용하여 배경 채우기로 표현되며, 선택된 텍스트는 selectionTextColor()을 통해 렌더링됩니다.
편의를 위해 lineStart 및 lineCount 를 사용하여 레이아웃에서 포함할 QTextLine 객체의 범위를 선택할 수 있습니다. 이는 예를 들어, 생략된 레이아웃을 생성할 때 유용할 수 있습니다. lineCount 가 < 0인 경우, 노드는 lineStart 부터 레이아웃 끝까지의 줄을 포함합니다.
이 함수는 인수를 가상 함수 doAddTextLayout()로 전달합니다.
clear()도 참조하십시오 .
[pure virtual] void QSGTextNode::clear()
노드의 내용을 지우며, 해당 노드에 추가된 레이아웃 및 문서를 나타내는 노드와 기타 데이터를 삭제합니다.
addTextLayout() 및 addTextDocument()도 참조하십시오 .
[pure virtual] QColor QSGTextNode::color() const
텍스트를 렌더링할 때 사용된 주 색상을 반환합니다.
setColor()도 참조하십시오 .
[pure virtual private] void QSGTextNode::doAddTextDocument(QPointF position, QTextDocument *document, int selectionStart, int selectionCount)
addTextDocument()에 의해 호출되는 가상 함수로, document 의 내용을 장면 그래프 노드로 변환하여 position 의 현재 노드에 추가합니다.
selectionStart 가 0 이상인 경우, 이는 selectionCount 에서 지정된 개수의 문자로 구성된 선택 영역의 첫 번째 문자를 나타냅니다. 선택 영역은 selectionColor()을 사용하여 배경 채우기로 표시되며, 선택된 텍스트는 selectionTextColor()을 통해 렌더링됩니다.
clear() 및 addTextDocument()도 참조하십시오 .
[pure virtual private] void QSGTextNode::doAddTextLayout(QPointF position, QTextLayout *layout, int selectionStart, int selectionCount, int lineStart, int lineCount)
addTextLayout()에 의해 호출되는 가상 함수로, layout 의 내용을 장면 그래프 노드로 변환하여 position 의 현재 노드에 추가합니다.
selectionStart 가 0 이상인 경우, 이는 selectionCount 에 지정된 문자 수만큼의 선택 영역의 첫 번째 문자를 나타냅니다. 선택 영역은 selectionColor()을 사용하여 배경 채우기로 표시되며, 선택된 텍스트는 selectionTextColor()을 통해 렌더링됩니다.
편의를 위해 lineStart 및 lineCount 를 사용하여 레이아웃에서 포함할 QTextLine 객체의 범위를 선택할 수 있습니다. 이는 예를 들어 생략된 레이아웃을 생성할 때 유용할 수 있습니다. lineCount 가 < 0인 경우, 노드는 lineStart 부터 레이아웃 끝까지의 줄을 포함합니다.
clear() 및 addTextLayout()도 참조하십시오 .
[pure virtual] QSGTexture::Filtering QSGTextNode::filtering() const
표시된 텍스트의 일부인 이미지를 크기 조정할 때 사용되는 샘플링 모드를 반환합니다.
setFiltering()도 참조하십시오 .
[pure virtual] QColor QSGTextNode::linkColor() const
텍스트 내 하이퍼링크의 색상을 반환합니다.
setLinkColor()도 참조하십시오 .
[pure virtual] QSGTextNode::RenderType QSGTextNode::renderType() const
텍스트 렌더링에 사용된 글리프 노드의 유형을 반환합니다.
setRenderType()도 참조하십시오 .
[pure virtual] int QSGTextNode::renderTypeQuality() const
노드의 렌더링 품질 유형을 반환합니다. 자세한 내용은 setRenderTypeQuality()을 참조하십시오.
setRenderTypeQuality()도 참조하십시오 .
[pure virtual] QColor QSGTextNode::selectionColor() const
텍스트의 어느 부분이든 선택된 상태로 표시되면 선택 영역의 배경색을 반환합니다.
setSelectionColor()도 참조하십시오 .
[pure virtual] QColor QSGTextNode::selectionTextColor() const
텍스트의 어느 부분이라도 선택된 상태로 표시되면, 선택된 텍스트의 색상을 반환합니다.
setSelectionTextColor()도 참조하십시오 .
[pure virtual] void QSGTextNode::setColor(QColor color)
color 에 텍스트를 렌더링할 때 사용할 기본 색상을 설정합니다.
기본값은 검은색입니다: QColor(0, 0, 0).
color()도 참조하십시오 .
[pure virtual] void QSGTextNode::setFiltering(QSGTexture::Filtering filtering)
표시된 텍스트의 일부인 이미지를 크기 조정할 때 사용되는 샘플링 모드를 ‘ filtering ’로 설정합니다. 이미지를 부드럽게 크기 조정하려면 여기에서 ‘ QSGTexture::Linear ’를 사용하십시오.
기본값은 ` QSGTexture::Nearest`입니다.
filtering()도 참조하십시오 .
[pure virtual] void QSGTextNode::setLinkColor(QColor linkColor)
텍스트 내의 색상 또는 linkColor 로 연결되는 하이퍼링크의 색상을 설정합니다.
기본값은 파란색입니다: QColor(0, 0, 255).
linkColor()도 참조하십시오 .
[pure virtual] void QSGTextNode::setRenderType(QSGTextNode::RenderType renderType)
사용 중인 글리프 노드의 유형을 ‘ renderType ’로 설정합니다.
기본값은 ` QtRendering`입니다.
renderType()도 참조하십시오 .
[pure virtual] void QSGTextNode::setRenderTypeQuality(int renderTypeQuality)
사용 중인 ` renderType()`가 이를 지원하는 경우, 텍스트를 렌더링할 때 사용할 품질을 설정합니다. 이 기능이 지원되는 경우, 이를 통해 시각적 충실도를 희생하여 실행 속도나 메모리 사용량을 개선할 수 있습니다.
renderTypeQuality 값이 0보다 작을 경우, 기본 품질이 사용됩니다.
renderTypeQuality 는 임의의 정수 값을 가질 수 있으나, 극단적인 값을 설정할 경우 기본 그래픽 하드웨어에서 부과하는 제한 사항이 발생할 수 있습니다. Qt Quick Text 요소는 다음과 같은 사전 정의된 값으로 작동합니다:
| 상수 | 설명 |
|---|---|
DefaultRenderTypeQuality | -1 (기본값) |
LowRenderTypeQuality | 26 |
NormalRenderTypeQuality | 52 |
HighRenderTypeQuality | 104 |
VeryHighRenderTypeQuality | 208 |
이 값은 현재 ' QtRendering ' 렌더링 유형에서만 적용됩니다. 이 값을 설정하면 글리프를 표현하는 데 사용되는 거리 필드의 해상도가 변경됩니다. 이 값을 'normal'보다 높게 설정하면 메모리 사용량이 증가하지만, 매우 큰 텍스트에서 발생하는 필터링 아티팩트가 줄어듭니다.
기본값은 -1입니다.
renderTypeQuality()도 참조하십시오 .
[pure virtual] void QSGTextNode::setSelectionColor(QColor color)
텍스트의 어느 부분이든 선택된 상태로 표시되면 선택 영역의 배경색을 color 로 설정합니다.
기본값은 진한 파란색입니다: QColor(0, 0, 128).
selectionColor()도 참조하십시오 .
[pure virtual] void QSGTextNode::setSelectionTextColor(QColor selectionTextColor)
텍스트의 어느 부분이든 선택된 것으로 표시되면, 선택된 텍스트의 색상을 selectionTextColor 로 설정합니다.
기본값은 흰색입니다: QColor(255, 255, 255).
selectionTextColor()도 참조하십시오 .
[pure virtual] void QSGTextNode::setStyleColor(QColor styleColor)
styleColor 에 텍스트를 렌더링할 때 사용할 스타일 색상을 설정합니다.
기본값은 검은색입니다: QColor(0, 0, 0).
styleColor() 및 setTextStyle()도 참조하십시오 .
[pure virtual] void QSGTextNode::setTextStyle(QSGTextNode::TextStyle textStyle)
렌더링된 텍스트의 스타일을 ` textStyle`로 설정합니다. 기본값은 ` Normal`입니다.
textStyle() 및 setStyleColor()도 참조하십시오 .
[pure virtual] void QSGTextNode::setViewport(const QRectF &viewport)
텍스트가 표시되는 뷰포트의 경계 사각형을 ` viewport`로 설정합니다. 이 정보를 제공하면 ` QSGTextNode `가 텍스트 레이아웃이나 문서의 어느 부분을 씬 그래프에 포함시킬지 최적화할 수 있습니다.
기본값은 기본 생성된 ` QRectF`입니다. 이 뷰포트의 경우 모든 콘텐츠가 그래프에 포함됩니다.
viewport()도 참조하십시오 .
[pure virtual] QColor QSGTextNode::styleColor() const
텍스트를 렌더링할 때 사용된 스타일 색상을 반환합니다.
setStyleColor() 및 textStyle()도 참조하십시오 .
[pure virtual] QSGTextNode::TextStyle QSGTextNode::textStyle()
렌더링된 텍스트의 스타일을 반환합니다.
setTextStyle() 및 styleColor()도 참조하십시오 .
[pure virtual] QRectF QSGTextNode::viewport() const
이 QSGTextNode 에 대해 현재 설정된 뷰포트를 반환합니다.
setViewport()도 참조하십시오 .
© 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.