Pages

API Documentation

• User Documentation
• Developer Documentation
• API Documentation

Search API documentation

On this page

ConvergentContextMenu QML Type

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

• Import Statement: import org.kde.kirigamiaddons.components
• Inherits: Item

#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

#[default] actions : list<Action>

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.

Constant	Description
ConvergentContextMenu.ContextMenu	A standard context menu, typically used on desktop platforms.
ConvergentContextMenu.BottomDrawer	A bottom drawer that displays nested actions on separate pages.
ConvergentContextMenu.Dialog	A dialog that displays nested actions on separate pages.

#headerContentItem : Item

Optional item displayed above the actions in the menu.

Note: This item is shown only at the top level in BottomDrawer and Dialog display modes. It is not shown in ContextMenu mode.

#opened : bool

Whether the context menu is open.

Note: Changing this property does not open or close the menu. Use popup() and close() to control it.

#Signal Documentation

#closed()

Emitted when the context menu is closed.

Note: The corresponding handler is onClosed.

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