Control QML Type

すべてのコントロールに共通する機能を提供する抽象基底型。詳細…

Import Statement:	`import QtQuick.Controls`
Inherits:	Item
Inherited By:	52 types AbstractButton, BusyIndicator, Button, CheckBox, CheckDelegate, ComboBox, Container, DayOfWeekRow, DelayButton, Dial, DialogButtonBox, DoubleSpinBox, Frame, GroupBox, HorizontalHeaderViewDelegate, ItemDelegate, MenuBar, MenuBarItem, MenuItem, MenuSeparator, MonthGrid, Page, PageIndicator, Pane, ProgressBar, RadioButton, RadioDelegate, RangeSlider, RoundButton, ScrollBar, ScrollIndicator, ScrollView, SearchField, SelectionRectangle, Slider, SpinBox, SplitView, StackView, SwipeDelegate, SwipeView, Switch, SwitchDelegate, TabBar, TabButton, TableViewDelegate, ToolBar, ToolButton, ToolSeparator, TreeViewDelegate, Tumbler, VerticalHeaderViewDelegate, and WeekNumberColumn

継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

availableHeight : real
availableWidth : real
background : Item
bottomInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
bottomPadding : real
contentItem : Item
focusReason : enumeration
font : font
horizontalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
hoverEnabled : bool
hovered : bool
implicitBackgroundHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitBackgroundWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitContentHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitContentWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
leftInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
leftPadding : real
locale : Locale
mirrored : bool
padding : real
rightInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
rightPadding : real
spacing : real
topInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
topPadding : real
verticalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
visualFocus : bool
wheelEnabled : bool

詳細な説明

コントロールは、ユーザーインターフェースコントロールの基本型です。ウィンドウシステムから入力イベントを受け取り、画面上に自身の表現を描画します。

コントロールのレイアウト

次の図は、典型的なコントロールのレイアウトを示しています：

構造を示す基本的な制御

コントロールのimplicitWidth およびimplicitHeight は、通常、背景とコンテンツ項目の暗黙的なサイズに、インセットやパディングを加えたものに基づいています。これらのプロパティは、明示的なwidth やheight が指定されていない場合に、コントロールのサイズがどの程度になるかを決定します。

contentItem のジオメトリは、パディングによって決定されます。次の例では、コントロールの境界とそのコンテンツの間に10pxのパディングを確保しています：

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

background アイテムは、インセットや明示的なサイズが指定されていない限り、コントロールの幅と高さの全体を埋めます。背景のインセットは、コントロールの視覚的なサイズに影響を与えることなく、タッチ可能領域やインタラクティブ領域を拡張するのに役立ちます。これは、タッチデバイスにおいて、コントロールが小さすぎてユーザーが操作できないという事態を防ぐために頻繁に使用されます。インセットはコントロールのサイズに影響を与えるため、例えばレイアウト内で占めるスペースの量にも影響します。

負のインセットを使用すると、背景をコントロールよりも大きくすることができます。次の例では、負のインセットを使用して、コントロールの境界の外側に影を配置しています。

Control {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6

    background: BorderImage {
        source: ":/images/shadowed-background.png"
    }
}

イベント処理

非インタラクティブなインジケータを除くすべてのコントロールは、その下にあるアイテムへのクリックやタッチを透過させません。たとえば、以下の例にあるconsole.log() の呼び出しは、Paneをクリックしても決して実行されません。これは、シーン内でMouseArea がPaneの下にあるためです：

MouseArea {
    anchors.fill: parent
    onClicked: console.log("MouseArea was clicked")

    Pane {
        anchors.fill: parent
    }
}

wheelEnabled がtrue の場合、ホイールイベントはコントロールによって処理されます。

「 ApplicationWindow 」、「 Container 」、および Using Qt Quick Controls types in property declarationsを参照してください。

プロパティのドキュメント

availableHeight : real `[read-only]`

このプロパティは、コントロールのheight から垂直方向のパディングを差し引いた後、contentItem が利用できる高さを保持します。

「 Control Layout 」、「padding 」、「topPadding 」、および「bottomPadding 」も参照してください 。

availableWidth : real `[read-only]`

このプロパティは、コントロールのwidth から水平方向のパディングを差し引いた後、contentItem が利用可能な幅を保持します。

「 Control Layout 」、「padding 」、「leftPadding 」、および「rightPadding 」も参照してください 。

background : Item

このプロパティは、背景アイテムを保持します。

Button {
    id: control
    text: qsTr("Button")
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#d0d0d0" : "#e0e0e0"
    }
}

注：背景アイテムに明示的なサイズが指定されていない場合、自動的にコントロールのサイズに従います。ほとんどの場合、背景アイテムの幅や高さを指定する必要はありません。

注: ほとんどの コントロールは、背景項目の暗黙的なサイズを使用して、コントロール自体の暗黙的なサイズを計算します。背景項目をカスタム項目に置き換える場合は、その項目に適した暗黙的なサイズを設定することも検討する必要があります（Image のように、独自の暗黙的なサイズを持つ項目を除く）。

「Control Layout」も参照してください。

bottomInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、背景の下部インセットを指定します。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

Control Layout およびtopInsetも参照してください。

bottomPadding : real

このプロパティは、下方向のパディングを指定します。明示的に設定しない限り、値は `verticalPadding` となります。

Control Layout 、padding 、topPadding 、verticalPadding 、およびavailableHeightも参照してください。

contentItem : Item

このプロパティには、ビジュアルコンテンツ項目が格納されます。

Button {
    id: control
    text: qsTr("Button")
    contentItem: Label {
        text: control.text
        verticalAlignment: Text.AlignVCenter
    }
}

注: コンテンツ項目は 、コントロールのpadding 内に収まるように、自動的に配置およびサイズ調整されます。contentItemのx 、y 、width 、およびheight プロパティへのバインディングは反映されません。

注：ほとんどの コントロールは、コンテンツ項目の暗黙的なサイズを使用して、コントロール自体の暗黙的なサイズを計算します。コンテンツ項目をカスタム項目に置き換える場合は、その項目に適切な暗黙的なサイズを指定することも検討する必要があります（Text のように、独自の暗黙的なサイズを持つ項目を除く）。

「 Control Layout 」および「padding 」も参照してください 。

focusReason : enumeration

このプロパティには、前回のフォーカス変更の理由が格納されます。

このプロパティの値は、フォーカスが移動するたびに Qt によって変更されるため、ユーザー自身がこのプロパティを設定する必要は一切ありません。

注：この プロパティは、アイテムがactive focus であるかどうかを示すものではなく、アイテムがフォーカスを獲得した、あるいは失った理由を示すものです。

定数	説明
`Qt.MouseFocusReason`	マウス操作が発生しました。
`Qt.TabFocusReason`	Tab キーが押されました。
`Qt.BacktabFocusReason`	バックタブが発生しました。この入力には、Shift キーや Control キーが含まれる場合があります（例：Shift+Tab）。
`Qt.ActiveWindowFocusReason`	ウィンドウシステムによって、このウィンドウがアクティブまたは非アクティブになりました。
`Qt.PopupFocusReason`	アプリケーションが、キーボードのフォーカスを取得／解放するポップアップを開いた／閉じた。
`Qt.ShortcutFocusReason`	ユーザーがラベルのバディショートカットを入力しました
`Qt.MenuBarFocusReason`	メニューバーがフォーカスを取得しました。
`Qt.OtherFocusReason`	その他の理由（通常はアプリケーション固有）。

Item::activeFocus およびvisualFocusも参照してください。

font : font

このプロパティには、コントロールに現在設定されているフォントが格納されます。

このプロパティは、コントロールが要求するフォントを指定します。このフォントは、標準コンポーネントをレンダリングする際にコントロールのスタイルで使用され、カスタムコントロールがネイティブプラットフォームのルックアンドフィールとの一貫性を維持するための手段としても利用できます。アプリケーションにおいて、プラットフォームやスタイルが異なると、定義されるフォントも異なることが一般的です。

デフォルトのフォントはシステム環境によって異なります。ApplicationWindow は、すべてのコントロールのデフォルトとして機能するシステム/テーマフォントを保持しています。また、特定の種類のコントロールには特別なデフォルトフォントが設定されている場合もあります。コントロールのデフォルトフォントは、次のいずれかの方法で設定することもできます。

QMLを読み込む前に、QGuiApplication::setFont() にカスタムフォントを渡すか、
qtquickcontrols2.conf ファイルでフォントを指定する。

最後に、そのフォントは Qt のフォントデータベースと照合され、最も適合するフォントが選択されます。

コントロールは、明示的なフォントプロパティを親から子へと伝播します。コントロールのフォントに関する特定のプロパティを変更すると、そのプロパティはコントロールのすべての子に伝播され、そのプロパティに関するシステムのデフォルト設定を上書きします。

Page {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

利用可能なフォントプロパティの完全なリストについては、『font QML Value Type 』のドキュメントを参照してください。

horizontalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、水平方向のパディングを保持します。明示的に設定しない限り、値は `padding` になります。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

Control Layout 、padding 、leftPadding 、rightPadding 、およびverticalPaddingも参照してください。

hoverEnabled : bool

このプロパティは、コントロールがホバーイベントを受け付けるかどうかを決定します。デフォルト値は `Application.styleHints.useHoverEffects` です。

このプロパティを設定すると、hoverEnabled が明示的に設定されていないすべての子コントロールにその値が反映されます。

また、環境変数 QT_QUICK_CONTROLS_HOVER_ENABLED を設定することで、すべてのQt Quick Controlsアプリケーションのホバー効果を有効または無効にすることもできます。

「hovered」も参照してください。

hovered : bool `[read-only]`

このプロパティは、コントロールにカーソルがホバーされているかどうかを表します。

「hoverEnabled」も参照してください。

implicitBackgroundHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、暗黙的な背景の高さを保持します。

この値は `background ? background.implicitHeight : 0` と同じです。

これは通常、implicitContentHeight と組み合わせて、implicitHeight を計算するために使用されます：

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

「 implicitBackgroundWidth 」および「implicitContentHeight 」も参照してください 。

implicitBackgroundWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、暗黙的な背景の幅を保持します。

その値は `background ? background.implicitWidth : 0` に等しくなります。

これは通常、`implicitContentWidth` と組み合わせて、`implicitWidth` を計算するために使用されます:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

「 implicitBackgroundHeight 」および「implicitContentWidth 」も参照してください 。

implicitContentHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、暗黙的なコンテンツの高さを保持します。

基本的なコントロールの場合、この値は `contentItem ? contentItem.implicitHeight : 0` に等しくなります。`Container` または `Pane` を継承するタイプの場合、この値はコンテンツの子要素に基づいて計算されます。

これは通常、implicitBackgroundHeight と組み合わせて、implicitHeight を計算するために使用されます。

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

implicitContentWidth およびimplicitBackgroundHeightも参照してください。

implicitContentWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、暗黙的なコンテンツ幅を保持します。

基本的なコントロールの場合、この値は `contentItem ? contentItem.implicitWidth : 0` に等しくなります。`Container` または `Pane` を継承するタイプの場合、この値はコンテンツの子要素に基づいて計算されます。

これは通常、implicitBackgroundWidth とともに、implicitWidth を計算するために使用されます：

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

implicitContentHeight およびimplicitBackgroundWidthも参照してください。

leftInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、背景の左インセットを指定します。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

Control Layout およびrightInsetも参照してください。

leftPadding : real

このプロパティは、左側のパディングを指定します。明示的に設定しない限り、値は `horizontalPadding` となります。

Control Layout 、padding 、rightPadding 、horizontalPadding 、およびavailableWidthも参照してください。

locale : Locale

このプロパティには、コントロールのロケールが格納されます。

このプロパティには、データや数値の書式設定を行うためのロケール固有のプロパティが含まれています。特別なロケールが設定されていない限り、これは親コントロールのロケール、またはデフォルトのロケールのいずれかになります。

コントロールは、親から子へロケールを継承します。コントロールのロケールを変更すると、そのロケールがコントロールのすべての子に継承され、システムの既定のロケールが上書きされます。

「mirrored」も参照してください。

mirrored : bool `[read-only]`

このプロパティは、コントロールがミラーリングされているかどうかを示します。

このプロパティは便宜上提供されています。コントロールの視覚的なレイアウト方向が「右から左」の場合、つまり `LayoutMirroring.enabled ` が `true` の場合、そのコントロールはミラー化されているとみなされます。

Qt 6.2 以降、locale プロパティはこのプロパティに影響しなくなりました。

「 LayoutMirroring 」および「右から左へのユーザーインターフェース」も参照してください 。

padding : real

このプロパティは、デフォルトのパディングを指定します。

パディングは、コンテンツ項目の各辺と背景項目の間に余白を追加し、実質的にコンテンツ項目のサイズを制御します。コントロールの特定の辺に対するパディング値を指定するには、関連するプロパティを設定します。

注：スタイルによって、 特定のコントロールのデフォルトのパディングの指定方法が異なる場合があります 。また、そのスタイルの基盤となるデザインガイドラインの進化に伴い、指定方法も変更される可能性があります。こうした変更が、指定したパディング値に影響を与えないようにするには、利用可能なプロパティの中で最も具体的なものを使用することをお勧めします。たとえば、padding プロパティを設定する代わりに：

padding: 0

代わりに、それぞれの特定のプロパティを設定してください:

leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0

関連項目： Control Layout 、availableWidth 、availableHeight 、topPadding 、leftPadding 、rightPadding 、およびbottomPadding 。

rightInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、背景の右インセットを指定します。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

Control Layout およびleftInsetも参照してください。

rightPadding : real

このプロパティは、右側のパディングを指定します。明示的に設定されていない場合、値は `horizontalPadding` となります。

Control Layout 、padding 、leftPadding 、horizontalPadding 、およびavailableWidthも参照してください。

spacing : real

このプロパティは間隔を指定します。

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

topInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、背景の上部インセットを指定します。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

「 Control Layout 」および「bottomInset 」も参照してください 。

topPadding : real

このプロパティは、上側のパディングを指定します。明示的に設定されない限り、その値は `verticalPadding` となります。

Control Layout 、padding 、bottomPadding 、verticalPadding 、およびavailableHeightも参照してください。

verticalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

このプロパティは、垂直方向のパディングを保持します。明示的に設定しない限り、値はpadding となります。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

Control Layout 、padding 、topPadding 、bottomPadding 、およびhorizontalPaddingも参照してください。

visualFocus : bool `[read-only]`

このプロパティは、コントロールが視覚的なフォーカスを有しているかどうかを表します。コントロールがアクティブなフォーカスを有しており、そのフォーカス理由が `Qt.TabFocusReason`、`Qt.BacktabFocusReason`、または `Qt.ShortcutFocusReason` のいずれかである場合、このプロパティは `true ` となります。

一般的に、キーフォーカスを視覚化する場合は、Item::activeFocus よりもこのプロパティを使用することが推奨されます。これにより、キー操作時のみキーフォーカスが視覚化され、タッチやマウスによる操作時には表示されないことが保証されます。

focusReason およびItem::activeFocusも参照してください。

wheelEnabled : bool

このプロパティは、コントロールがホイールイベントを処理するかどうかを指定します。デフォルト値はfalse です。

注： Flickable などのスクロール可能なアイテム内のコントロールでホイールイベントを有効にする場合は注意が必要です 。コントロールがイベントを消費してしまうため、Flickable のスクロールが中断されてしまうからです。

© 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.

Control QML Type

プロパティ

詳細な説明

コントロールのレイアウト

イベント処理

プロパティのドキュメント

availableHeight : real [read-only]

availableWidth : real [read-only]

background : Item

bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

bottomPadding : real

contentItem : Item

focusReason : enumeration

font : font

horizontalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

hoverEnabled : bool

hovered : bool [read-only]

implicitBackgroundHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

implicitBackgroundWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

implicitContentHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

implicitContentWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

leftPadding : real

locale : Locale

mirrored : bool [read-only]

padding : real

rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

rightPadding : real

spacing : real

topInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

topPadding : real

verticalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

visualFocus : bool [read-only]

wheelEnabled : bool

availableHeight : real `[read-only]`

availableWidth : real `[read-only]`

bottomInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

horizontalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

hovered : bool `[read-only]`

implicitBackgroundHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

implicitBackgroundWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

implicitContentHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

implicitContentWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

leftInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

mirrored : bool `[read-only]`

rightInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

topInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

verticalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

visualFocus : bool `[read-only]`