Adicionar acções

Aprender mais como funcionam as Action's (acções) do Kirigami e como o ajudarão a tornar a sua aplicação mais útil.

Recapitulação

Até agora, conseguimos criar uma aplicação simples que mostra cartões. Contudo, não temos nenhuma forma de adicionar cartões novos à nossa de área de cartões.

Neste tutorial, iremos ver as acções do Kirigami. Estas ajudá-lo-ão a adicionar interactividade à nossa aplicação de uma forma consistente, rápida e acessível.

Acções

Uma Kirigami.Action encapsula uma acção da interface do utilizador. Podemos usá-las para oferecer às nossas aplicações acções fáceis de aceder e que são essenciais à sua funcionalidade.

Se tiver usado antes as aplicações do Kirigami, provavelmente já interagiu com as acções do Kirigami. Nesta imagem, poderemos ver as acções à direita do título da página com vários ícones. As acções do Kirigami poderão ser apresentadas de várias formas e poderão efectuar uma grande variedade de acções.

Adicionar contagens decrescentes

Uma aplicação de contagens decrescentes sem a capacidade de adicionar contagens é bastante inútil. Iremos criar uma acção que nos permite fazer isso.

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

Estamos a colocar a nossa acção do Kirigami dentro da nossa página principal com base nos nossos tutoriais. Se o quiséssemos, poderíamos adicionar mais acções à nossa página (e mesmo associar acções dentro de acções!). Os componentes Kirigami.Action são usados como acções de contexto dentro das páginas do Kirigami. Estamos a configurar esse valor de forma específica na propriedade actions.main da Kirigami.Page : o objecto actions tem propriedades que nos deixam definir acções diferentes em posições diferentes; contudo, dado que a nossa acção "Adicionar uma contagem" é algo tão central na nossa interface, estamos a configurá-lo como acção principal desta página.

As propriedades id e text deverão ser familiares dos tutoriais anteriores. Contudo, a nova propriedade Action.icon deverá ser interessante: é um objecto com várias propriedades que lhe permitirão mostrar certos ícones para as suas acções. Felizmente, para usar os ícones do KDE, tudo o que é preciso fazer é configurar a propriedade 'name' com a propriedade do ícone, icon.name.

Nota

O Cuttlefish é uma aplicação do KDE que lhe permite ver todos os ícones que poderá usar para a sua aplicação. A mesma oferece um conjunto de funcionalidades úteis, como as antevisões da sua aparência com os vários itens instalados, antevisões com vários tamanhos, etc. Poderá concluir que é uma ferramenta útil para decidir quais os itens a usar na sua aplicação.

Muitos dos ícones do KDE seguem a especificação do FreeDesktop para nomes de ícones. Como tal, poderá querer consultar a página Web do projecto FreeDesktop, o qual contém todos os nomes de ícones compatíveis com os vários ambientes de trabalho.

A propriedade onTriggered é a mais importante. É o que a nossa acção irá fazer quando for usada. Irá reparar que, no nosso exemplo, estamos a usar o método kountdownModel.append que criámos no nosso tutorial anterior. Este método permite-nos adicionar um novo elemento ao nosso modelo de lista. Estamos a passar-lhe um objecto que tem as propriedades relevantes para as nossas contagens decrescentes (nome, descrição e uma data substituta).

De cada vez que carregamos no nosso botão "Adicionar uma contagem" em cima e à direita, é adicionada a nossa contagem decrescente personalizada.

Área global

Reparou nessas três linhas a seguir ao título da página na imagem anterior? Isso é um menu em hambúrguer que abre uma Kirigami.GlobalDrawer . As áreas globais são úteis para a navegação global e para as acções: por outras palavras, essas coisas que poderá precisar de usar em toda a sua aplicação. Iremos criar uma área global simples que inclua um botão para "sair".

Kirigami.ApplicationWindow {
    id: root
    ...
    globalDrawer: Kirigami.GlobalDrawer {
        isMenu: true
        actions: [
            Kirigami.Action {
                text: i18n("Quit")
                icon.name: "gtk-quit"
                shortcut: StandardKey.Quit
                onTriggered: Qt.quit()
            }
        ]
    }
    ...
}

Agora iremos colocar a nossa área global dentro da janela da nossa aplicação. A propriedade principal que precisa de prestar atenção é a GlobalDrawer.actions , que tem a forma de uma lista de componentes Kirigami.Action . Esta acção tem um ícone apropriado e invoca a função Qt.quit() , fechando a aplicação.

Dado que estamos a manter a nossa área global simples por agora, vamos configurar a propriedade GlobalDrawer.isMenu como verdadeira. Isto mostra a nossa área global como um menu da aplicação normal, ocupando menos espaço que a a área global predefinida.

Nota

A página de componentes baseados em Action's da secção de 'Componentes' desta documentação oferece mais detalhes sobre as acções do Kirigami e como podem ser usadas.

A nossa aplicação até agora

  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
import QtQuick 2.15
import QtQuick.Controls 2.15 as Controls
import QtQuick.Layouts 1.15
import org.kde.kirigami 2.20 as Kirigami

Kirigami.ApplicationWindow {
    id: root

    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: "gtk-quit"
                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")
                        //onClicked: to be done... soon!
                    }
                }
            }
        }
    }

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

        // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
        actions.main: Kirigami.Action {
            id: addAction
            // Name of icon associated with the action
            icon.name: "list-add"
            // 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: layout
            model: kountdownModel
            delegate: kountdownDelegate
        }
    }
}

Layouts, ListViews e Cards

Criar folhas sobrepostas