UIコントロールの挿入

Components では、プリセットの UI コントロールが利用可能です > Qt Quick Controls >Controls から利用できます。

ユーザー操作に使用できるコントロールの種類は以下の通りです：

• ボタンコントロール
• インジケーター
• セレクター
• タブバー
• ツールバー
• UI コントロールの概要

「Properties 」ビューでは、コンポーネントインスタンスのプロパティの値を指定できます。プロパティには、すべてのコンポーネントに共通のものもあれば、特定の種類のコントロールに共通のものもあります。また、特定のコントロールでのみ利用可能なプロパティもあります。以下のセクションでは、プリセットのUIコントロールとそのプロパティについて説明します。

一般的なコントロールプロパティ

「Properties 」ビューで、コントロールのプロパティを設定できます。

「Enable 」チェックボックスは、コントロールが有効かどうかを示します。

「Focus policy 」フィールドの値によって、タブキー、クリック、およびマウスホイール操作によってそのコントロールにフォーカスが移動するかどうかが決まります。

「Hover 」と「Wheel 」を選択すると、コントロールがマウスイベントを受け付けるようになります。ホバー値は、子コンポーネントに対して明示的に設定されていない限り、すべての子コンポーネントに反映されます。

Spacing は、複数の構成要素や反復的な構成要素を持つコントロールに役立ちます。たとえば、一部のスタイルでは、チェックボックスのテキストとインジケーター間の距離を決定するために間隔が使用されます。間隔はコントロールによって強制されるものではないため、スタイルごとに解釈が異なり、完全に無視される場合もあります。

ボタンコントロール

Qt Quick Controls では、特定のユースケースに対応したボタン型のコントロールが用意されています。以下のセクションでは、ユースケースに最適なボタンを選択するためのガイドラインを説明し、Properties ビューでボタンのプロパティに設定できる値について解説します。

テキストを含むボタンに関する推奨事項：

• ラベルは短く簡潔にしましょう。
• UIガイドラインで特に指定がない限り、デフォルトのフォントを使用してください。
• テキストがローカライズされる場合は、テキストが長くなった場合にレイアウトにどのような影響が出るかを検討してください。

テキストのプロパティの設定に関する詳細については、「文字のプロパティ」および「パディング」を参照してください。

すべてのボタン コントロールに共通するプロパティについては、以下で説明されています：

• テキストとアイコンの表示
• チェック可能なボタン
• ボタンのシグナル

ボタン

Components のインスタンスを作成できます > Qt Quick Controls >Controls >Button:

ボタンは、ユーザーが押したりクリックしたりすることができます。通常、ボタンはアクションを実行したり、質問に答えたりするために使用されます。例えば、「OK」、「適用」、「キャンセル」、「閉じる」、「はい」、「いいえ」、「ヘルプ」などがあります。

ボタンのテキストは、そのアクションを表す動詞、または開かれるポップアップのタイトルと一致する名詞であるべきです。

状態を設定するためにボタンを使用しないでください。その目的には「スイッチ」の方が適しています。

強調表示されたボタン

「Button 」セクションで「Highlight 」を選択すると、ユーザーの注意をボタンに引き付けることができます。ボタンを強調表示しても、キーボード操作には影響しません。

以下の画像は、強調表示されたボタンの例です：

フラットボタン

フラットボタンは通常、押されたり選択されたりしない限り、背景が描画されません。フラットボタンを作成するには、「Button 」セクションで「Flat 」を選択します。

次の画像は、フラットボタンの例を示しています：

遅延ボタン

Delay Button コントロールには、アクションが実行される前に遅延時間が設定されています。この遅延により、誤操作を防ぐことができます。

タッチUIや、慎重に実行する必要があるアクションにおいて、ディレイボタンを使用してください。

「Delay 」フィールドで、遅延時間をミリ秒単位で設定できます。

チェックボックス

「Components 」のインスタンスを作成できます > Qt Quick Controls >Controls >Check Box のインスタンスを作成できます：

チェックボックスは、オン（チェック入り）またはオフ（チェックなし）に切り替え可能なオプションボタンを表します。チェックボックスは通常、一連のオプションの中から1つまたは複数のオプションを選択するために使用されます。リスト内のようにオプションの数が多い場合は、代わりにCheck Delegate コントロールのインスタンスを作成することを検討してください。

デリゲートを強調表示することで、ユーザーの注意をそのデリゲートに向けることができます。強調表示はキーボード操作には影響しません。デリゲートを強調表示するには、[Item Delegate ] セクションで [Highlight ] を選択してください。

チェックボックスを使用すると、選択肢をいくつでも（選択しない場合も含む）選択できる複数選択可能なオプションリストを作成できますが、各選択肢は互いに排他的ではありません。

ダイアログで利用規約に同意する必要がある場合など、はい／いいえの選択には単一のチェックボックスを使用します。単一のはい／いいえの選択には、スイッチを使用することもできます。ユーザーがオプションの中から選択する場合はチェックボックスを使用し、実行するアクションの中から選択する場合はスイッチの使用が推奨されます。

Button Content セクションのChecked の値によって、チェックボックスの状態が決まります。ただし、チェック済みおよび未チェックの状態に加え、チェックボックスには3つ目の状態、つまり「部分的にチェック済み」の状態があります。

「Check Box 」セクションで「Tri-state 」を選択すると、ユーザーがタッチ、マウス、またはキーボードを使用してチェックボックスを切り替えた際に、チェック済み、部分的にチェック済み、および未チェックの状態を循環できるようになります。

オプションをグループ化できる場合、部分的にチェックされたチェックボックスを使用してグループ全体を表すことができます。「Check state 」フィールドで「PartiallyChecked 」を選択すると、ユーザーがグループ内のサブコンポーネントの一部を選択したが、すべてを選択したわけではないことを示すことができます。

チェック可能なオプションは、多くの場合、縦に並べて表示されます。

チェックボックスのラベルは、チェックマークが付いている場合は真となり、チェックマークが付いていない場合は偽となるような記述であるべきです。したがって、チェックボックスのラベルには否定形の記述を含めないでください。

ラジオボタン

Radio Button は、オン（チェックあり）またはオフ（チェックなし）に切り替え可能なオプションボタンです。ラジオボタンは通常、一連の選択肢の中から1つを選択するために使用されます。選択肢を選択すると、以前の選択は自動的に解除されます。

互いに排他的な選択肢が2つしかない場合は、それらを1つのチェックボックスまたはスイッチにまとめます。

Radio Delegate はラジオボタンと似ていますが、通常はビューで使用される点が異なります。

「Radio Delegate 」セクションで「Highlight 」を選択すると、デリゲートが強調表示されます。

ラジオボタンの推奨事項：

• ラベルのテキストは1行以内に収めてください。
• 適切なデフォルトの選択肢がチェックされていることを確認してください。
• ラジオボタンの選択肢は縦に並べる。
• 選択肢の数は少なくしてください。
• 混乱を避けるため、2つのラジオボタンのグループを隣り合わせに配置しないでください。

スイッチ

Components のインスタンスを作成できます > Qt Quick Controls >Controls >Switch のインスタンスを作成できます：

スイッチとは、ドラッグしたり、オン（チェック）またはオフ（チェックなし）に切り替えたりできるオプションボタンです。スイッチは通常、オンまたは オフという2つの状態から選択するために使用されます。リスト内など、より多くの選択肢がある場合は、代わりにSwitch Delegate の使用を検討してください。

「Item Delegate 」セクションで「Highlight 」を選択すると、デリゲートが強調表示されます。

スイッチは、切り替え直後に効果が現れる二値操作に使用します。たとえば、Wi-Fiのオン/オフを切り替える際にスイッチを使用します。

丸いボタン

Round Button は、アクションを開始したり、ポップアップを開いたり閉じたりするためのクリック可能なコントロールです。四角い画像アイコンや1文字のフォントアイコンが付いた丸いボタンは円形です。円形の丸いボタンは通常のボタンよりもスペースを取らず、フローティングアクションボタンとしても使用できます。

一般的なボタンのプロパティに加え、丸型ボタンにはボタンの半径を指定するRadius プロパティがあります。

角がわずかに丸みを帯びた、比較的正方形に近いボタンを作成するには、3 などの小さな値を指定します。

完全に円形のボタンを作成するには、ボタンの幅または高さの半分に等しい値を使用し、ボタンの幅と高さを同じにします。

テキストとアイコンの表示

ボタンには、テキスト、アイコン、またはその両方を含めることができます。ボタンのテキストは、「Button Content 」セクションの「Text 」フィールドで指定します。「Display 」フィールドの値によって、テキストのみが表示されるか、アイコンのみが表示されるかが決まります。また、両方が表示される場合は、テキストがアイコンの横に配置されるか、下に配置されるかが決まります。

チェック可能なボタン

チェック可能なボタンは、ボタンにフォーカスが当たっている状態でユーザーがボタンまたはスペースバーを選択すると、チェック済み（オン）と未チェック（オフ）の間で切り替わります。ボタンをチェック可能にするには、「Checkable 」を選択します。ボタンをチェック済み状態にするには、「Checked 」を選択します。

同じ親コンポーネントに属するボタンは、相互に排他的です。ユーザーがボタンを選択してチェックを入れると、前回の選択は解除されます。ユーザーは、現在チェックされているボタンをクリックしてもチェックを解除することはできません。代わりに、そのグループ内の別のボタンを選択して、そのグループの新しいチェック対象ボタンを設定する必要があります。

ラジオボタンとタブボタンは、デフォルトで相互排他的です。他の種類のボタンを相互排他的にするには、Exclusive を選択してください。

ボタンが同じ親コンポーネントに属していない場合、ボタンのチェックやチェック解除を行っても、グループ内の他のボタンには影響しません。

ボタンのシグナル

ボタンは、ユーザーによってアクティブ化されると、clicked() シグナルを発信します。このシグナルに接続することで、ボタンのアクションを実行できます。ボタンには、長押し時に発せられる以下の追加シグナルがあります：canceled() 、doubleClicked() 、pressed() 、released() 、およびpressAndHold() 。

「Auto-repeat 」を選択すると、ボタンが長押しされている間、pressed() 、released() 、およびclicked() のシグナルが繰り返し送信されます。pressAndHold() のシグナルは送信されません。

インジケータ

Qt Quick Controls では、特定のユースケース向けに、ビジーインジケータ、ページインジケータ、プログレスバーなど、インジケータのようなコントロールが用意されています。以下のセクションでは、ユースケースに最適なインジケータを選択するためのガイドラインを説明します。

ビジーインジケーター

Busy Indicator 操作が進行中であり、UIがその操作が完了するまで待機する必要があることを示します。

ビジーインジケーターは、不確定な進行状況を示すプログレスバーと似ています。どちらもバックグラウンドでの処理を示するために使用できます。主な違いは視覚的な点にあり、プログレスバーは（進行状況が特定できる場合）具体的な進行度も表示できる点です。この視覚的な違いにより、ビジーインジケーターと不確定なプログレスバーは、UI内の異なる場所に配置されます。

「Running 」を選択すると、ビジーインジケーターが表示されます。

Live を選択すると、進行状況をリアルタイムで更新できます。

ビジーインジケーターが通常表示される場所は以下の通りです：

• Tool Bar の隅。
• Page の上にオーバーレイとして表示。
• Item Delegate の側面。

ページインジケーター

Page Indicator は、複数のページからなるコンテナ内で、現在アクティブなページを示すために使用されます。「Count 」フィールドでページ数を指定してください。「Current 」フィールドで現在のページを選択してください。

「Interactive 」を選択すると、ページインジケーターが押下操作に反応し、「Current 」フィールドの値がそれに応じて自動的に変更されるようになります。

ページインジケーターは、ユーザーが UI の実際のコンテンツに集中できるよう、通常は非常に小さく設計されています。そのため、クリックしにくかったり、ユーザーからインタラクティブな要素として認識されにくかったりする可能性があります。これらの理由から、ページインジケーターは「Swipe View 」などの主要なナビゲーション方法を補完するために使用するのが最適であり、それらに取って代わるものではありません。

プログレスバー

Progress Bar 操作の進行状況を示します。初期値は「Value 」フィールドで指定できますが、定期的に更新する必要があります。「From 」および「To 」フィールドで範囲を指定しますが、どちらのフィールドにも任意の値を入力できます。

ダウンロード対象のアイテムのサイズが不明な場合や、ネットワーク障害によりダウンロードの進行が中断される可能性がある場合は、「Indeterminate 」を選択してください。

「不確定モード」は、「ビジーインジケーター」と同様に、バックグラウンドでの処理を示唆するために使用できます。視覚的な違いがあるため、不確定モードのプログレスバーとビジーインジケーターは、UI上の配置場所が異なります。

不確定プログレスバーが一般的に配置される場所は以下の通りです：

• Tool Bar の下部。
• Page のコンテンツ内にインラインで配置。
• Item Delegate 内で、特定の項目の進行状況を示す場合。

セレクタ

Qt Quick Controls では、スライダー、ダイヤル、スピンボックス、コンボボックス、タンブラーなど、特定のユースケース向けのセレクターのようなコントロール一式が用意されています。以下のセクションでは、ユースケースに最適なセレクターを選択するためのガイドラインを説明します。

スライダーとダイヤル

Components のインスタンスを作成できます > Qt Quick Controls >Controls >Slider のように、インスタンスを作成できます：

スライダーは、トラックに沿ってハンドルをスライドさせて値を選択するために使用されますが、Range Slider は、各ハンドルをトラックに沿ってスライドさせ、2つの値で指定された範囲を選択するために使用されます。

Dial は、ステレオや産業用機器などに搭載されている従来のダイヤルノブに似ています。これにより、ユーザーは範囲内の値を指定することができます。

Components のインスタンスを作成できます > Qt Quick Controls >Controls >Dial:

「From 」および「To 」フィールドで、スライダーまたはダイヤルの範囲を設定します。「Value 」フィールドで、スライダーハンドルまたはダイヤルの値を設定します。範囲スライダーの場合は、「Value 1 」および「Value 2 」フィールドで、1番目と2番目のハンドルの初期位置を設定します。「Live 」を選択すると、値プロパティがリアルタイムで更新されます。

「Snap mode 」フィールドで、「Step size 」フィールドの値に対して、スライダーのハンドルやダイヤルがどのように動作するかを設定します。デフォルトではステップサイズにスナップしませんが、ドラッグ中にスナップさせるか、ドラッグを解除した後にスナップさせるように設定できます。

「Orientation 」フィールドでは、スライダーの向きを水平または垂直に設定できます。

「Drag threshold 」を変更して、タッチドラッグイベントが開始されるしきい値を決定します。

詳細については、以下の動画をご覧ください：

ダイヤルでは、円形、水平、垂直の各入力モードがサポートされています。高速な入力が重要なアプリケーションでは、円形入力モードが便利です。ダイヤルをクリックすると、その位置に直接移動します。 正確な入力が重要なアプリケーションでは、水平および垂直入力モードが推奨されます。これらのモードでは、ダイヤルをクリックした位置を基準に微調整を行うことができます。また、オーディオの音量を制御するダイヤルなど、値が急激に変化すると危険な場合にも、これらのモードが適しています。入力モードは、「Input mode 」フィールドで設定します。

スピンボックス

Components のインスタンスを作成できます > Qt Quick Controls >Controls >Spin Box:

スピンボックスを使用すると、ユーザーは上向きまたは下向きのインジケーターボタンをクリックするか、キーボードの上下キーを押すことで、整数値を選択できます。「Editable 」を選択すると、ユーザーが入力フィールドにテキスト値を入力できるようになります。

その他のスピンボックスのプロパティは、Dial のプロパティと同様です。

コンボボックス

Combo Box は、ボタンとポップアップリストを組み合わせたものです。画面上のスペースを最小限に抑えつつ、ユーザーに選択肢のリストを表示する手段を提供します。

コンボボックスは、静的な複数行のドロップダウンリストから値を選択するために使用されます。ユーザーは新しい値を追加することはできず、選択できるオプションは1つだけです。

コンボボックスの値はデータモデルによって提供されます。データモデルは通常、JavaScriptの配列、ListModel 、または整数ですが、その他のタイプのデータモデルもサポートされています。

「Editable 」を選択すると、モデルに定義されている内容に基づいて、コンボボックスのテキストが自動補完されます。

複数の名前付きロールを持つモデルを使用する場合は、[Text role ]フィールドでDisplay text プロパティのロールを指定します。テキストロールに対応するモデル項目のロールを使用するには、このフィールドに「valueRole 」と入力します。

「Current index 」フィールドには、コンボボックスに表示される項目のインデックスが格納されます。コンボボックスが空の場合、デフォルト値は「-1 」となり、それ以外の場合は「0 」となります。

フラットなコンボボックスは、操作が行われない限り背景が描画されないため、UIに溶け込みます。たとえば、ツールバー上でツールボタンのフラットな外観に合わせて、フラットなコンボボックスを使用します。フラットなコンボボックスを作成するには、[Flat] を選択します。

コンボボックスに関する推奨事項：

• 値の数が非常に多い場合は、フィルタの適用を検討してください。
• 値の数が少ない場合は、ユーザーがすべてのオプションを同時に確認できるよう、ラジオボタンの使用を検討してください。
• デフォルト値を設定してください。この値は、最も頻繁に選択されると予想される値にしてください。

タンブラー

Tumbler ユーザーが、項目が並んだ回転式ホイールから選択肢を選択できるようにします。これは、ラジオボタンのように選択肢が多すぎる場合や、編集可能なスピンボックスを使うほど選択肢が少ない場合に便利です。キーボード操作を必要とせず、項目数が多くなっても両端で自動的に循環するため、使い勝手が良いです。

「Visible count 」フィールドで、表示するオプションの数を指定します。「Current index 」フィールドで、現在のオプションのインデックスを選択します。

折り返しを有効にするには、[Wrap] を選択します。

タブバー

Tab Bar は、タブベースのナビゲーションモデルを提供し、ユーザーはさまざまなビューやサブタスクを切り替えることができます。タブバーは、通常、ApplicationWindow のヘッダーまたはフッターとして使用されます。Position フィールドでツールバーの位置を選択します。

通常、タブバーには、その子要素として定義された一連の静的なTab Button コントロールが含まれます。「Container 」セクションの「Current index 」フィールドには、現在のタブボタンのインデックスが表示されます。タブバーが空の場合、デフォルト値は「-1 」となり、それ以外の場合は「0 」となります。

Content size フィールドでは、コンテンツの幅（W ）と高さ（H ）を指定できます。

ボタンの合計幅がタブバーの利用可能な幅を超える場合、自動的にフリック操作が可能になります。

ツールバー

Tool Bar には、ナビゲーションボタンや検索フィールドなど、アプリケーション全体で共通して使用されるアクションや、コンテキストに応じたアクションやコントロールが含まれます。ツールバーは通常、ApplicationWindow のヘッダーまたはフッターとして使用されます。Position フィールドでツールバーの位置を選択してください。

Tool Button はButton とほぼ同じですが、ツールバーへの挿入に適したグラフィック外観を持っています。

ツールバー自体には独自のレイアウトは用意されておらず、RowLayout を作成するなどして、その内容を配置する必要があります。ツールバーに項目が 1 つしか含まれていない場合、その項目の暗黙的なサイズに合わせてツールバーのサイズが調整されます。このため、ツールバーはレイアウトとの併用に特に適しています。 ただし、Pane セクションのContent size フィールドで、コンテンツの幅（W ）と高さ（H ）を指定することは可能です。

Tool Separator は、ツールバー上のアイテムのグループを線で区切ることで視覚的に区別するために使用されます。「Orientation 」フィールドの値を設定することで、水平または垂直のツールバーで使用できます。

スタイル設定コントロール

プリセットの UI コントロールはスタイル設定が可能です。「2D 」ビューは、設定ファイル（qtquickcontrols2.conf ）から優先スタイルを読み込みます。スタイルを変更するには、メインツールバーのリストから別のスタイルを選択してください。これにより、利用可能なスタイルを使用した場合の UI の外観を確認できます。

独自のスタイルを定義し、デザインモードでそれを使用する例については、「Qt Quick Controls - フラットスタイル」を参照してください。

特定のコントロールのカスタマイズ方法の詳細については、「カスタマイズリファレンス」を参照してください。

UI コントロールの概要

次の表に、プリセットの UI コントロールと、それぞれの開発者向けドキュメントへのリンクを一覧表示します。これらは「Components > Qt Quick Controlsで利用可能です。「MCU サポート」の列は、MCU でサポートされているコントロールを示しています。