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
  • icon.cache : bool
  • icon.color : color
  • icon.height : int
  • icon.name : string
  • icon.source : url
  • icon.width : int
• overlap : real (since QtQuick.Controls 2.3 (Qt 5.10))
• 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つの使用例があります：

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

コンテキスト・メニューとして使用する場合、メニューを開くにはpopup() を呼び出すことをお勧めします。位置が明示的に指定されない限り、マウス・カーソルが利用可能なデスクトップ・プラットフォームでは、メニューはマウス・カーソルの位置に置かれ、そうでない場合は親アイテムの中央に置かれます。

MouseArea {
    anchors.fill: parent
    acceptedButtons: Qt.LeftButton | Qt.RightButton
    onClicked: {
        if (mouse.button === Qt.RightButton)
            contextMenu.popup()
    }
    onPressAndHold: {
        if (mouse.source === Qt.MouseEventNotSynthesized)
            contextMenu.popup()
    }

    Menu {
        id: contextMenu
        MenuItem { text: "Cut" }
        MenuItem { text: "Copy" }
        MenuItem { text: "Paste" }
    }
}

ポップアップ・メニューとして使用する場合は、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 {
    // ...
    closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent

QtQuick.Controls 2.3 (Qt 5.10)からは、Menu.Controlsの中にサブメニューを作成し、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で最もよく使われますが、どのようなタイプの項目でも含めることができます。

余白

Popupから継承されるように、Menuはmargins をサポートします。デフォルトでは、すべてのビルトインスタイルは、メニューがウィンドウの境界内に保たれるように、Menuのマージンに0 を指定します。メニューがウィンドウの外に出るようにするには（例えば、メニューが視界に入るようにアニメーションさせるには）、margin プロパティを-1 に設定します。

メニュー項目の動的生成

Instantiator または動的オブジェクト作成で、メニュー項目を動的に作成することができます。

インスタンシエータの使用

Instantiator を使って、メニュー項目を動的に生成することができます。次のコードは、"Recent Files" サブメニューを実装する方法を示しています：

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 ）に設定する必要があります。もう1つの方法は、Qt::AA_DontUseNativeMenuWindows application attribute を設定することです。これは、スタイルに関係なく、アプリケーション全体のネイティブ・コンテキスト・メニューを無効にします。

デフォルトのpopupType はスタイルによって決まります。例えばmacOSスタイルでは Popup.Native 、Imagineスタイルでは Popup.Window （スタイルでポップアップタイプが設定されていない場合のデフォルト）を使用します。メニューにカスタマイズを追加し、スタイルに関係なくそれらを使用したい場合は、ポップアップタイプを明示的にPopup.Window （またはPopup.Item ）に設定する必要があります。

メニューが優先タイプを使用できるかどうかはプラットフォームに依存します。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 に関係なく実行されるように、常にインスタンス化されます(ただし、非表示)。

対応プラットフォーム

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

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

メニューのカスタマイズ,MenuItem,メニューコントロール,ポップアップコントロール,JavaScript からの動的 QML オブジェクト作成,Popup type,[QML],popupTypeもご参照ください 。

プロパティ ドキュメント

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

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

メソッド・ドキュメント