Menu QML Type

コンテキストメニューやポップアップメニューとして使用できるメニューポップアップ。詳細...

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

プロパティ

• cascade : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• contentData : list<QtObject>
• contentModel : model
• count : int (since QtQuick.Controls 2.3 (Qt 5.10))
• currentIndex : int (since QtQuick.Controls 2.3 (Qt 5.10))
• delegate : Component (since QtQuick.Controls 2.3 (Qt 5.10))
• focus : bool
• icon (since QtQuick.Controls 6.5)
  • icon.cache : bool (since QtQuick.Controls 6.5)
  • icon.color : color (since QtQuick.Controls 6.5)
  • icon.height : int (since QtQuick.Controls 6.5)
  • icon.name : string (since QtQuick.Controls 6.5)
  • icon.source : url (since QtQuick.Controls 6.5)
  • icon.width : int (since QtQuick.Controls 6.5)
• overlap : real (since QtQuick.Controls 2.3 (Qt 5.10))
• separatorsCollapsible : bool (since QtQuick.Controls 6.12 (Qt 6.12))
• title : string

方法

• Action actionAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addItem(Item item)
• void addMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• void dismiss() (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertAction(int index, Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertItem(int index, Item item)
• void insertMenu(int index, Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Item itemAt(int index)
• Menu menuAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void moveItem(int from, int to)
• void popup(MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeItem(Item item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Action takeAction(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• MenuItem takeItem(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• Menu takeMenu(int index) (since QtQuick.Controls 2.3 (Qt 5.10))

詳細説明

メニューには主に2つの用途があります：

• コンテキストメニュー：たとえば、ボタンを右クリックした後に表示されるメニュー
• ポップアップメニュー：例えば、ボタンをクリックした後に表示されるメニューなど

コンテキストメニューについては、Context Menus を参照してください。

ポップアップメニューとして使用する場合、それぞれのプロパティを使用してx およびy の座標を指定し、open()を呼び出してメニューを開くのが最も簡単です。

Button {
    id: fileButton
    text: "File"
    onClicked: menu.open()

    Menu {
        id: menu
        y: fileButton.height

        MenuItem {
            text: "New..."
        }
        MenuItem {
            text: "Open..."
        }
        MenuItem {
            text: "Save"
        }
    }
}

ボタンをクリックした際にメニューを閉じるようにするには、Popup.CloseOnPressOutsideParent フラグを使用します：

    onClicked: menu.visible = !menu.visible

    Menu {
        id: menu
        // ...
        closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent

サブメニューを作成したり、Menu 内で Action オブジェクトを宣言したりすることができます:

Menu {
    Action { text: "Cut" }
    Action { text: "Copy" }
    Action { text: "Paste" }

    MenuSeparator { }

    Menu {
        title: "Find/Replace"
        Action { text: "Find Next" }
        Action { text: "Find Previous" }
        Action { text: "Replace" }
    }
}

マウスカーソルが利用可能なデスクトッププラットフォームでは、サブメニューはデフォルトでcascading （カスケード）となります。カスケードしないメニューは、1つずつ表示され、親メニューの中央に配置されます。

通常、メニュー項目はメニューの子要素として静的に宣言されますが、Menuにはadd 、insert 、move 、remove といった項目を動的に生成するためのAPIも用意されています。メニュー内の項目には、itemAt() またはcontentChildren を使用してアクセスできます。

MenuItems はMenuで最も一般的に使用されますが、Menuには任意のタイプの項目を含めることができます。

コンテキストメニュー

コンテキストメニューについては、プラットフォーム固有のイベントが発生した際にメニューを作成する「ContextMenu 」アタッチメントタイプを使用する方が簡単です。さらに、TextField 、TextArea 、SpinBox 、DoubleSpinBox などのテキスト編集コントロールは、デフォルトで独自のコンテキストメニューを提供します。

ContextMenu を使用しない場合、メニューを開く推奨される方法は、popup()を呼び出すことです。位置が明示的に指定されていない限り、マウスカーソルが利用可能なデスクトッププラットフォームではメニューはマウスカーソルの位置に配置され、それ以外の場合は親アイテムの中央に配置されます：

    TapHandler {
        acceptedButtons: Qt.RightButton
        onPressedChanged: {
            if (pressed && Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Press)
                contextMenu.popup()
        }
        onTapped: {
            if (Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Release)
                contextMenu.popup()
        }
    }
    TapHandler {
        acceptedDevices: PointerDevice.TouchScreen
        onLongPressed: contextMenu.popup()
    }

    Menu {
        id: contextMenu

        MenuItem {
            text: qsTr("Do stuff")
        }
        MenuItem {
            text: qsTr("Do more stuff")
        }
    }

なお、テキスト編集コントロール用に独自のコンテキストメニューを実装する場合、iOS や Android にはネイティブのコンテキストメニューが備わっているため、デスクトッププラットフォームでのみ表示すれば十分です：

    TextArea {
        text: qsTr("TextArea")

        // Disable the built-in context menu (since Qt 6.9).
        ContextMenu.menu: null

        TapHandler {
            acceptedButtons: Qt.RightButton
            onPressedChanged: {
                if (pressed === (Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Press))
                    contextMenu.popup()
            }
        }
    }

    Menu {
        id: contextMenu

        MenuItem {
            text: qsTr("Cut")
            // ...
        }
        MenuItem {
            text: qsTr("Copy")
            // ...
        }
        MenuItem {
            text: qsTr("Paste")
            // ...
        }
    }

余白

Popup から継承されているため、Menu は `margins` をサポートしています。デフォルトでは、メニューがウィンドウの境界内に収まるように、すべての組み込みスタイルで Menu のマージンに `0 ` が指定されています。メニューをウィンドウの外に出す（例えば、画面内へ移動するアニメーションを表示するためなど）には、margins プロパティを `-1` に設定してください。

メニュー項目の動的生成

Instantiator や動的なオブジェクト生成を使用して、メニュー項目を動的に作成できます。

Instantiatorの使用

Instantiator を使用すると、メニュー項目を動的に生成できます。以下のコードは、設定に保存されたファイルのリストから項目を取得する「最近のファイル」サブメニューを実装する方法を示しています：

Menu {
    title: qsTr("File")

    Menu {
        id: recentFilesMenu
        title: qsTr("Recent Files")
        enabled: recentFilesInstantiator.count > 0

        Instantiator {
            id: recentFilesInstantiator
            model: settings.recentFiles
            delegate: MenuItem {
                text: settings.displayableFilePath(modelData)
                onTriggered: loadFile(modelData)
            }

            onObjectAdded: (index, object) => recentFilesMenu.insertItem(index, object)
            onObjectRemoved: (index, object) => recentFilesMenu.removeItem(object)
        }

        MenuSeparator {}

        MenuItem {
            text: qsTr("Clear Recent Files")
            onTriggered: settings.clearRecentFiles()
        }
    }
}

動的なオブジェクト作成の使用

Qt.createComponent() を使用して、QML ファイルからコンポーネントを動的に読み込むこともできます。コンポーネントの準備が整ったら、そのコンポーネントのcreateObject() メソッドを呼び出して、そのコンポーネントのインスタンスを作成できます。

Row {
    anchors.centerIn: parent

    Component {
        id: menuItemComponent

        MenuItem {}
    }

    Button {
        id: button
        text: "Menu"
        onClicked: menu.open()
        Menu {
            id: menu
        }
    }

    Button {
        text: "Add item"
        onClicked: {
            onClicked: {
                let menuItem = menuItemComponent.createObject(
                    menu.contentItem, { text: qsTr("New item") })
                menu.addItem(menuItem)
            }
        }
    }
}

メニューの種類

Qt 6.8 以降、メニューはプラットフォームに応じて 3 種類の実装を提供しています。popupType を設定することで、どの実装を優先するかを指定できます。これにより、メニューを独立したウィンドウとして表示するか、親ウィンドウ内の項目として表示するか、あるいはネイティブメニューとして表示するかを制御できます。これらのオプションの詳細については、here を参照してください。

popupType のデフォルト値は、スタイルによって決まります。たとえば、macOSスタイルではPopup.Native に設定されていますが、ImagineスタイルではPopup.Window が使用されます（スタイルでポップアップタイプが設定されていない場合のデフォルトです）。 メニューにカスタマイズを追加し、スタイルに関係なくそれらを使用したい場合は、ポップアップタイプを明示的に `Popup.Window `（または `Popup.Item`）に設定する必要があります。別の方法として、Qt::AA_DontUseNativeMenuWindows `application attribute` に設定することもできます。これにより、スタイルに関係なく、アプリケーション全体のネイティブコンテキストメニューが無効になります。

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

ネイティブメニュー使用時の制限

popupType をPopup.Native に設定する場合、Popup.Item やPopup.Window を使用する場合と比較して、いくつかの制限や違いがあります。

APIの違い

ネイティブメニューを使用する場合、すべてのプラットフォームでサポートされるのはMenu APIの一部の機能のみです：

• x
• y
• visible
• opened
• title
• count
• contentData
• contentChildren （視覚的な子要素は表示されません）
• contentModel
• open()
• popup()
• close()
• opened()
• closed()
• aboutToShow()
• aboutToHide()

さらに、ポップアップの表示（例：open() やpopup() を使用する場合）は、一部のプラットフォームにおいてブロッキング呼び出しとなります。つまり、メニューが閉じられるまで呼び出しが返らないため、アプリケーションのロジックに影響を与える可能性があります。 これは、アプリケーションが複数のプラットフォームを対象としており、そのためネイティブメニューがサポートされていないプラットフォームで実行される場合がある場合に、特に考慮する必要があります。その場合、popupTypeは例えばPopup.Item にフォールバックし、open()への呼び出しはブロッキングされなくなります。

MenuItem のような項目は、例えばシグナルを発行するなどして、対応するネイティブメニュー項目のクリックには引き続き反応しますが、ネイティブの対応項目に置き換えられます。

レンダリングの違い

ネイティブメニューは、プラットフォーム上で利用可能なネイティブメニュー API を使用して実装されます。 したがって、これらのメニューとそのすべてのコンテンツは、QML ではなく、プラットフォームによってレンダリングされます。つまり、delegate はレンダリングには使用されません。ただし、onCompleted() などの関数がプラットフォームに関係なく実行されるように、 は常にインスタンス化されます（非表示ですが）。popupType 。

サポートされているプラットフォーム

ネイティブメニューは現在、以下のプラットフォームでサポートされています：

• Android
• iOS
• Linux（GTK+プラットフォームテーマで実行する場合に限り、スタンドアロンのコンテキストメニューとして利用可能）
• macOS
• Windows

関連項目： メニューのカスタマイズ、MenuItem 、メニューコントロール、ポップアップコントロール、JavaScript からの動的な QML オブジェクトの作成、Popup type 、[QML]、およびpopupType 。

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

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

このプロパティは、メニューがサブメニューをカスケード表示するかどうかを指定します。

デフォルト値はプラットフォームによって異なります。マウスカーソルが利用可能なデスクトッププラットフォームでは、デフォルトでメニューはカスケード表示されます。カスケード表示されないメニューは、1つずつ表示され、親メニューの中央に配置されます。

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

overlapも参照してください 。

contentData : list<QtObject> [default]

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

このリストには、QMLでメニューの子として宣言されたすべてのオブジェクトに加え、それぞれaddItem()メソッドおよびinsertItem()メソッドを使用して動的に追加または挿入された項目が含まれます。

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

contentModel : model [read-only]

このプロパティには、メニュー項目を表示するために使用されるモデルが格納されます。

コンテンツモデルは視覚化の目的で提供されています。メニューの内容を表示するコンテンツアイテムに対して、モデルとして割り当てることができます。

Menu {
    id: menu
    contentItem: ListView {
        model: menu.contentModel
    }
}

このモデルを使用すると、メニュー項目をメニューの子として静的に宣言することができます。

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

このプロパティは、項目の数を保持します。

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

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

このプロパティは、現在ハイライト表示されている項目のインデックスを保持します。

メニュー項目は、マウスをホバーさせたり、キーボードで移動したりすることでハイライト表示できます。

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

MenuItem::highlightedも参照してください 。

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

このプロパティには、アクションを表示するためのアイテムを作成するために使用されるコンポーネントが格納されます。

Menu {
    Action { text: "Cut" }
    Action { text: "Copy" }
    Action { text: "Paste" }
}

メニューはデリゲートの所有権を取得しません。

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

Actionも参照してください 。

focus : bool

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

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

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

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

icon group

これらのプロパティは、QtQuick.Controls 6.5 で導入されました。

「 AbstractButton::text」 、「AbstractButton::display 」、および「 Qt Quick Controls」の「Icons」も参照してください 。

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

このプロパティは、メニューが親メニューと水平方向に重なるピクセル数を指定します。

このプロパティは、メニューがカスケード形式のサブメニューとして使用されている場合にのみ効果を発揮します。

デフォルト値はスタイルによって異なります。

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

cascadeも参照してください 。

separatorsCollapsible : bool [since QtQuick.Controls 6.12 (Qt 6.12)]

このプロパティは、連続する区切り記号を折りたたむかどうかを指定します。

このプロパティが `true` に設定されている場合、メニューは、表示されている項目の先頭または末尾に表示される区切り線、およびその間の項目がすべて非表示になっている連続した区切り線を自動的に非表示にします。これは、Qt Widgets の `QMenu::separatorsCollapsible ` の動作を反映したものです。

デフォルト値はtrue です。

これは、メニュー項目が動的に表示または非表示になる場合に、孤立した区切り記号が表示されるのを防ぐため、有用です。

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

MenuSeparatorも参照してください 。

title : string

このプロパティは、メニューのタイトルを保持します。

メニューがサブメニューである場合、メニュー項目のテキストにメニューのタイトルが表示されることが多く、メニューバーにある場合はツールボタンのテキストに表示されます。

メソッドのドキュメント

[since QtQuick.Controls 2.3 (Qt 5.10)] Action actionAt(int index)

index にあるアクションを返します。インデックスが無効であるか、指定されたインデックスにアクションが存在しない場合は、null を返します。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

[since QtQuick.Controls 2.3 (Qt 5.10)] void addAction(Action action)

このメニューの末尾に「action 」を追加します。このメニューは、新しく追加された「action 」の所有権を取得しません。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

void addItem(Item item)

アイテムのリストの末尾に「item 」を追加します。このメニューは、新しく追加された「item 」の所有権を取得しません。

「Dynamically Generating Menu Items」も参照してください 。

[since QtQuick.Controls 2.3 (Qt 5.10)] void addMenu(Menu menu)

このメニューの末尾に「menu 」をサブメニューとして追加します。このメニューは、新たに追加されたmenu の所有権を取得しません。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

[since QtQuick.Controls 2.3 (Qt 5.10)] void dismiss()

このメニューが属する階層内のすべてのメニューを閉じます。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

popup() およびPopup::close()も参照してください 。

[since QtQuick.Controls 2.3 (Qt 5.10)] void insertAction(int index, Action action)

index に `action ` を挿入します。インデックスはメニュー内のすべての項目に含まれます。メニューは、新しく挿入された `action` の所有権を取得しません。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

void insertItem(int index, Item item)

index にitem を挿入します。このメニューは、新しく挿入されたitem の所有権を取得しません。

Dynamically Generating Menu Itemsも参照してください 。

[since QtQuick.Controls 2.3 (Qt 5.10)] void insertMenu(int index, Menu menu)

index に「menu 」をサブメニューとして挿入します。インデックスはメニュー内のすべての項目に含まれます。メニューは、新たに挿入されたmenu の所有権を取得しません。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

Item itemAt(int index)

index にあるアイテムを返します。存在しない場合は、null を返します。

[since QtQuick.Controls 2.3 (Qt 5.10)] Menu menuAt(int index)

index にあるサブメニューを返します。インデックスが無効な場合、または指定されたインデックスにサブメニューが存在しない場合は、null を返します。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

void moveItem(int from, int to)

アイテムをfrom のインデックス分移動し、to のインデックス分移動します。

マウスカーソルが利用可能なデスクトッププラットフォームでは、マウスカーソルの位置でメニューを開き、それ以外の場合はメニューを「parent 」項目の中心に配置します。

オプションで、メニューを特定のメニューitem に揃えることができます。この場合、その項目はcurrent. となります。item が指定されていない場合、currentIndex は-1 に設定されます。

これらのメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

Popup::open()も参照してください 。

ポップアップの座標系において、指定された位置pos （つまり、parent 項目に対する相対座標）でメニューを開きます。

オプションで、メニューを特定のメニューitem に整列させることができます。その場合、この項目はcurrent. となります。item が指定されていない場合、currentIndex は-1 に設定されます。

これらのメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

Popup::open()も参照してください 。

ポップアップの座標系において、指定された位置（x 、y ）でメニューを開きます。これは、そのparent 項目に対する相対座標です。

オプションで、メニューを特定のメニューitem に位置合わせすることができます。この場合、この項目はcurrent. となります。item が指定されていない場合、currentIndex は-1 に設定されます。

これらのメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

dismiss() およびPopup::open()も参照してください 。

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeAction(Action action)

指定されたaction を削除し、破棄します。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeItem(Item item)

指定されたitem を削除し、破棄します。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeMenu(Menu menu)

指定されたmenu を削除し、破棄します。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

[since QtQuick.Controls 2.3 (Qt 5.10)] Action takeAction(int index)

index にあるアクションを削除して返します。インデックスは、メニュー内のすべての項目を範囲とします。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

[since QtQuick.Controls 2.3 (Qt 5.10)] MenuItem takeItem(int index)

index にあるアイテムを取り出し、返します。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

[since QtQuick.Controls 2.3 (Qt 5.10)] Menu takeMenu(int index)

index にあるメニューを取り出し、返します。インデックスはメニュー内のすべての項目に含まれています。

このメソッドは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。