UIコントロールの挿入

プリセットのUIコントロールは、Components >で利用可能です。 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、Apply、Cancel、Close、Yes、No、Helpなどです。

ボタンのテキストは、アクションを説明する動詞、または開かれるポップアップのタイトルに一致する名詞でなければなりません。

状態を設定するためにボタンを使用しないでください。

ハイライトされたボタン

ユーザーの注意をボタンに向けるには、Button セクションでHighlight を選択してください。ボタンをハイライトしても、キーボード操作には影響しません。

次の画像はハイライトされたボタンの例です：

フラットボタン

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

次の画像はフラット・ボタンの例です：

遅延ボタン

Delay Button コントロールには、アクションをトリガーする前にディレイが組み込まれています。このディレイにより、誤って押してしまうことを防ぎます。

ディレイボタンは、タッチUIや、注意してトリガーしなければならないアクションに使用します。

Delay 、ミリ秒単位でディレイを設定できます。

チェックボックス

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

チェックボックスは、オン（チェック済み）またはオフ（チェックなし）に切り替えることができるオプションボタンを示します。チェックボックスは通常、オプションのセットから1つ以上のオプションを選択するために使用されます。リストのような大きなオプションのセットでは、代わりにCheck Delegate コントロールのインスタンスを作成することを検討してください。

デリゲートは、ユーザーの注意を引くためにハイライトすることができます。ハイライトはキーボード操作には影響しません。デリゲートをハイライトするには、Item Delegate セクションのHighlight を選択します。

チェックボックスを使用して、複数選択可能なオプションリストを作成します。ここでは、何も選択しない場合を含め、任意の数のオプションを選択することができますが、オプションは相互に排他的ではありません。

ユーザーがダイアログで利用規約に同意しなければならない場合など、「はい/いいえ」の選択には1つのチェックボックスを使用します。Yes/Noの選択にはSwitchを使用することもできます。ユーザーが選択肢を選ぶ場合は、チェックボックスを使用してください。ユーザーが取るべき行動を選択する場合は、switchをお勧めします。

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 を選択し、デリゲートをハイライトします。

スイッチを切り替えた直後に有効になるバイナリ操作には、スイッチを使用します。例えば、WiFiのオン/オフを切り替えるにはスイッチを使います。

ラウンドボタン

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

一般的なButtonプロパティに加え、丸ボタンはボタンの半径を保持するRadius プロパティを持っています。

角をわずかに丸めた比較的四角いボタンを作成するには、3などの小さな値を使用します。

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

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

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

チェック可能なボタン

チェック可能なボタンは、ボタンにアクティブなフォーカスがあるときに、ユーザーがそのボタンまたはスペースバーを選択すると、チェックされた状態（オン）とチェックされていない状態（オフ）に切り替わります。ボタンをチェック可能にするには、Checkable を選択します。ボタンをチェック可能にするには、Checked を選択します。

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

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

ボタンが同じ親に属していない場合、ボタンをチェックしたり、チェックを外したりしても、グループ内の他のボタンには影響しません。

ボタンのシグナル

ボタンは、ユーザーによってアクティブにされると、clicked() シグナルを発信します。ボタンのアクションを実行するには、このシグナルに接続します。ボタンは以下の追加シグナルを提供します：canceled() doubleClicked(),pressed(),released(),pressAndHold() 長押し用。

ボタンを押し続けている間、pressed() 、released() 、clicked() 信号を繰り返すには、Auto-repeat を選択します。pressAndHold() シグナルは出力されません。

インジケーター

Qt Quick Controls は、ビジー・インジケータ、ページ・インジケータ、プログレス・バーなど、インジケータのようなコントロールを特定のユースケース向けに提供します。以下のセクションでは、ユースケースに最も適したインジケーターを選択するためのガイドラインを示します。

ビジー・インジケータ

Busy Indicator は、操作が進行中であり、UIが操作の完了を待たなければならないことを示します。

ビジーインジケータは、不確定なプログレスバーに似ています。どちらもバックグラウンドのアクティビティを示すために使用できます。主な違いは視覚的なもので、プログレスバーは具体的な進捗量を示すこともできます（決定できる場合）。視覚的な違いにより、ビジー・インジケータと不確定プログレス・バーはUIの異なる場所に適合します。

ビジー・インジケータを表示するには、Running 。

進捗のライブアップデートを提供するには、Live を選択してください。

ビジーインジケータの典型的な場所は以下のとおりです：

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

ページインジケータ

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

ページ・インジケータが押されたことに反応し、それに応じてCurrent フィールドの値を自動的に変更することを決定するには、Interactive を選択する。

ページ・インジケータは通常、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つのアイテムだけを含む場合、それは暗黙のアイテムのサイズに合わせてリサイズされます。このため、ツールバーは特にレイアウトとの併用に適しています。ただし、コンテンツの幅 (W) と高さ (H) は、Pane セクションのContent size フィールドで指定できます。

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

コントロールのスタイリング

プリセットされたUIコントロールは、スタイルを設定することができます。2D ビューは、設定ファイル(qtquickcontrols2.conf)から好みのスタイルを読み込む。スタイルを変更するには、メインツールバーのリストから別のスタイルを選択します。これにより、利用可能なスタイルを使用したときのUIの外観を確認することができます。

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

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

UI コントロールの概要

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