Aggiungere azioni

Imparare di più sulle azioni di Kirigami ci aiuterà a rendere la nostra applicazione più utile.

About Kirigami API documentation: use https://api-staging.kde.org/kirigami-index.html for now

Click here to read more

We are aware of issues involving broken links to Kirigami API documentation. We are currently working on a better website to address these issues, porting the API docs where possible.

In its current state, the staging API website under development for Kirigami can be used to access all relevant Kirigami API pages, and it should already work better than the previous API website. You can access the staging API website through https://api-staging.kde.org/kirigami-index.html.

If you'd like to assist us in our efforts to port the API documentation, take a look at our Port API documentation to QDoc metatask.

Ricapitoliamo

So far, we built a simple app that can display cards. However, there is currently no way for the user to add new cards to the card view.

In questa esercitazione guarderemo le azioni di Kirigami: ci aiuteranno ad aggiungere l'interattività al nostro programma, in modo coerente, veloce e accessibile.

Azioni

Una Kirigami.Action incapsula un'azione utente con l'interfaccia. Possiamo usarle per fornire le nostre applicazioni di azioni facili da raggiungere, che sono essenzialmente le loro funzionalità.

Se hai già usato delle applicazioni in Kirigami avrai certamente interagito con le azioni di Kirigami. In quest'immagine, alla destra del titolo della pagina possiamo vedere delle azioni con varie icone. Le azioni di Kirigami possono essere visualizzate in molti modi e possono fare molte cose.

Aggiunta dei conti alla rovescia

Un applicazione per il conto alla rovescia è abbastanza inutile senza la possibilità di aggiungerne qualcuno. Creiamo un'azione che ci permetterà di farlo.

pageStack.initialPage: Kirigami.ScrollablePage {
    // Other page properties...
    actions: [
        Kirigami.Action {
            id: addAction
            icon.name: "list-add-symbolic"
            text: i18nc("@action:button", "Add kountdown")
            onTriggered: kountdownModel.append({
                name: "Kirigami Action added card!",
                description: "Congratulations, your Kirigami Action works!",
                date: 1000
            })
        }
    ]
    // ...
}

We are placing our Kirigami.Action within our main page from the previous tutorials. If we wanted to, we could add more actions to our page (and even nest actions within actions!).

The brackets [] used above are similar to JavaScript arrays, which means you can pass one or more things to them, separated by comma:

// General JavaScript array of components:
variable: [ component1, component2 ]
// Passing an array of Kirigami actions to QML:
actions: [ Kirigami.Action {}, Kirigami.Action {} ]

The id and text properties should be familiar from previous tutorials. However, the inherited Action.icon property should be interesting: it is an object with several properties letting you display certain icons for your actions. Fortunately, to use KDE icons all we need to do is provide the name property for the icon property, icon.name.

Viewing the available icons

Fai clic qui per vedere come controllare le icone disponibili nel sistema.

Cuttlefish è un'applicazione di KDE che ti permette di vedere le icone che puoi usare nelle tue applicazioni. Offre delle funzionalità utili, ad esempio l'anteprima dell'aspetto tra i vari temi installati oppure nelle varie dimensioni, e altro. Potresti trovarlo un utile strumento se stai decidendo quale icona utilizzare nella tua applicazione.

Many of KDE's icons follow the FreeDesktop Icon Naming specification. Therefore, you might also find it useful to consult The FreeDesktop project's website, which lists all cross-desktop compatible icon names.

The onTriggered signal handler is the most important. This is what our action will do when it is used. You'll notice that in our example we're using the method kountdownModel.append of the kountdownModel we created in our previous tutorial. This method lets us append a new element to our list model. We are providing it with an object (indicated by curly braces {}) that has the relevant properties for our countdowns (name, description, and a placeholder date).

Each time we click our "Add kountdown" button on the top right, our custom countdown is added

Cassetto globale

The next component is a Kirigami.GlobalDrawer. It shows up as a hamburger menu. By default it opens a sidebar, which is especially useful on mobile, as the user can just swipe in a side of the screen to open it. Global drawers are useful for global navigation and actions. We are going to create a simple global drawer that includes a "quit" button.

Kirigami.ApplicationWindow {
    id: root
    // Other window properties...
    globalDrawer: Kirigami.GlobalDrawer {
        isMenu: true
        actions: [
            Kirigami.Action {
                text: i18n("Quit")
                icon.name: "application-exit-symbolic"
                shortcut: StandardKey.Quit
                onTriggered: Qt.quit()
            }
        ]
    }
    // ...
}

Here, we put our global drawer inside our application window. The main property we need to pay attention to is GlobalDrawer.actions, which takes the form of an array of Kirigami.Action components. This action has an appropriate icon and executes the Qt.quit() function when triggered, closing the application.

Since we are keeping our global drawer simple for now, we are setting the GlobalDrawer.isMenu property to true. This displays our global drawer as a normal application menu, taking up less space than the default global drawer pane.

Suggerimento

The Actions based components page of these docs provides further detail on Kirigami Actions and how they can be used.

Le azioni sono contestuali

Kirigami components are designed in such a way that the place where you put Kirigami Actions is relevant. As seen above, if you add actions to a Kirigami.Page, Kirigami.ScrollablePage or any other derivative Page component, they will show up on the right side of the header in desktop mode, and on the bottom in mobile mode.

Similarly, if Kirigami Actions are added to a Kirigami.GlobalDrawer, they will show up in the resulting drawer or menu.

Other examples of Kirigami Actions showing up differently depending on their parent component are:

Kirigami.ContextDrawer - ContextDrawer tutorial here
Kirigami.AbstractCard and derivatives - Card tutorial here
Kirigami.Dialog and derivatives - Dialog tutorial here
Kirigami.ActionToolBar - ActionToolBar tutorial here

Among other Kirigami components.

Il nostro programma finora

Main.qml:

  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
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    id: root

    width: 400
    height: 300

    title: i18nc("@title:window", "Day Kountdown")

    // Global drawer element with app-wide actions
    globalDrawer: Kirigami.GlobalDrawer {
        // Makes drawer a small menu rather than sliding pane
        isMenu: true
        actions: [
            Kirigami.Action {
                text: i18n("Quit")
                icon.name: "application-exit-symbolic"
                shortcut: StandardKey.Quit
                onTriggered: Qt.quit()
            }
        ]
    }

    ListModel {
        id: kountdownModel
        ListElement {
            name: "Dog birthday!!"
            description: "Big doggo birthday blowout."
            date: 100
        }
    }

    Component {
        id: kountdownDelegate
        Kirigami.AbstractCard {
            contentItem: Item {
                implicitWidth: delegateLayout.implicitWidth
                implicitHeight: delegateLayout.implicitHeight
                GridLayout {
                    id: delegateLayout
                    anchors {
                        left: parent.left
                        top: parent.top
                        right: parent.right
                    }
                    rowSpacing: Kirigami.Units.largeSpacing
                    columnSpacing: Kirigami.Units.largeSpacing
                    columns: root.wideScreen ? 4 : 2

                    Kirigami.Heading {
                        Layout.fillHeight: true
                        level: 1
                        text: date
                    }

                    ColumnLayout {
                        Kirigami.Heading {
                            Layout.fillWidth: true
                            level: 2
                            text: name
                        }
                        Kirigami.Separator {
                            Layout.fillWidth: true
                            visible: description.length > 0
                        }
                        Controls.Label {
                            Layout.fillWidth: true
                            wrapMode: Text.WordWrap
                            text: description
                            visible: description.length > 0
                        }
                    }
                    Controls.Button {
                        Layout.alignment: Qt.AlignRight
                        Layout.columnSpan: 2
                        text: i18n("Edit")
                    }
                }
            }
        }
    }

    pageStack.initialPage: Kirigami.ScrollablePage {
        title: i18nc("@title", "Kountdown")

        // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
        actions: [
            Kirigami.Action {
                id: addAction
                // Name of icon associated with the action
                icon.name: "list-add-symbolic"
                // Action text, i18n function returns translated string
                text: i18nc("@action:button", "Add kountdown")
                // What to do when triggering the action
                onTriggered: kountdownModel.append({
                    name: "Kirigami Action added card!",
                    description: "Congratulations, your Kirigami Action works!",
                    date: 1000
                })
            }
        ]

        Kirigami.CardsListView {
            id: cardsView
            model: kountdownModel
            delegate: kountdownDelegate
        }
    }
}

Layouts, ListViews, and Cards

Aggiungere una finestra