Actions based components

Kirigami's Actions are used to add functionality to components.

Actions

A Kirigami.Action encapsulates a user interface action. We can use these to provide our applications with easy-to-reach actions that are essential to their functionality.

Note

Kirigami actions inherit from QtQuick Controls Action and can be assigned shortcuts.

Like QtQuick Controls Actions , they can be assigned to menu items and toolbar buttons, but also to multiple other Kirigami components.

import org.kde.kirigami 2.20 as Kirigami

Kirigami.Action {
    id: copyAction
    text: i18n("&Copy")
    icon.name: "edit-copy"
    shortcut: StandardKey.Copy
    onTriggered: { ... }
}

Note

The icon.name property takes names for system-wide icons following the FreeDesktop specification. These icons and icon names can be viewed with KDE's CuttleFish application which comes with plasma-sdk, or by visiting FreeDesktop's icon naming specification.

One feature offered by Kirigami Actions on top of QtQuick Actions is the possibility to nest actions.

import org.kde.kirigami 2.20 as Kirigami

Kirigami.Action {
    text: "View"
    icon.name: "view-list-icons"
    Kirigami.Action {
        text: "action 1"
    }
    Kirigami.Action {
        text: "action 2"
    }
    Kirigami.Action {
        text: "action 3"
    }
}

Another feature of Kirigami Actions is to provide various hints to items using actions about how they should display the action. These are primarily handled by the displayHint and displayComponent properties.

These properties will be respected by the item if possible. For example, the following action will be displayed as a TextField with the item trying its best to keep itself visible as long as possible.

import org.kde.kirigami 2.20 as Kirigami

Kirigami.Action {
    text: "Search"
    icon.name: "search"

    displayComponent: TextField { }

    displayHint: Kirigami.DisplayHints.KeepVisible
}

Using actions in other components

Page

One of Kirigami.Page 's features is that Actions can be added to it.

You can add a actions.main action, a actions.left and actions.right action and additional context actions that are displayed on the toolbar if there is enough place or in a hamburger menu on smaller screens.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import org.kde.kirigami 2.20 as Kirigami

Kirigami.ApplicationWindow {
    globalDrawer: Kirigami.GlobalDrawer {}
    contextDrawer: Kirigami.ContextDrawer {}

    pageStack.initialPage: Kirigami.Page {
        title: "Demo"

        actions {
            main: Kirigami.Action {
                icon.name: "go-home"
                onTriggered: showPassiveNotification("Main action triggered")
            }
            left: Kirigami.Action {
                icon.name: "go-previous"
                onTriggered: showPassiveNotification("Left action triggered")
            }
            right: Kirigami.Action {
                icon.name: "go-next"
                onTriggered: showPassiveNotification("Right action triggered")
            }
            contextualActions: [
                Kirigami.Action {
                    text: "Contextual Action 1"
                    icon.name: "bookmarks"
                    onTriggered: showPassiveNotification("Contextual action 1 clicked")
                },
                Kirigami.Action {
                    text: "Contextual Action 2"
                    icon.name: "folder"
                    enabled: false
                }
            ]
        }
    }
}

Warning

To make the context actions work on mobile, you need to add a ContextDrawer to your Kirigami.ApplicationWindow .

Kirigami.ApplicationWindow {
    ...
    contextDrawer: Kirigami.ContextDrawer {
        id: contextDrawer
    }
    ...
}

Global Drawer

The global drawer provides an action based navigation to your application. This is where nested actions are useful because it is possible to create nested navigation:

Kirigami.ApplicationWindow {
    title: i18n("Demo")
    globalDrawer: Kirigami.GlobalDrawer {
        title: i18n("Demo")
        titleIcon: "applications-graphics"
        actions: [
            Kirigami.Action {
                text: i18n("View")
                icon.name: "view-list-icons"
                Kirigami.Action {
                    text: i18n("View Action 1")
                    onTriggered: showPassiveNotification(i18n("View Action 1 clicked"))
                }
                Kirigami.Action {
                    text: i18n("View Action 2")
                    onTriggered: showPassiveNotification(i18n("View Action 2 clicked"))
                }
            },
            Kirigami.Action {
                text: i18n("Action 1")
                onTriggered: showPassiveNotification(i18n("Action 1 clicked"))
            },
            Kirigami.Action {
                text: i18n("Action 2")
                onTriggered: showPassiveNotification(i18n("Action 2 clicked"))
            }
        ]
    }
    ...
}

Global Drawer actions on a mobile device

You can read more about Global Drawers in the documentation page for drawers.

ActionTextFields

A Kirigami.ActionTextField is used to add some contextual actions to a text field, for example to clear the text, or to search for the text.

Kirigami.ActionTextField {
    id: searchField
    rightActions: [
        Kirigami.Action {
            icon.name: "edit-clear"
            visible: searchField.text !== ""
            onTriggered: {
                searchField.text = ""
                searchField.accepted()
            }
        }
    ]
}

In this example, we are creating a "clear" button for a search field that is only visible when text is entered.

Note

You should rarely use an ActionTextField directly. SearchField and PasswordField both inherit from ActionTextField and are likely to cover your desired use-case.

SwipeListItem

A Kirigami.SwipeListItem is a delegate intended to support extra actions. When using a mouse, its actions will always be shown. On a touch device, they can be shown by dragging the item with the handle. In the following pictures, these are the icons to the right.

ListView {
    model: myModel
    delegate: SwipeListItem {
        Controls.Label {
            text: model.text
        }
        actions: [
             Action {
                 icon.name: "document-decrypt"
                 onTriggered: print("Action 1 clicked")
             },
             Action {
                 icon.name: model.action2Icon
                 onTriggered: //do something
             }
        ]
    }
}

ActionToolBar

A Kirigami.ActionToolBar is a toolbar built out of a list of actions. By default, each action that will fit in the toolbar will be represented by a ToolButton , with those that do not fit being moved into a menu at the end of the toolbar.

Like ActionTextField , you may not need to use ActionToolBar directly as it is used by page headers and cards to provide their action display.

Kirigami.ActionToolBar {
    actions: [
        Kirigami.Action {
            text: i18n("View Action 1")
            onTriggered: showPassiveNotification(i18n("View Action 1 clicked"))
        },
        Kirigami.Action {
            text: i18n("View Action 2")
            onTriggered: showPassiveNotification(i18n("View Action 2 clicked"))
        },
        Kirigami.Action {
            text: i18n("Action 1")
            onTriggered: showPassiveNotification(i18n("Action 1 clicked"))
        },
        Kirigami.Action {
            text: i18n("Action 2")
            onTriggered: showPassiveNotification(i18n("Action 2 clicked"))
        }
    ]
}

A horizontal toolbar being displayed at the top of the application

You can read more about ActionToolBar components in their dedicated documentation page.

Cards

A Kirigami.Card is used to display a collection of information or actions together. These actions can be added to the actions group, similarly to previous components.

Kirigami.Card {
    actions: [
        Kirigami.Action {
            text: qsTr("Action1")
            icon.name: "add-placemark"
        },
        Kirigami.Action {
            text: qsTr("Action2")
            icon.name: "address-book-new-symbolic"
        },
        // ...
    ]
    banner {
        source: "../banner.jpg"
        title: "Title Alignment"
        titleAlignment: Qt.AlignLeft | Qt.AlignBottom
    }
    contentItem: Controls.Label {
        wrapMode: Text.WordWrap
        text: "My Text"
    }
}

Screenshot of a full-fledged Card with a banner background behind its title, white background behind its text, and two actions with icons and a hamburger menu at the bottom

For more information consult the component page for Cards.

Typography

Page rows and page stacks