QStyleKitStyle Class
QStyleKitStyle 클래스는 Qt Labs StyleKit 스타일을 Qt Widgets 에 적용합니다. 더 보기...
| 헤더: | #include <QStyleKitStyle> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS LabsStyleKit) target_link_libraries(mytarget PRIVATE Qt6::LabsStyleKit) |
| 다음부터: | Qt 6.12 |
| 상속: | QCommonStyle |
속성
- availableThemeNames : QStringList
- customThemeNames : QStringList
- stylePath : QString
- themeName : QString
공개 함수
| QStyleKitStyle() | |
| QStyleKitStyle(const QString &filePath) | |
| virtual | ~QStyleKitStyle() override |
| QStringList | availableThemeNames() const |
| QStringList | customThemeNames() const |
| void | setStylePath(const QString &filePath) |
| void | setThemeName(const QString &themeName) |
| QString | stylePath() const |
| QString | themeName() const |
재구현된 공용 함수
| virtual void | drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *w = nullptr) const override |
| virtual void | drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const override |
| virtual void | drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const override |
| virtual QStyle::SubControl | hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *w = nullptr) const override |
| virtual int | pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt = nullptr, const QWidget *widget = nullptr) const override |
| virtual void | polish(QApplication *app) override |
| virtual void | polish(QPalette &palette) override |
| virtual void | polish(QWidget *widget) override |
| virtual QSize | sizeFromContents(QStyle::ContentsType ct, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget = nullptr) const override |
| virtual QPalette | standardPalette() const override |
| virtual int | styleHint(QStyle::StyleHint sh, const QStyleOption *opt = nullptr, const QWidget *w = nullptr, QStyleHintReturn *shret = nullptr) const override |
| virtual QRect | subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *w = nullptr) const override |
| virtual QRect | subElementRect(QStyle::SubElement r, const QStyleOption *opt, const QWidget *widget = nullptr) const override |
| virtual void | unpolish(QApplication *app) override |
| virtual void | unpolish(QWidget *widget) override |
신호
| void | availableThemeNamesChanged(const QStringList &availableThemeNames) |
| void | customThemeNamesChanged(const QStringList &customThemeNames) |
| void | stylePathChanged(const QString &stylePath) |
| void | themeNameChanged(const QString &themeName) |
재구현된 보호 함수
| virtual bool | event(QEvent *event) override |
| virtual bool | eventFilter(QObject *obj, QEvent *event) override |
상세 설명
QStyleKitStyle은 StyleKit Style 를 사용하여 Qt Widgets 의 스타일을 지정하는 QStyle 구현체입니다. Style 는 각 위젯 유형 및 상태에 대한 시각적 디자인(색상, 크기, 반경, 테두리 및 기타 속성)을 선언적으로 기술하는 QML 파일입니다. 이러한 속성 값은 페인팅을 제어하며, 페인팅은 전적으로 QPainter 를 통해 수행됩니다. Qt Quick 와 씬 그래프는 렌더링에 전혀 관여하지 않습니다.
이러한 분리를 통해 동일한 Style QML 파일로 Qt Quick Controls 와 Qt Widgets 모두를 제어할 수 있으며, 두 시스템에서 하나의 디자인 정의를 공유할 수 있습니다.
참고: StyleKit은 Qt Labs 모듈이며, Qt 릴리스에 따라 API가 변경될 수 있습니다.
스타일 불러오기
스타일은 루트 객체가 Style 인 QML 파일입니다. 스타일을 로드하려면 파일 경로를 생성자나 setStylePath()에 전달하십시오:
auto *style = new QStyleKitStyle(QStringLiteral(":/styles/MyStyle.qml"));
QApplication::setStyle(style);스타일은 QStyleKitStyle 인스턴스가 소유한 내부 QQmlEngine 와 함께 로드됩니다. 경로가 유효하지 않거나 루트 객체가 Style 가 아닌 경우 경고가 발생하며, 유효한 stylePath 가 설정될 때까지 스타일은 기본 대체 스타일을 사용합니다.
테마
스타일은 하나 이상의 명명된 themes 를 정의할 수 있습니다. 활성 테마는 setThemeName()를 통해 선택되며, 사용 가능한 테마 목록은 availableThemeNames 를 통해 제공됩니다. 특수 테마 이름 System 을 지정하면 스타일이 플랫폼 색상 구성표를 따르게 됩니다. OS 색상 구성표가 변경되면 활성 테마가 자동으로 재생성되고 모든 위젯이 다시 적용됩니다.
위젯과 StyleKit 컨트롤 간의 매핑
각 Qt Widgets 클래스는 StyleKit 컨트롤 유형에 매핑되며, 이를 통해 Style 내의 어떤 컨트롤 항목이 해당 클래스에 적용되는지가 결정됩니다. 해당 컨트롤 항목을 사용하여 해당 위젯 유형의 시각적 속성을 구성할 수 있으며, 여기에는 배경, 표시기, 핸들 등 위젯의 개별 부분도 포함됩니다. 스타일링 가능한 속성의 전체 목록은 ControlStyleProperties 을 참조하십시오. 특정 컨트롤 항목에서 설정되지 않은 속성은 컨트롤 유형 계층 구조를 통해 대체됩니다. 예를 들어, button 는 abstractButton 로 대체되고, 이는 다시 control 로 대체됩니다.
위에 나열되지 않은 위젯은 아직 QStyleKitStyle에서 지원되지 않으며, QCommonStyle 에 의해 렌더링됩니다. 나머지 위젯에 대한 지원은 향후 릴리스에서 제공될 예정입니다. 반대로, StylableControls 에 있는 일부 컨트롤 항목은 Qt Widgets 에 해당하는 항목이 없어, 위젯에 스타일을 적용할 때 사용되지 않습니다.
위젯 내의 하위 컨트롤
위젯 내의 개별 하위 컨트롤은 각각 Style 의 별도 컨트롤 항목에 매핑되므로 개별적으로 스타일을 지정할 수 있습니다:
| 하위 요소 | StyleKit 컨트롤 |
|---|---|
| QStyledItemDelegate items - QComboBox 팝업 목록을 포함한 모든 Qt 항목 뷰에 대한 기본 델리게이트 | itemDelegate |
| 사용자가 선택할 수 있는(즉, 선택 표시기가 표시되는) 동일한 항목의 경우 | checkDelegate; 명시적으로 설정되지 않은 항목에 대해서는 itemDelegate 로 대체됩니다 |
| 내의 개별 탭 QTabBar | tabButton |
| QMenu items | menuItem |
| 내의 구분선 QMenu | menuSeparator |
| QMenuBar 항목 | menuBarItem |
| 내부의 구분선 QToolBar | toolSeparator |
| QComboBox 팝업 목록 컨테이너 | popup |
알려진 제한 사항
QStyleKitStyle은 기술 미리보기(Tech Preview) 단계에 있습니다. 현재 Qt Widgets 와 함께 사용할 때 다음 StyleKit 기능은 지원되지 않습니다:
- 그림자 — 그림자가 렌더링되지 않습니다.
- 컨트롤 배경에 1.0을 초과하는 델리게이트 스케일 적용 — 위젯은 자체 사각형 영역 외부로 그리기를 수행할 수 없으므로, 스케일링된 배경은 위젯 가장자리에서 잘립니다. 배경을 안쪽으로 배치하고 확장될 공간을 확보하려면 ` margins `를 사용하십시오. 스케일링 지표, 핸들 및 전경에는 영향을 미치지 않습니다.
- 변형 — 위젯 인스턴스에 StyleVariation 를 설정하는 기능은 아직 지원되지 않습니다.
- 사용자 정의 컨트롤 — ` CustomControl `을 사용하여 사용자 정의 위젯의 스타일을 지정하는 기능은 아직 지원되지 않습니다.
- 사용자 정의 델리게이트 — ` delegate ` 속성은 사용되지 않으며, 항상 기본 렌더링이 적용됩니다.
이러한 기능에 대한 지원은 향후 릴리스에서 제공될 예정입니다.
QStyle, QCommonStyle, Qt Labs StyleKit, Style 및 Theme도 참조하십시오 .
속성 문서
[read-only] availableThemeNames : QStringList
이 속성은 로드된 Style 에서 제공하는 테마 이름 목록을 포함합니다.
이 목록에는 내장된 Light 및 Dark 테마는 물론, 해당 스타일에서 정의된 모든 사용자 정의 테마가 포함됩니다.
액세스 함수:
| QStringList | availableThemeNames() const |
Notifier 신호:
| void | availableThemeNamesChanged(const QStringList &availableThemeNames) |
[read-only] customThemeNames : QStringList
이 속성은 로드된 Style 에 의해 정의된 사용자 정의 테마 이름 목록을 포함합니다.
availableThemeNames 와 달리, 이 목록에는 기본 제공되는 Light 및 Dark 테마가 제외되며, 스타일 작성자가 명시적으로 정의한 테마만 포함됩니다. 스타일이 로드되지 않은 경우 빈 목록을 반환합니다.
액세스 함수:
| QStringList | customThemeNames() const |
알림 신호:
| void | customThemeNamesChanged(const QStringList &customThemeNames) |
availableThemeNames 및 themeName도 참조하십시오 .
stylePath : QString
이 속성은 이 스타일을 제어하는 QML Style 파일의 경로를 저장합니다.
값은 로컬 파일의 경로이거나 리소스 파일 시스템 내의 파일 경로(예: :/styles/MyStyle.qml)입니다. 상대 경로는 애플리케이션의 작업 디렉터리를 기준으로 해석됩니다. 파일에는 루트 객체가 ` Style`인 QML 컴포넌트가 포함되어 있어야 합니다. 이 속성을 설정하면 스타일이 다시 로드됩니다. 새 파일을 로드할 수 없는 경우, 이전에 로드된 스타일이 유지되고 경고가 표시됩니다.
액세스 함수:
| QString | stylePath() const |
| void | setStylePath(const QString &filePath) |
Notifier 시그널:
| void | stylePathChanged(const QString &stylePath) |
themeName : QString
이 속성은 활성 테마의 이름을 저장합니다.
값은 availableThemeNames 에 나열된 항목 중 하나여야 하며, 플랫폼 색상 구성표를 따르려면 특수 이름인 System 를 지정해야 합니다. 이 속성을 설정하면 모든 위젯이 새 테마에 맞춰 다시 그려집니다.
액세스 함수:
| QString | themeName() const |
| void | setThemeName(const QString &themeName) |
Notifier 시그널:
| void | themeNameChanged(const QString &themeName) |
멤버 함수 문서
QStyleKitStyle::QStyleKitStyle()
스타일이 로드되지 않은 상태로 QStyleKitStyle을 생성합니다.
생성 후 setStylePath()을 사용하여 QML Style 을 불러옵니다. 스타일이 로드될 때까지는 기본 대체 스타일이 사용됩니다.
[explicit] QStyleKitStyle::QStyleKitStyle(const QString &filePath)
QStyleKitStyle 객체를 생성하고, filePath 에 있는 QML Style 을 불러옵니다.
filePath 는 로컬 파일의 경로이거나 리소스 파일 시스템 내 파일의 경로입니다. 상대 경로는 애플리케이션의 작업 디렉터리를 기준으로 해석됩니다. 경로가 유효하지 않거나 로드된 컴포넌트의 루트 객체가 Style 가 아닌 경우, 경고가 발생하며 생성된 스타일은 유효한 stylePath 가 설정될 때까지 기본 대체 스타일을 사용합니다.
[override virtual noexcept] QStyleKitStyle::~QStyleKitStyle()
QStyleKitStyle 를 삭제합니다.
QStringList QStyleKitStyle::availableThemeNames() const
로드된 ` Style`에 의해 노출된 모든 테마의 이름을 반환합니다. 여기에는 내장 테마인 ` Light ` 및 ` Dark `와 해당 스타일에 의해 정의된 모든 사용자 정의 테마가 포함됩니다. 스타일이 로드되지 않은 경우 빈 목록을 반환합니다.
참고: availableThemeNames 속성에 대한게터 함수입니다.
customThemeNames() 및 themeName()도 참조하십시오 .
QStringList QStyleKitStyle::customThemeNames() const
Style 에 의해 정의된 사용자 정의 테마의 이름을 반환하며, 내장 테마인 Light 및 Dark 는 제외됩니다. 스타일이 로드되지 않은 경우 빈 리스트를 반환합니다.
참고: customThemeNames 속성에 대한게터 함수입니다.
참조: availableThemeNames() 함수.
[override virtual] void QStyleKitStyle::drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *w = nullptr) const
QCommonStyle::drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const를 재구현합니다.
[override virtual] void QStyleKitStyle::drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const
QCommonStyle::drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *widget) const를 재구현합니다.
[override virtual] void QStyleKitStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const
QCommonStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *widget) const를 재구현합니다.
[override virtual protected] bool QStyleKitStyle::event(QEvent *event)
QObject::event(QEvent *e)를 재구현합니다.
[override virtual protected] bool QStyleKitStyle::eventFilter(QObject *obj, QEvent *event)
QObject::eventFilter(QObject *watched, QEvent *event)를 재구현합니다.
[override virtual] QStyle::SubControl QStyleKitStyle::hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *w = nullptr) const
QCommonStyle::hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const를 재구현합니다.
[override virtual] int QStyleKitStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt = nullptr, const QWidget *widget = nullptr) const
QCommonStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt, const QWidget *widget) const를 재구현합니다.
[override virtual] void QStyleKitStyle::polish(QApplication *app)
QCommonStyle::polish(QApplication *app)를 재구현합니다.
[override virtual] void QStyleKitStyle::polish(QPalette &palette)
QCommonStyle::polish(QPalette 및 &pal)을 재구현합니다.
[override virtual] void QStyleKitStyle::polish(QWidget *widget)
QCommonStyle::polish(QWidget *widget)을 재구현합니다.
void QStyleKitStyle::setStylePath(const QString &filePath)
filePath 에 있는 QML Style 을 불러와 모든 위젯에 적용합니다.
filePath 는 로컬 파일의 경로이거나 리소스 파일 시스템 내 파일의 경로입니다. 허용되는 형식에 대해서는 stylePath 속성을 참조하십시오. 현재 stylePath 와 동일한 경우, 이 함수는 아무 작업도 수행하지 않습니다. 새 스타일을 불러올 수 없는 경우, 이전에 불러온 스타일이 활성화된 상태로 유지되며 경고가 발생합니다. 속성 값의 변경을 반영하기 위해 stylePathChanged()는 여전히 호출됩니다.
참고: stylePath 속성에 대한세터 함수입니다.
stylePath()도 참조하십시오 .
void QStyleKitStyle::setThemeName(const QString &themeName)
themeName 라는 테마를 활성화합니다.
themeName availableThemeNames()에 포함된 항목 중 하나이거나, 플랫폼 색상 구성표를 따르려면 특수 이름인 이어야 합니다. 가 로드되지 않은 경우, 이 함수는 경고를 출력하고 활성 테마를 변경하지 않은 채 반환합니다. System Style
참고: themeName 속성에 대한설정 함수입니다.
themeName() 및 availableThemeNames()도 참조하십시오 .
[override virtual] QSize QStyleKitStyle::sizeFromContents(QStyle::ContentsType ct, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget = nullptr) const
QCommonStyle::sizeFromContents(QStyle::ContentsType contentsType, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget) const를 재구현합니다.
[override virtual] QPalette QStyleKitStyle::standardPalette() const
QStyle::standardPalette() const를 재구현합니다.
[override virtual] int QStyleKitStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt = nullptr, const QWidget *w = nullptr, QStyleHintReturn *shret = nullptr) const
QCommonStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt, const QWidget *widget, QStyleHintReturn *hret) const를 재구현합니다.
QString QStyleKitStyle::stylePath() const
현재 로드된 ` Style ` 파일의 경로를 반환합니다.
참고: stylePath 속성에 대한게터 함수입니다.
참조: setStylePath().
[override virtual] QRect QStyleKitStyle::subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *w = nullptr) const
QCommonStyle::subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *widget) const를 재구현합니다.
[override virtual] QRect QStyleKitStyle::subElementRect(QStyle::SubElement r, const QStyleOption *opt, const QWidget *widget = nullptr) const
QCommonStyle::subElementRect(QStyle::SubElement sr, const QStyleOption *opt, const QWidget *widget) const를 재구현합니다.
QString QStyleKitStyle::themeName() const
현재 활성화된 테마의 이름을 반환하며, Style 가 로드되지 않은 경우에는 빈 문자열을 반환합니다.
참고: themeName 속성에 대한게터 함수입니다.
참조: setThemeName() 및 availableThemeNames().
[override virtual] void QStyleKitStyle::unpolish(QApplication *app)
QCommonStyle::unpolish(QApplication *application)를 재구현합니다.
[override virtual] void QStyleKitStyle::unpolish(QWidget *widget)
QCommonStyle::unpolish(QWidget *widget)을 재구현합니다.
© 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.