ConvergentContextMenu QML Type

A context menu that can appear as a standard menu, bottom drawer, or dialog. More...

• List of all members, including inherited members

Properties

• actions : list<Action>
• displayMode : int
• headerContentItem : Item
• opened : bool

Signals

• closed()

Methods

• close()
• popup(parent, position)

Detailed Description

Add QtQuick Controls actions or Kirigami actions as child items. Kirigami actions can contain nested actions. By default, the menu uses a standard context menu on desktop and a bottom drawer on mobile. A Kirigami action's displayComponent can provide a custom delegate in BottomDrawer and Dialog modes.

import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.components as Components
import org.kde.kirigamiaddons.formcard as FormCard

Components.ConvergentContextMenu {
    id: root

    headerContentItem: RowLayout {
        spacing: Kirigami.Units.smallSpacing
        Kirigami.Avatar { ... }

        Kirigami.Heading {
            level: 2
            text: "Room Name"
        }
    }

    Controls.Action {
        text: i18nc("@action:inmenu", "Simple Action")
    }

    Kirigami.Action {
        text: i18nc("@action:inmenu", "Nested Action")

        Controls.Action { ... }

        Controls.Action { ... }

        Controls.Action { ... }
    }

    Kirigami.Action {
        text: i18nc("@action:inmenu", "Nested Action with Multiple Choices")

        Kirigami.Action {
            text: i18nc("@action:inmenu", "Follow Global Settings")
            checkable: true
            autoExclusive: true // Since KF 6.10
        }

        Kirigami.Action {
            text: i18nc("@action:inmenu", "Enabled")
            checkable: true
            autoExclusive: true // Since KF 6.10
        }

        Kirigami.Action {
            text: i18nc("@action:inmenu", "Disabled")
            checkable: true
            autoExclusive: true // Since KF 6.10
        }
    }

    // A custom FormCard delegate is used in BottomDrawer and Dialog modes.
    Kirigami.Action {
        displayComponent: FormCard.FormButtonDelegate { ... }
    }
}

For a ListView, avoid creating a separate menu instance for every delegate. Keep one menu for the view, or define a Component and create a menu when it is needed. The example below creates a menu on demand and passes the current delegate's index to it:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.components as Addons

ListView {
    model: 10
    delegate: Controls.ItemDelegate {
        text: index

        function openContextMenu(): void {
            const item = menu.createObject(Controls.Overlay.overlay, {
                index,
            });
            item.popup();
        }

        onPressAndHold: openContextMenu()

        // Open the menu for a platform context-menu request.
        Controls.ContextMenu.onRequested: (position) => openContextMenu()
    }

    Component {
        id: menu

        Addons.ConvergentContextMenu {
            required property int index

            Controls.Action {
                text: i18nc("@action:inmenu", "Action 1")
            }

            Kirigami.Action {
                text: i18nc("@action:inmenu", "Action 2")

                Controls.Action {
                    text: i18nc("@action:inmenu", "Sub-action")
                }
            }
        }
    }
}

Property Documentation

actions : list<Action> [default]

The actions displayed in the menu. This is the default property, so add actions as child items.

Each item can be a QtQuick Controls action or a Kirigami action. Kirigami actions can contain subactions.

displayMode : int

The presentation used to display the context menu.

By default, this is ContextMenu on desktop and BottomDrawer on mobile.

headerContentItem : Item

Optional item displayed above the actions in the menu.

opened : bool

Whether the context menu is open.

Signal Documentation

closed()

Emitted when the context menu is closed.

Method Documentation

close()

Close the currently open context menu.

popup(parent = null, position = null)

Open the context menu.

parent The item that owns the menu and, in ContextMenu mode, the item it is positioned relative to. If omitted, the menu uses this component as its parent.

position The location in parent's coordinate system where a ContextMenu should open. This argument is used only in ContextMenu mode.