Qt Quick コントロールのスタイル設定

利用可能なスタイル

Qt Quick Controlsには、いくつかのスタイルが用意されています。

基本スタイル

「基本スタイル」は、シンプルで軽量な汎用スタイルであり、Qt Quick コントロールにおいて最高のパフォーマンスを発揮します。

Fusion スタイル

Fusion スタイルは、プラットフォームに依存しないスタイルであり、Qt Quick コントロールにデスクトップ向けのルックアンドフィールを提供します。

Imagine スタイル

イマジン・スタイルは画像アセットに基づいています。このスタイルにはデフォルトの画像セットが付属しており、あらかじめ定義された命名規則に従って画像を格納したディレクトリを指定することで、簡単に変更することができます。

macOS スタイル

macOS スタイルは、macOS らしいネイティブな外観のスタイルです。

iOS スタイル

iOS スタイルは、画像アセットに基づいた、iOS らしい外観のスタイルです。

Material スタイル

Material スタイルは、Google の Material Design ガイドラインに基づいた魅力的なデザインを提供しますが、Basic スタイルよりも多くのシステムリソースを必要とします。

ユニバーサルスタイル

ユニバーサルスタイルは、Microsoft ユニバーサルデザインガイドラインに基づいた魅力的なデザインを提供しますが、ベーシックスタイルよりも多くのシステムリソースを必要とします。

Windows スタイル

Windows スタイルは、Windows らしい外観を持つスタイルです。

FluentWinUI3 スタイル

FluentWinUI3 スタイルは、Windows 11 以降を実行するプラットフォーム向けに設計された、モダンでネイティブな外観のスタイルであり、Fluent UI および WinUI 3 のデザインガイドラインに準拠しています。FluentWinUI3 は、サポートされているすべてのプラットフォームで実行できます。

Qt Quick コントロールでのスタイルの使用

デフォルトのスタイル

スタイルが明示的に設定されていない場合は、デフォルトのスタイルが使用されます。使用されるスタイルはオペレーティングシステムによって異なります：

• Android：Materialスタイル
• iOS:iOSスタイル
• Linux：Fusionスタイル
• 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 {
    // ...
}

ただし、プラットフォームのデフォルトを無視して、コンパイル時に特定のスタイルを1つインポートすることも可能です。たとえば、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 プラグインが使用されないため、アプリケーションとともにデプロイする必要がないことです。

また、アプリケーションが静的リンクでビルドされる場合も、明示的なインポートが必要です。

コンパイル時のスタイル選択の欠点は、各スタイルに専用の実行ファイルが必要なため、1つの実行ファイルで複数のスタイルをサポートできないことです。

コンパイル時と実行時のスタイル選択を組み合わせる方法については、「スタイル選択の混合」を参照してください。

実行時のスタイル選択

実行時のスタイル選択は、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 設定ファイル

実行時のスタイル選択の利点は、1 つのアプリケーションバイナリで複数のスタイルをサポートできることです。つまり、エンドユーザーはアプリケーションを実行する際に使用するスタイルを選択できます。

このアプローチの欠点は、QML コンパイラがどの特定のスタイルが使用されているかを把握できないため、Qt Quick Controls タイプのプロパティに対するバインディング用の C++ コードを生成できないことです。これは、他のモジュールのタイプに対するバインディング用の C++ コードを生成する QML コンパイラの機能には影響しません。

実行時とコンパイル時のスタイル選択を併用する方法については、「スタイル選択の併用」を参照してください。

スタイル固有のAPI

いくつかのスタイルでは、そのスタイル固有のAPIが公開されています。例えば、Material スタイルのアタッチメントオブジェクトやUniversalスタイルのアタッチメントオブジェクトなどです。これらのスタイル固有のAPIは、コンパイル時または実行時のスタイル選択を使用して、直接的または間接的にそのスタイルが実際に選択されている場合にのみ利用可能です。

スタイル選択の併用

アプリケーションでは、コンパイル時または実行時のいずれかのスタイル選択のみを使用することを推奨します。ただし、たとえばアプリケーションがサードパーティの QML コードを読み込む場合など、どのインポートが使用されるかを制御できない可能性があります。2 つのアプローチを併用する場合は、以下の制限事項に注意してください:

• コンパイル時のスタイル選択は、実行時のスタイル選択よりも優先されます。
• 使用したいスタイルは、他のControlsのインポートよりも常に先に明示的にインポートする必要があります。これを行わない場合、フォントやパレットなどのテーマ設定が期待どおりに動作しなくなります。また、最初に明示的にインポートされたスタイルが、QQuickStyle::name() によって報告されるスタイルとなります。
• 最後に明示的にインポートされたスタイルが、実際に使用されるものとなります。例えば、最初にQtQuick.Controls をインポートし、次にQtQuick.Controls.Material をインポートした場合、Button が作成される際には Material スタイルの Button.qml が使用されます。前述のテーマ設定に関する点からも、この理由により、同じアプリケーション内で 2 つの異なるスタイルを明示的にインポートしてはなりません。
• コンパイル時のスタイル選択を使用する予定でありながら、QtQuick.Controls をインポートするコードを読み込む場合は、スタイルが明示的にインポートされる前にQQuickStyle::name()を呼び出すと、プラットフォームのデフォルトが報告されてしまう点に注意してください。これを避けられない場合は、QQuickStyle::setStyle() または「実行時のスタイル選択」に記載されている他の方法のいずれかを使用して、事前にスタイルをコンパイル時のスタイルに合わせるように設定してください。

C++ での QQuickStyle の使用

QQuickStyle は、特定のスタイルを設定するための C++ API を提供します。次の例は、Qt Quick Controls アプリケーションを Material スタイルで実行するものです:

QQuickStyle::setStyle("Material");

詳細については、QQuickStyle の詳細な説明を参照してください。

コマンドライン引数

-style のコマンドライン引数を指定することは、さまざまなスタイルをテストするための便利な方法です。これは、以下に挙げる他の方法よりも優先されます。次の例は、Qt Quick Controlsアプリケーションを「Material」スタイルで実行します:

./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 コントロールの設定ファイル」を参照してください。

関連情報

• 基本スタイル
• Fusion スタイル
• Imagineスタイル
• マテリアル・スタイル
• ユニバーサルスタイル
• FluentWinUI3 スタイル
• Qt Quick コントロールのカスタマイズ
• Qt Quick コントロールでのファイル選択機能の使用
• Qt Quick コントロール アプリケーションのデプロイ
• Qt Quick コントロールの設定ファイル
• Qt Quick コントロールでサポートされている環境変数