Popup QML Type

ポップアップ形式のユーザーインターフェースコントロールの基底型。詳細...

Import Statement:	`import QtQuick.Controls`
Inherits:	QtObject
Inherited By:	Dialog, Drawer, Menu, and ToolTip

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

プロパティ

activeFocus : bool
anchors.centerIn : Item (since QtQuick.Controls 2.5 (Qt 5.12))
availableHeight : real
availableWidth : real
background : Item
bottomInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
bottomMargin : real
bottomPadding : real
clip : bool
closePolicy : enumeration
contentChildren : list<Item>
contentData : list<QtObject>
contentHeight : real
contentItem : Item
contentWidth : real
dim : bool
enabled : bool (since QtQuick.Controls 2.3 (Qt 5.10))
enter : Transition
exit : Transition
focus : bool
font : font
height : real
horizontalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
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))
implicitHeight : real
implicitWidth : real
leftInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
leftMargin : real
leftPadding : real
locale : Locale
margins : real
mirrored : bool (since QtQuick.Controls 2.3 (Qt 5.10))
modal : bool
opacity : real
opened : bool (since QtQuick.Controls 2.3 (Qt 5.10))
padding : real
palette : palette (since QtQuick.Controls 2.3 (Qt 5.10))
parent : Item
popupType : enumeration (since 6.8)
rightInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
rightMargin : real
rightPadding : real
scale : real
spacing : real (since QtQuick.Controls 2.1 (Qt 5.8))
topInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
topMargin : real
topPadding : real
transformOrigin : enumeration
verticalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
visible : bool
width : real
x : real
y : real
z : real

信号

void aboutToHide()
void aboutToShow()
void closed()
void opened()

方法

void close()
void forceActiveFocus(enumeration reason)
void open()

詳細説明

Popupは、ポップアップ形式のユーザーインターフェースコントロールの基本タイプです。Window やApplicationWindow と組み合わせて使用できます。

import QtQuick.Window
import QtQuick.Controls

ApplicationWindow {
    id: window
    width: 400
    height: 400
    visible: true

    Button {
        text: "Open"
        onClicked: popup.open()
    }

    Popup {
        id: popup
        x: 100
        y: 100
        width: 200
        height: 300
        modal: true
        focus: true
        closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent
    }
}

Popupは独自のレイアウトを提供せず、RowLayout やColumnLayout を作成するなどして、コンテンツを配置する必要があります。

Popupの子として宣言されたアイテムは、自動的にそのPopupのcontentItem の子となります。動的に作成されたアイテムは、明示的にcontentItem の子として設定する必要があります。

次の図は、ウィンドウ内のポップアップのレイアウトを示しています：

コンテンツの上に重なるポップアップウィンドウ

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

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

Popup {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

background アイテムは、インセットや明示的なサイズが指定されていない限り、ポップアップの幅と高さの全体を埋めます。

負のインセットを使用すると、背景をポップアップよりも大きく表示できます。次の例では、負のインセットを使用して、ポップアップの境界の外側に影を配置しています:

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

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

Qt 6.8以降、Menu などの一部のポップアップでは、プラットフォームに応じて3つの異なる実装が提供されています。popupType を設定することで、好みの実装を選択できます。

ポップアップが優先されるタイプを使用できるかどうかは、プラットフォームによって異なります。Popup.Item はすべてのプラットフォームでサポートされていますが、Popup.Window およびPopup.Native は通常、デスクトッププラットフォームでのみサポートされています。さらに、ポップアップがnative menubar 内のMenu である場合、そのメニューもネイティブ形式になります。また、メニューが別のメニュー内のサブメニューである場合、そのタイプは親（またはルート）メニューによって決定されます。

popupType をPopup.Item に設定すると、ポップアップは独立したウィンドウとしてではなく、親と同じシーン内のアイテムとして表示されます。このアイテムは、そのシーンのoverlay の子として配置され、実際のウィンドウのように見えるようスタイルが設定されます。

このオプションは、複数のウィンドウをサポートしていないプラットフォームで特に役立ちます。また、Qt 6.8以前は、これが唯一のオプションでした。

ポップアップをシーン内の他のアイテムよりも上に表示させるためには、ApplicationWindow の使用をお勧めします。ApplicationWindow には、背景を暗くする効果も用意されています。

popupType をPopup.Window に設定すると、ポップアップはQt::Popup フラグが設定されたトップレベルのwindow 内に表示されます。ウィンドウを使用してポップアップを表示する利点は、ポップアップが親ウィンドウの上に浮いて表示され、そのジオメトリの外側に配置できることです。それ以外の場合、ポップアップの外観はPopup.Item を使用した場合と同じになります。つまり、Popup.Item を使用する場合と同じQMLデリゲートとスタイルが使用されます。

注：プラットフォームが `Popup.Window` をサポートしていない場合、フォールバックとして `Popup.Item ` が使用されます。

popupType をPopup.Native に設定すると、プラットフォーム固有のポップアップウィンドウを使用してポップアップが表示されます。このウィンドウとそのすべてのコンテンツは、QML ではなくプラットフォームによってレンダリングされます。つまり、ポップアップに割り当てられた QML デリゲートは、レンダリングには使用されません。例えば、Menu でこのオプションを使用すると、プラットフォーム固有のメニューAPIを使用して実装されます。これにより、通常はPopup.Window などよりもポップアップの外観や操作感がネイティブに近づきますが、その一方で、外観や動作に関するプラットフォームの制限や差異の影響を受けることになります。このような制限については、影響を受けるサブクラス（Menu など）でより詳細に説明されています。

注：プラットフォームがPopup.Native をサポートしていない場合、Popup.Window がフォールバックとして使用されます。

ポップアップ内で 1 つのアイテムのみが使用される場合、ポップアップは、そのアイテムの暗黙的なサイズに合わせてサイズが調整されます。このため、レイアウトとの併用に特に適しています。

Popup {
    ColumnLayout {
        anchors.fill: parent
        CheckBox { text: qsTr("E-mail") }
        CheckBox { text: qsTr("Calendar") }
        CheckBox { text: qsTr("Contacts") }
    }
}

場合によっては、ポップアップ内に2つのアイテムが含まれることもあります：

Popup {
    SwipeView {
        // ...
    }
    PageIndicator {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
    }
}

この場合、Popupは適切な暗黙的なサイズを算出できません。PageIndicator をSwipeView の上に配置しているため、コンテンツサイズをビューの暗黙的なサイズに設定するだけで済みます：

Popup {
    contentWidth: view.implicitWidth
    contentHeight: view.implicitHeight

    SwipeView {
        id: view
        // ...
    }
    PageIndicator {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
    }
 }

注： popup itemsを使用する場合、ポップアップのcontent item はoverlay の子となり、ポップアップの親要素内には存在しません。そのため、ポップアップが存在するツリーに適用されたscale は、視覚的なポップアップには適用されません。例えば、ComboBox のポップアップをコンボボックスのスケールに合わせて表示するには、overlay にも同じスケールを適用します。

Window {
    property double scaleFactor: 2.0

    Scale {
        id: scale
        xScale: scaleFactor
        yScale: scaleFactor
    }
    Item {
        id: scaledContent
        transform: scale

        ComboBox {
            id: combobox
            // ...
        }
    }

    Overlay.overlay.transform: scale
}

Qt Quick の項目と同様に、ポップアップのx およびy 座標は親要素を基準としています。つまり、例えばButton の子であるポップアップを開くと、ポップアップはボタンを基準に配置されます。

次の例では、添付されたOverlay.overlay プロパティを使用して、ポップアップを開くボタンの位置に関係なく、ポップアップをウィンドウの中央に配置しています：

Button {
    onClicked: popup.open()

    Popup {
        id: popup

        parent: Overlay.overlay

        x: Math.round((parent.width - width) / 2)
        y: Math.round((parent.height - height) / 2)
        width: 100
        height: 100
    }
}

親アイテムに関係なくポップアップをウィンドウの中央に配置するもう 1 つの方法は、anchors.centerIn を使用することです：

ApplicationWindow {
    id: window
    // ...

    Pane {
        // ...

        Popup {
            anchors.centerIn: Overlay.overlay
        }
    }
}

ポップアップが囲んでいるウィンドウの境界内に確実に配置されるようにするには、margins プロパティを非負の値に設定します。

オーバーレイの使用

popup windows が使用されていない場合、Popupは、ポップアップがシーン内の他のすべての要素よりも手前に表示されるようにするため、contentItem の視覚的な親をウィンドウのoverlay に設定します。その主な役割は、イベントをインターセプトしてmodal ポップアップの下にあるアイテムへのイベント配信を防止すること、およびclosePolicy に従ってポップアップを閉じることです。

場合によっては、virtual keyboard など、ポップアップの前面にアイテムを配置することが有用な場合があります。これは現在、アイテムの親をオーバーレイに設定し、z の値を正にすることで、そのアイテムがどのポップアップアイテムよりも前に配置されるようにすることでのみ実現可能です。

オーバーレイは本来この目的のために設計されたものではなく、またpopupType を変更した際に動作が不安定になるため、一般的にこの方法でオーバーレイを使用することは推奨されません。

Popup {
    id: popup
    visible: true
    anchors.centerIn: parent
    margins: 10
    closePolicy: Popup.CloseOnEscape
    ColumnLayout {
        TextField {
            placeholderText: qsTr("Username")
        }
        TextField {
            placeholderText: qsTr("Password")
            echoMode: TextInput.Password
        }
    }
}
InputPanel {
    parent: Overlay.overlay
    width: parent.width
    y: popup.y + popup.topMargin + (window.activeFocusItem?.y ?? 0) + (window.activeFocusItem?.height ?? 0)
    z: 1
}

終了トランジションが終了すると、これらのプロパティは、開始トランジションが開始される前の値にリセットされます。

これにより、明示的に定義された値を失うことなく、組み込みスタイルによってこれらのプロパティにアニメーションを適用することができます。

戻る/Esc イベントの処理

デフォルトでは、以下の条件を満たすとポップアップが閉じられます。

activeFocus が設定されている場合、
その「closePolicy 」が「Popup.CloseOnEscape 」に設定されており、
ユーザーがQKeySequence::Cancel に対応するキーシーケンス（通常はEscキー）を押した場合

これを防ぐには、次のいずれかの方法があります：

ポップアップにfocus を指定しない。
ポップアップのclosePolicy を、Popup.CloseOnEscape を含まない値に設定する。
ポップアップの子アイテム内でKeys'escapePressed シグナルを処理し、ポップアップ本体よりも先にそのイベントを受け取れるようにします。

プロパティの伝播

ポップアップは、オブジェクトやビジュアル上の親ではなく、親ウィンドウを通じてフォント、パレット、および関連付けられたプロパティを継承します。

import QtQuick.Controls.Basic

ApplicationWindow {
    width: 500
    height: 500
    visible: true
    font.pixelSize: 20
    palette.windowText: "steelblue"

    // This will have a pixelSize of 20 and be "steelblue" in color.
    header: Label {
        text: "ApplicationWindow Label"
        leftPadding: 20
        topPadding: 20
    }

    Pane {
        width: 400
        height: 400
        anchors.centerIn: parent
        palette.window: "#edf3f8"
        palette.windowText: "tomato"

        // This will have a pixelSize of 20 and be "tomato" in color.
        Label {
            text: "Pane Label"
        }

        Popup {
            width: 300
            height: 300
            anchors.centerIn: parent
            font.pixelSize: 10
            visible: true

            // This will have a pixelSize of 10 and "steelblue" in color.
            Label {
                text: "Popup Label"
            }

            Popup {
                width: 200
                height: 200
                anchors.centerIn: parent
                visible: true

                // This will have a pixelSize of 20 and be "steelblue" in color.
                Label {
                    text: "Child Popup Label"
                }
            }
        }
    }
}

ポップアップのプロパティの継承を示す図

さらに、ポップアップはそのプロパティを子ポップアップに伝播しません。この動作は、Qt Widgets をモデルにしています。では、Qt::Popup ウィジェットは最上位ウィンドウです。最上位ウィンドウは、そのプロパティを子ウィンドウに伝播しません。

ComboBox のような特定の派生型は、通常、ポップアップがコントロールの不可欠な部分と見なされるように実装されており、そのため、アタッチされたプロパティなどを継承する場合があります。たとえば、Material スタイルの ComboBox では、テーマやその他のアタッチされたプロパティは、ComboBox 自体から Popup によって明示的に継承されます:

popup: T.Popup {
    // ...

    Material.theme: control.Material.theme
    Material.accent: control.Material.accent
    Material.primary: control.Material.primary
}

したがって、子ポップアップが親ポップアップと同じプロパティ値を持つようにするには、それらのプロパティを明示的に設定してください：

Popup {
    id: parentPopup
    // ...

    Popup {
        palette: parentPopup.palette
    }
}

閉じられたポップアップの動作の調整

ポップアップが閉じられると、それに関連付けられたウィンドウは存在しなくなり、その子アイテムも同様になります。つまり、ポップアップが表示されるまで、どの子アイテムもpolished 状態にはなりません。このため、例えば、閉じられたPopup 内のListView が、そのcount プロパティを更新することを期待することはできません：

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    SomeModel {
        id: someModel
    }

    Button {
        text: view.count
        onClicked: popup.open()
    }

    Popup {
        id: popup
        width: 400
        height: 400
        contentItem: ListView {
            id: view
            model: someModel
            delegate: Label {
                text: display

                required property string display
            }
        }
    }
}

上記の例では、ポップアップが閉じられている間に、component completion の後にsomeModel に行が追加されたり削除されたりしても、Buttonのテキストは更新されません。

その代わりに、SomeModel にcount プロパティを追加し、rowsInserted 、rowsRemoved 、およびmodelReset シグナルが発信されるたびにこのプロパティが更新されるように設定できます。そうすることで、Button はこのプロパティを自身のtext にバインドできるようになります。

「ポップアップコントロール」、「ポップアップのカスタマイズ」、「ApplicationWindow 」も参照してください 。

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

activeFocus : bool `[read-only]`

このプロパティは、ポップアップにフォーカスが当たっているかどうかを表します。

「 focus 」および「 Qt Quick 」の「Keyboard Focus」も参照してください 。

anchors.centerIn : Item `[since QtQuick.Controls 2.5 (Qt 5.12)]`

アンカーを使用すると、他のアイテムとの関係を指定することで、アイテムの位置を調整することができます。

一般的な使用例として、ポップアップを親ウィンドウの中央に配置することが挙げられます。これを行う方法の一つとして、x やy プロパティを使用する方法がありますが、アンカーを使用するとより便利なアプローチが可能です：

Pane {
    // ...

    Popup {
        anchors.centerIn: parent
    }
}

また、Overlay を使用することで、ポップアップをウィンドウ内で中央に配置することも可能です：

ApplicationWindow {
    id: window
    // ...

    Pane {
        // ...

        Popup {
            anchors.centerIn: Overlay.overlay
        }
    }
}

これにより、どのコンポーネントからでもウィンドウ内でポップアップを中央に配置することが容易になります。

注：ポップアップは 、直上の親またはウィンドウオーバーレイ内でのみ中央に配置できます。その他の項目内で中央配置を試みると、警告が表示されます。

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

関連項目: Popup Positioning 、anchors 、および Using Qt Quick Controls types in property declarations。

availableHeight : real `[read-only]`

このプロパティは、ポップアップのheight から垂直方向のパディングを差し引いた後、contentItem が利用可能な高さを保持します。

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

availableWidth : real `[read-only]`

このプロパティは、ポップアップのwidth から水平方向のパディングを差し引いた後、contentItem が利用できる幅を保持します。

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

background : Item

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

注：背景アイテムに明示的なサイズが指定されていない場合、自動的にポップアップのサイズに準じます。ほとんどの場合、背景アイテムの幅や高さを指定する必要はありません。

注：ほとんどのポップ アップは、背景アイテムの暗黙的なサイズを使用して、ポップアップ自体の暗黙的なサイズを計算します。背景アイテムをカスタムアイテムに置き換える場合は、そのアイテムに対して適切な暗黙的なサイズを設定することも検討する必要があります（Image のように、独自の暗黙的なサイズを持つアイテムを除く）。

「ポップアップのカスタマイズ」も参照してください 。

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

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

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

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

bottomMargin : real

このプロパティは、ポップアップの下端とそのウィンドウの下端との間の距離を保持します。

下マージンが負の値に設定されたポップアップは、囲むウィンドウの下端の内側には表示されません。デフォルト値は-1 です。

margins 、topMargin 、およびPopup Layoutも参照してください。

bottomPadding : real

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

パディングプロパティは、content item の形状を制御するために使用されます。

Popupは、Control と同じパディング処理を採用しています。パディングシステムの視覚的な説明については、ドキュメントの「Control Layout 」セクションを参照してください。

関連項目：padding 、topPadding 、verticalPadding 、およびavailableHeightも参照してください。

clip : bool

このプロパティは、クリッピングが有効かどうかにかかわらず適用されます。デフォルト値はfalse です。クリッピングは、ポップアップが独立したウィンドウ内にない場合にのみ機能します。

closePolicy : enumeration

このプロパティは、ポップアップが閉じられる条件を決定します。フラグを組み合わせて、ポップアップを閉じる方法を複数設定することができます。

使用可能な値は次のとおりです：

定数	説明
`Popup.NoAutoClose`	ポップアップは、手動で閉じられるよう指示があった場合にのみ閉じられます。
`Popup.CloseOnPressOutside`	ポップアップの外側でマウスをクリックすると、ポップアップが閉じます。
`Popup.CloseOnPressOutsideParent`	親要素の外側でマウスをクリックすると、ポップアップが閉じます。
`Popup.CloseOnReleaseOutside`	ポップアップの外側でマウスを離すと、ポップアップが閉じます。
`Popup.CloseOnReleaseOutsideParent`	親ウィンドウの外側でマウスを離すと、ポップアップが閉じます。
`Popup.CloseOnEscape`	ポップアップにフォーカスが当たっている状態で Esc キーが押されると、ポップアップは閉じます。
`Popup.CloseMultiple`	複数のポップアップがネストされている場合、デフォルトでは、外部でクリックされるたびに最上層のポップアップのみが閉じられます。閉じられるポップアップにこのフラグが設定されている場合、スタック内の次のポップアップもチェックされます。クリック位置がそのポップアップの外側にある場合、そのポップアップも閉じられます。このカスケードは、すべてのポップアップが閉じられるか、クリック位置を境界内に含むポップアップに到達するか、`CloseMultiple` が設定されていないポップアップが閉じられるまで、スタックを下に向かって続きます。少なくとも1つの`CloseOnPress` または`CloseOnRelease` フラグと組み合わせて使用する必要があります。

デフォルト値は `Popup.CloseOnEscape | Popup.CloseOnPressOutside` です。

注: 「Popup.CloseOnReleaseOutside 」および「Popup.CloseOnReleaseOutsideParent 」ポリシーは、「modal 」ポップアップでのみ機能するという既知の制限があります 。

contentChildren : list<Item>

このプロパティには、コンテンツの子要素のリストが格納されます。

このリストには、QML内でポップアップの子として宣言されたすべての項目が含まれます。

注: `contentData` とは異なり 、`contentChildren ` には非ビジュアルな QML オブジェクトは含まれません。

「 Item::children 」および「contentData 」も参照してください 。

contentData : list<QtObject> `[default]`

このプロパティには、コンテンツデータのリストが格納されます。

このリストには、QML内でポップアップの子として宣言されたすべてのオブジェクトが含まれます。

注: `contentChildren`とは異なり 、`contentData ` には非ビジュアルな QML オブジェクトも含まれます。

「 Item::data 」および「contentChildren 」も参照してください 。

contentHeight : real

このプロパティは、コンテンツの高さを保持します。ポップアップの暗黙的な合計高さを計算するために使用されます。

詳細については、Popup Sizing を参照してください。

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

contentItem : Item

このプロパティには、ポップアップのコンテンツアイテムが格納されます。

コンテンツアイテムは、ポップアップの視覚的な実装です。ポップアップが表示されると、コンテンツアイテムは自動的にoverlay item に再配置されます。

注：コンテンツアイテムは、ポップアップのpadding 内に収まるように自動的にサイズ調整されます。

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

「ポップアップのカスタマイズ」も参照してください 。

contentWidth : real

このプロパティはコンテンツの幅を保持します。これは、ポップアップの暗黙的な総幅を計算するために使用されます。

詳細については、Popup Sizing を参照してください。

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

dim : bool

このプロパティは、ポップアップが表示された際に背景を暗くするかどうかを指定します。

明示的に設定されていない場合、このプロパティは `modal` の値に従います。デフォルト値に戻すには、このプロパティを `undefined` に設定してください。

「 modal 」および「Overlay.modeless 」も参照してください 。

enabled : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

このプロパティは、ポップアップが有効かどうかを示します。デフォルト値はtrue です。

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

「 visible 」および「Item::enabled 」も参照してください 。

enter : Transition

このプロパティは、ポップアップが開かれて画面に表示される際に、ポップアップ項目に適用されるトランジションを保持します。

次の例では、ポップアップが画面に表示される際に、その不透明度をアニメーション表示しています。

Popup {
    enter: Transition {
        NumberAnimation { property: "opacity"; from: 0.0; to: 1.0 }
    }
}

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

exit : Transition

このプロパティは、ポップアップが閉じられて画面外に出た際に、ポップアップ項目に適用されるトランジションを保持します。

次の例では、ポップアップが画面外に出る際に、その不透明度をアニメーション表示しています。

Popup {
    exit: Transition {
        NumberAnimation { property: "opacity"; from: 1.0; to: 0.0 }
    }
}

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

focus : bool

このプロパティは、ポップアップがフォーカスを取得するかどうかを指定します。

ポップアップが実際にフォーカスを受け取ると、`activeFocus ` は `true` になります。詳細については、 Qt Quick の「キーボードフォーカス」を参照してください。

デフォルト値は `false` です。

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

font : font

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

ポップアップは、明示的なフォントプロパティを子要素に伝播します。ポップアップのフォントの特定のプロパティを変更すると、そのプロパティはポップアップのすべての子要素に伝播され、そのプロパティに関するシステムのデフォルト設定が上書きされます。

Popup {
    font.family: "Courier"

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

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

「 Control::font 」および「ApplicationWindow::font 」も参照してください 。

height : real

このプロパティは、ポップアップの高さを保持します。

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

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

パディングプロパティは、content item のジオメトリを制御するために使用されます。

Popupは、Control と同じアプローチでパディングを扱います。パディングシステムの視覚的な説明については、ドキュメントの「Control Layout 」セクションを参照してください。

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

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

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

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

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

このプロパティは、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` に等しくなります。

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

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

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

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

値は、コンテンツの子要素に基づいて計算されます。

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

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

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

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

値は、コンテンツの子要素に基づいて計算されます。

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

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

implicitHeight : real

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

implicitWidth : real

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

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

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

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

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

leftMargin : real

このプロパティは、ポップアップの左端とそのウィンドウの左端との間の距離を保持します。

左マージンが負の値に設定されたポップアップは、囲むウィンドウの左端の内側に押し込まれません。デフォルト値は-1 です。

margins 、rightMargin 、およびPopup Layoutも参照してください。

leftPadding : real

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

パディングプロパティは、content item の形状を制御するために使用されます。

Popupは、Control と同じパディングの処理方法を採用しています。パディングシステムの視覚的な説明については、ドキュメントの「Control Layout 」セクションを参照してください。

関連項目：padding 、rightPadding 、horizontalPadding 、およびavailableWidthも参照してください。

locale : Locale

このプロパティは、ポップアップのロケールを保持します。

mirrored およびLayoutMirroringも参照してください。

margins : real

このプロパティは、ポップアップの端とそのウィンドウの端との間の距離を保持します。

マージンが負の値に設定されたポップアップは、囲むウィンドウの境界内に押し込まれません。デフォルト値は-1 です。

topMargin 、leftMargin 、rightMargin 、bottomMargin 、およびPopup Layoutも参照してください。

mirrored : bool `[read-only, since QtQuick.Controls 2.3 (Qt 5.10)]`

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

このプロパティは便宜上提供されています。ポップアップは、その視覚的なレイアウト方向が右から左の場合、つまり右から左のロケールを使用している場合に、反転表示されていると見なされます。

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

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

このプロパティは、ポップアップがモーダルであるかどうかを表します。

モーダルポップアップには、Overlay.modal で定義されているような特徴的な背景の暗転効果が適用されることが多く、その下にあるアイテムに対してクリックやリリースイベントが透過されません。たとえば、ユーザーが誤ってポップアップの外側をクリックした場合、そのクリック位置にあるポップアップの下にあるアイテムにはイベントが伝わりません。

デスクトッププラットフォームでは、モーダルポップアップはEscキーが押された場合にのみ閉じられるのが一般的です。この動作を実現するには、closePolicy をPopup.CloseOnEscape に設定します。デフォルトでは、closePolicy はPopup.CloseOnEscape | Popup.CloseOnPressOutside に設定されており、これはモーダルポップアップの外側をクリックするとポップアップが閉じられることを意味します。

デフォルト値は `false` です。

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

opacity : real

このプロパティは、ポップアップの不透明度を指定します。不透明度は、0.0 （完全に透明）から1.0 （完全に不透明）までの数値で指定します。デフォルト値は1.0 です。

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

opened : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

このプロパティは、ポップアップが完全に開かれているかどうかを表します。ポップアップは、表示されており、かつenter およびexit のトランジションのいずれも実行されていない場合に、開かれているとみなされます。

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

open()、close()、およびvisibleも参照してください。

padding : real

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

パディングプロパティは、content item の形状を制御するために使用されます。

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

palette : palette `[since QtQuick.Controls 2.3 (Qt 5.10)]`

このプロパティは、ポップアップに現在設定されているパレットを保持します。

ポップアップは、明示的に指定されたパレットのプロパティをその子要素に反映します。ポップアップのパレットで特定のプロパティを変更すると、そのプロパティはポップアップのすべての子要素に反映され、そのプロパティに関するシステムのデフォルト設定を上書きします。

Popup {
    palette.text: "red"

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

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

関連項目：Item::palette 、Window::palette 、ColorGroup 、Palette

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

parent : Item

このプロパティには親アイテムが格納されます。

popupType : enumeration `[since 6.8]`

このプロパティは、優先されるポップアップの種類を指定します。

利用可能なオプション：

定数	説明
`Item`	ポップアップは、別のウィンドウを使用せずに、same scene as the parent に埋め込まれます。
`Window`	ポップアップはseparate window 内に表示されます。プラットフォームが複数のウィンドウに対応していない場合、代わりに`Popup.Item` が使用されます。
`Native`	ポップアップはプラットフォーム固有の形式で表示されます。プラットフォームがネイティブのポップアップをサポートしていない場合は、代わりに`Popup.Window` が使用されます。

ポップアップが優先されるタイプを使用できるかどうかは、プラットフォームによって異なります。Popup.Item はすべてのプラットフォームでサポートされていますが、Popup.Window およびPopup.Native は通常、デスクトッププラットフォームでのみサポートされています。さらに、ポップアップがnative menubar 内のMenu である場合、メニューもネイティブ形式になります。また、メニューが別のメニュー内のサブメニューである場合、そのタイプは親（またはルート）メニューによって決定されます。

デフォルト値は通常「Popup.Item 」ですが、前述のようにいくつかの例外があります。他のポップアップタイプの使用が有益となる特定のスタイルやプラットフォームについては、将来のQtバージョンでこれが変更される可能性があります。たとえば、macOSのすべてのスタイルで常にネイティブメニューを使用したい場合は、次のように設定できます：

Menu {
    popupType: Qt.platform.os === "osx" ? Popup.Native : Popup.Window
}

また、ポップアップをカスタマイズする場合（例えば、デリゲートのいずれかを変更する場合など）、ポップアップタイプもPopup.Window に設定することを検討すべきです。これにより、すべてのプラットフォームおよびすべてのスタイルで変更内容が確実に反映されます。そうしないと、ネイティブメニューが使用されている場合、レンダリングにデリゲートが使用されなくなります。

このプロパティは Qt 6.8 で導入されました。

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

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

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

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

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

rightMargin : real

このプロパティは、ポップアップの右端とそのウィンドウの右端との間の距離を保持します。

右マージンが負の値に設定されたポップアップは、囲むウィンドウの右端の内側に押し込まれません。デフォルト値は `-1` です。

margins 、leftMargin 、およびPopup Layoutも参照してください。

rightPadding : real

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

パディングプロパティは、content item の形状を制御するために使用されます。

関連項目：padding 、leftPadding 、horizontalPadding 、およびavailableWidthも参照してください。

scale : real

このプロパティは、ポップアップの拡大率を指定します。デフォルト値は1.0 です。

スケール値が1.0 より小さい場合、ポップアップはより小さいサイズで描画され、1.0 より大きい場合は、より大きなサイズで描画されます。負のスケール値はサポートされていません。

spacing : real `[since QtQuick.Controls 2.1 (Qt 5.8)]`

このプロパティは余白を指定します。

間隔は、複数の構成要素や繰り返しの構成要素を含むポップアップで役立ちます。例えば、一部のスタイルでは、Dialog のヘッダー、コンテンツ、フッター間の距離を決定するために間隔が使用されます。間隔はPopupによって強制されるものではないため、スタイルごとに解釈が異なり、完全に無視される場合もあります。

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

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

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

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

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

topMargin : real

このプロパティは、ポップアップの上端とそのウィンドウの上端との間の距離を保持します。

topマージンが負の値に設定されたポップアップは、囲むウィンドウの上端の内側に配置されません。デフォルト値は-1 です。

margins 、bottomMargin 、およびPopup Layoutも参照してください。

topPadding : real

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

パディングプロパティは、content item の形状を制御するために使用されます。

関連項目： padding 、bottomPadding 、verticalPadding 、およびavailableHeight 。

transformOrigin : enumeration

このプロパティは、エンターおよびエグジットのトランジションにおける変形の原点を指定します。

下の画像に示すように、9つの変換原点が利用可能です。デフォルトの変換原点はPopup.Center です。

変形の原点を示すポップアップ

「 enter 」、「exit 」、および「Item::transformOrigin 」も参照してください 。

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

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

パディングプロパティは、content item のジオメトリを制御するために使用されます。

Popupは、Control と同じパディングの仕組みを採用しています。パディングシステムの視覚的な説明については、ドキュメントの「Control Layout 」のセクションを参照してください。

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

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

visible : bool

このプロパティは、ポップアップが表示されているかどうかを表します。デフォルト値は `false` です。

open()、close()、およびopenedも参照してください。

width : real

このプロパティは、ポップアップの幅を保持します。

x : real

このプロパティは、ポップアップの x 座標を保持します。

「 y 」および「z 」も参照してください 。

y : real

このプロパティは、ポップアップのY座標を保持します。

「 x 」および「z 」も参照してください 。

z : real

このプロパティは、ポップアップのz値を保持します。z値によって、ポップアップの重ね順が決まります。

表示中の2つのポップアップのz値が同じ場合、最後に開かれたポップアップが最前面に表示されます。

ポップアップが開かれた際にz値が明示的に設定されておらず、かつすでに開かれているポップアップの子要素である場合、そのポップアップは親要素の上に重ねられます。これにより、子要素が親要素の下に隠れてしまうことがありません。

ポップアップに独自のウィンドウがある場合、z値は代わりにウィンドウの重ね順を決定します。

デフォルトの z 値は0 です。

「 x 」および「y 」も参照してください 。

Signal ドキュメント

void aboutToHide()

このシグナルは、ポップアップが非表示になろうとする際に発火します。

注：対応するハンドラは `onAboutToHide` です。

closed()も参照してください 。

void aboutToShow()

このシグナルは、ポップアップが表示されようとしているときに発せられます。

注：対応するハンドラは onAboutToShow です。

opened()も参照してください 。

void closed()

このシグナルは、ポップアップが閉じられたときに発生します。

注：対応するハンドラは onClosed です。

aboutToHide()も参照してください 。

void opened()

このシグナルは、ポップアップが開かれたときに発せられます。

注：対応するハンドラは onOpened です。

aboutToShow()も参照してください 。

メソッドのドキュメント

void close()

ポップアップを閉じます。

visibleも参照してください。

void forceActiveFocus(enumeration reason = Qt.OtherFocusReason)

指定されたreason を持つポップアップにフォーカスを強制的に移動させます。

このメソッドは、ポップアップにフォーカスを設定し、オブジェクト階層内のすべての親FocusScope オブジェクトに対してもfocus が設定されるようにします。

「 activeFocus 」および「Qt::FocusReason 」も参照してください 。

void open()

ポップアップを開きます。

visibleも参照してください。

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

Popup QML Type

プロパティ

信号

方法

詳細説明

ポップアップのレイアウト

ポップアップの種類

ポップアップを項目として表示する

ポップアップを独立したウィンドウとして表示する

ネイティブのポップアップを表示する

ポップアップのサイズ設定

ポップアップの位置決め

オーバーレイの使用

ポップアップの遷移

戻る/Esc イベントの処理

プロパティの伝播

閉じられたポップアップの動作の調整

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

activeFocus : bool [read-only]

anchors.centerIn : Item [since QtQuick.Controls 2.5 (Qt 5.12)]

availableHeight : real [read-only]

availableWidth : real [read-only]

background : Item

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

bottomMargin : real

bottomPadding : real

clip : bool

closePolicy : enumeration

contentChildren : list<Item>

contentData : list<QtObject> [default]

contentHeight : real

contentItem : Item

contentWidth : real

dim : bool

enabled : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

enter : Transition

exit : Transition

focus : bool

font : font

height : real

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

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)]

implicitHeight : real

implicitWidth : real

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

leftMargin : real

leftPadding : real

locale : Locale

margins : real

mirrored : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

modal : bool

opacity : real

opened : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

padding : real

palette : palette [since QtQuick.Controls 2.3 (Qt 5.10)]

parent : Item

popupType : enumeration [since 6.8]

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

rightMargin : real

rightPadding : real

scale : real

spacing : real [since QtQuick.Controls 2.1 (Qt 5.8)]

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

topMargin : real

topPadding : real

transformOrigin : enumeration

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

visible : bool

width : real

x : real

y : real

z : real

Signal ドキュメント

void aboutToHide()

void aboutToShow()

void closed()

void opened()

activeFocus : bool `[read-only]`

anchors.centerIn : Item `[since QtQuick.Controls 2.5 (Qt 5.12)]`

availableHeight : real `[read-only]`

availableWidth : real `[read-only]`

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

contentData : list<QtObject> `[default]`

enabled : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

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

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, since QtQuick.Controls 2.3 (Qt 5.10)]`

opened : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

palette : palette `[since QtQuick.Controls 2.3 (Qt 5.10)]`

popupType : enumeration `[since 6.8]`

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

spacing : real `[since QtQuick.Controls 2.1 (Qt 5.8)]`

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

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