스타일링 Qt Quick Controls

사용 가능한 스타일

Qt Quick Controls 다양한 스타일이 제공됩니다.

기본 스타일

기본 스타일은 심플하고 가벼운 만능 스타일로, Qt Quick Controls 에서 최고의 성능을 발휘합니다.

퓨전 스타일

퓨전 스타일은 플랫폼에 구애받지 않는 스타일로, Qt Quick Controls 에 데스크톱 중심의 룩앤필을 제공합니다.

Imagine 스타일

Imagine 스타일은 이미지 자산을 기반으로 합니다. 이 스타일에는 기본 이미지 세트가 포함되어 있으며, 미리 정의된 명명 규칙을 따르는 이미지 디렉터리를 지정하여 쉽게 변경할 수 있습니다.

macOS 스타일

macOS 스타일은 macOS에 최적화된 네이티브 스타일입니다.

iOS 스타일

iOS 스타일은 이미지 자산을 기반으로 한 iOS용 네이티브 스타일입니다.

머티리얼 스타일

머티리얼 스타일은 Google 머티리얼 디자인 가이드라인을 기반으로 한 매력적인 디자인을 제공하지만, 기본 스타일보다 더 많은 시스템 리소스를 필요로 합니다.

유니버설 스타일

유니버설 스타일은 Microsoft 유니버설 디자인 가이드라인을 기반으로 한 매력적인 디자인을 제공하지만, 기본 스타일보다 더 많은 시스템 리소스를 필요로 합니다.

Windows 스타일

Windows 스타일은 Windows에 최적화된 네이티브 스타일입니다.

FluentWinUI3 스타일

FluentWinUI3 스타일은 Windows 11 이상을 실행하는 플랫폼을 위해 설계된 현대적이고 네이티브한 느낌의 스타일로, Fluent UI 및 WinUI 3 디자인 가이드라인을 따릅니다. FluentWinUI3는 지원되는 모든 플랫폼에서 실행할 수 있습니다.

스타일 사용 Qt Quick Controls

기본 스타일

스타일이 명시적으로 설정되지 않은 경우 기본 스타일이 사용됩니다. 사용되는 스타일은 운영 체제에 따라 다릅니다:

• Android: Material 스타일
• iOS: iOS 스타일
• Linux: 퓨전 스타일
• macOS: macOS 스타일
• Windows: Windows 스타일

그 외의 모든 운영 체제에서는 기본 스타일이 사용됩니다.

컴파일 시점 스타일 선택

컴파일 시점 스타일 선택은 QML에서 스타일을 직접 또는 간접적으로 임포트하여 사용할 스타일을 지정하는 방법입니다. 컴파일 시점에 선택되므로, 컴파일 시점 스타일 선택을 사용하는 경우 실행 시점에 스타일을 변경할 수 없습니다.

컴파일 시점 스타일 선택을 사용하는 가장 편리한 방법은 `QtQuick.Controls.Native ` 스타일을 임포트하는 것입니다. ` QtQuick.Controls.Native `는 대상 플랫폼의 기본 스타일을 자동으로 임포트합니다. ` QtQuick.Controls.Native`를 임포트하는 경우, 다른 특정 스타일이나 (실행 시점에 선택되는) ` QtQuick.Controls ` 모듈을 임포트해서는 안 됩니다. ` QtQuick.Controls.Native `는 플랫폼 기본 스타일을 자동으로 임포트하며, 해당 스타일이 대체 스타일을 처리합니다. 동시에 두 개 이상의 최상위 스타일을 가질 수는 없습니다. 예를 들어:

// Refrain from importing QtQuick.Controls or specific styles.
import QtQuick.Controls.Native

ApplicationWindow {
    // ...
}

하지만 플랫폼 기본값을 무시하고 컴파일 시점에 특정 스타일을 하나만 가져올 수도 있습니다. 예를 들어, Material 스타일을 가져오려면 다음과 같이 합니다:

// The style must be imported before any other QtQuick.Controls imports
// in order for run-time style selection API like QQuickStyle::name() to
// work.
import QtQuick.Controls.Material

ApplicationWindow {
    // ...
}

QtQuick.Controls (런타임 스타일 선택을 담당함)은 임포트되지 않는다는 점에 유의하십시오. 대체 스타일은 스타일의 qmldir에 의해 지정됩니다:

module QtQuick.Controls.Material
# ...
import QtQuick.Controls.Basic auto

컴파일 시점 스타일 선택의 장점은 QML 컴파일러가 어떤 특정 스타일이 사용 중인지 파악하여 바인딩용 C++ 코드를 생성할 수 있다는 점입니다.

또 다른 장점은 QtQuick.Controls 플러그인이 사용되지 않으므로 애플리케이션과 함께 배포할 필요가 없다는 점입니다.

애플리케이션을 정적으로 빌드하는 경우에도 명시적 임포트가 필요합니다.

컴파일 시간 스타일 선택의 단점은 각 스타일마다 별도의 실행 파일이 필요하기 때문에 하나의 실행 파일이 여러 스타일을 지원할 수 없다는 점입니다.

컴파일 시간 및 런타임 스타일 선택의 혼합에 대한 자세한 내용은 스타일 선택 혼합을 참조하십시오.

런타임 스타일 선택

런타임 스타일 선택은 QtQuick.Controls 를 임포트하여 사용할 스타일을 지정하는 방법입니다.

import QtQuick.Controls

QtQuick.Controls 플러그인은 다음 방법 중 하나를 통해 런타임에 설정된 스타일을 가져옵니다:

• QQuickStyle::setStyle()
• -style 명령줄 인수
• QT_QUICK_CONTROLS_STYLE 환경 변수
• qtquickcontrols2.conf 구성 파일

이러한 방법의 우선순위는 나열된 순서대로, 가장 높은 것부터 낮은 순으로 적용됩니다. 즉, 예를 들어 QQuickStyle 를 사용하여 스타일을 설정하는 것이 명령줄 인수를 사용하는 것보다 항상 우선합니다.

마찬가지로, 대체 스타일은 다음 방법 중 하나를 통해 설정할 수 있습니다:

• QQuickStyle::setFallbackStyle()
• QT_QUICK_CONTROLS_FALLBACK_STYLE 환경 변수
• qtquickcontrols2.conf 구성 파일

런타임 스타일 선택의 장점은 단일 애플리케이션 바이너리가 여러 스타일을 지원할 수 있어, 최종 사용자가 애플리케이션을 실행할 때 사용할 스타일을 선택할 수 있다는 점입니다.

이 접근 방식의 단점은 QML 컴파일러가 어떤 특정 스타일이 사용 중인지 알 수 없기 때문에 Qt Quick Controls 유형의 속성에 대한 바인딩용 C++ 코드를 생성할 수 없다는 것입니다. 이는 다른 모듈의 유형에 대한 바인딩용 C++ 코드를 생성하는 QML 컴파일러의 기능에는 영향을 미치지 않습니다.

런타임 및 컴파일타임 스타일 선택의 혼합에 대한 정보는 ‘스타일 선택 혼합’을 참조하십시오.

스타일별 API

일부 스타일은 해당 스타일에 특화된 API를 제공합니다. 예를 들어, Material 스타일의 첨부 객체나 Universal 스타일의 첨부 객체가 있습니다. 이러한 스타일별 API는 컴파일 시점 또는 런타임 스타일 선택을 통해 해당 스타일이 직접적이든 간접적이든 실제로 선택된 경우에만 사용할 수 있습니다.

스타일 선택 혼합

애플리케이션에서는 컴파일 시간 또는 런타임 스타일 선택 중 하나만 사용하는 것이 권장됩니다. 그러나 애플리케이션이 타사 QML 코드를 로드하는 경우, 어떤 임포트가 사용되는지 제어할 수 없을 수도 있습니다. 두 방식을 혼합하여 사용하는 경우, 다음 제한 사항을 유의해야 합니다:

• 컴파일 시간 스타일 선택은 런타임 스타일 선택보다 우선합니다.
• 사용하려는 스타일은 다른 모든 컨트롤(Controls)을 임포트하기 전에 항상 명시적으로 임포트해야 합니다. 이렇게 하지 않으면 테마(글꼴 및 팔레트 등)가 예상대로 작동하지 않습니다. 또한 QQuickStyle::name() 함수는 가장 먼저 명시적으로 임포트된 스타일을 반환합니다.
• 마지막으로 명시적으로 임포트된 스타일이 실제로 사용됩니다. 예를 들어, QtQuick.Controls 을 먼저 임포트한 다음 QtQuick.Controls.Material 을 임포트하면, Button이 생성될 때 Material 스타일의 Button.qml이 사용됩니다. 앞서 언급한 테마 관련 사항 때문에, 동일한 애플리케이션에서 두 가지 다른 스타일을 명시적으로 임포트해서는 안 됩니다.
• 컴파일 시점 스타일 선택을 사용하려는 경우, QtQuick.Controls 를 임포트하는 코드를 로드한다면, 스타일이 명시적으로 임포트되기 전에 QQuickStyle::name()를 호출하면 플랫폼 기본값이 반환된다는 점에 유의해야 합니다. 이를 피할 수 없다면, QQuickStyle::setStyle() 또는 ‘런타임 스타일 선택’에 나열된 다른 방법 중 하나를 통해 미리 스타일을 컴파일 시점 스타일과 일치하도록 설정해야 합니다.

C++에서 QQuickStyle 사용하기

QQuickStyle 는 특정 스타일을 구성하기 위한 C++ API를 제공합니다. 다음 예제는 Material 스타일로 Qt Quick Controls 애플리케이션을 실행합니다:

QQuickStyle::setStyle("Material");

자세한 내용은 QQuickStyle 에 대한 설명서를 참조하십시오.

명령줄 인수

-style 명령줄 인수를 전달하는 것은 다양한 스타일을 테스트하는 편리한 방법입니다. 이 방법은 아래에 나열된 다른 방법들보다 우선합니다. 다음 예제는 Material 스타일로 Qt Quick Controls 애플리케이션을 실행합니다:

./app -style Material

환경 변수

QT_QUICK_CONTROLS_STYLE 환경 변수를 설정하면 시스템 전체에 적용되는 스타일 기본값을 지정할 수 있습니다. 이 방법은 아래에 언급된 구성 파일보다 우선합니다. 다음 예제는 Qt Quick Controls 애플리케이션을 Universal 스타일로 실행합니다:

QT_QUICK_CONTROLS_STYLE=Universal ./app

지원되는 환경 변수의 전체 목록은 Qt Quick Controls 의 ‘지원되는 환경 변수’를 참조하십시오.

구성 파일

Qt Quick Controls 는 애플리케이션 리소스에 내장된 특수 구성 파일인 :/qtquickcontrols2.conf 을 지원합니다.

이 구성 파일에서는 선호하는 스타일(앞서 설명한 두 가지 방법 중 하나로 재정의될 수 있음)과 특정 스타일별 속성을 지정할 수 있습니다. 다음 예제는 선호하는 스타일을 Material 스타일로 지정합니다.

[Controls]
Style=Material

구성 파일에 대한 자세한 내용은 Qt Quick Controls 구성 파일을 참조하십시오.

관련 정보

• 기본 스타일
• Fusion 스타일
• Imagine 스타일
• 머티리얼 스타일
• 범용 스타일
• FluentWinUI3 스타일
• 사용자 지정 Qt Quick Controls
• 파일 선택기 사용 Qt Quick Controls
• Qt Quick Controls 애플리케이션 배포
• Qt Quick Controls 구성 파일
• 에서 지원되는 환경 변수 Qt Quick Controls