Usar a Galeria do Kirigami

Usar a Galeria do Kirigami para encontrar padrões de código

A Galeria do Kirigami é um amigo útil quando estiver a desenvolver uma aplicação em Kirigami. É uma aplicação que usa as funcionalidades do Kirigami, oferece ligações para o código-fonte, dicas de como usar os componentes, assim como referências para as páginas do HIG correspondentes.

Sugestão

Antes de prosseguir, instale por favor a Galeria do Kirigami. Já deverá existir no repositório da sua distribuição de Linux.

Procurar uma grelha de cartões

Ao navegar pela aplicação da Galeria do Kirigami, iremos encontrar o componente da galeria da "Grelha de cartões". Este é um bom candidato por exemplo para mostrar uma grelha de cartões de contactos.

Lista de componentes da galeria do Kirigami

Depois de seleccionar o componente da "Grelha de cartões", iremos carregar no botão "Informações" em cima e à direita, para obter algumas informações úteis sobre os tipos Card e AbstractCard.

Na secção inferior desta janela de informações, iremos também encontrar uma referência para o código-fonte da "Área da Grelha de Cartões". Vejamos essa página.

Implementar uma grelha de cartões

Iremos reutilizar a maioria do código encontrado na Galeria da Grelha de Cartões, na página de código-fonte do CardsGridViewGallery. Em particular, iremos remover as partes extra da OverlaySheet (que é a implementação da Galeria do Kirigami que nos ajudou a obter o repositório do código-fonte do 'kirigami-gallery').

Como tal, iremos substituir a componente Page do 'main.qml' da aplicação de esqueleto com a ScrollablePage abaixo:

Kirigami.ScrollablePage {
    title: i18n("Address book (prototype)")

    Kirigami.CardsGridView {
        id: view

        model: ListModel {
            id: mainModel
        }

        delegate: card
    }
}

O que fizemos até agora foi criar uma ScrollablePage e colocar uma CardsGridView nela, dado que queremos mostrar uma grelha de cartões gerada a partir de um modelo. Os dados de cada contacto são obtidos com um ListModel enquanto o delegado do cartão é responsável pela apresentação dos dados. Para mais informações sobre os modelos e vistas no Qt Quick, veja aqui.

Agora vamos preencher o modelo que irá alimentar a nossa grelha com dados. Na definição do Kirigami.ScrollablePage , logo a seguir a:

      delegate: card
    }

adicione o seguinte abaixo:

Component.onCompleted: {
    mainModel.append({
        "firstname": "Pablo",
        "lastname": "Doe",
        "cellphone": "6300000002",
        "email" : "jane-doe@example.com",
        "photo": "qrc:/konqi.jpg"
    });
    mainModel.append({
        "firstname": "Paul",
        "lastname": "Adams",
        "cellphone": "6300000003",
        "email" : "paul-adams@example.com",
        "photo": "qrc:/katie.jpg"
    });
    mainModel.append({
        "firstname": "John",
        "lastname": "Doe",
        "cellphone": "6300000001",
        "email" : "john-doe@example.com",
        "photo": "qrc:/konqi.jpg"
    });
    mainModel.append({
        "firstname": "Ken",
        "lastname": "Brown",
        "cellphone": "6300000004",
        "email" : "ken-brown@example.com",
        "photo": "qrc:/konqi.jpg"
    });
    mainModel.append({
        "firstname": "Al",
        "lastname": "Anderson",
        "cellphone": "6300000005",
        "email" : "al-anderson@example.com",
        "photo": "qrc:/katie.jpg"
    });
    mainModel.append({
        "firstname": "Kate",
        "lastname": "Adams",
        "cellphone": "6300000005",
        "email" : "kate-adams@example.com",
        "photo": "qrc:/konqi.jpg"
    });
}

Nota

Repare no {} que indica que estamos a adicionar um objecto de JavaScript ao nosso modelo.

A componente de modelo da nossa implementação está pronta. Vamos prosseguir com a definição de um delegado que será responsável por mostrar os dados. Como tal, iremos adicionar o seguinte código à nossa página no 'main.qml', logo a seguir à definição do Component.onCompleted :

Component {
    id: card

    Kirigami.Card {

        height: view.cellHeight - Kirigami.Units.largeSpacing

        banner {
            title: i18nc("@title", "%1 %2", model.firstname, model.lastname)
            titleIcon: "im-user"
        }

        contentItem: Column {
            id: content

            spacing: Kirigami.Units.smallSpacing

            Controls.Label {
                wrapMode: Text.WordWrap
                text: i18nc("@label", "Mobile: %1", model.cellphone)
            }

            Controls.Label {
                wrapMode: Text.WordWrap
                text: i18nc("@label", "Email: %1", model.email)
            }
        }
    }
}

A seguir à informação relacionada na página da API do Kirigami.Card iremos preencher um " banner ", que irá actuar como cabeçalho que apresentará o nome do contacto, assim como um ícone do contacto.

O conteúdo principal do cartão foi preenchido com o número de telemóvel e o e-mail do contacto, estruturado como uma Column de Label's .

A aplicação deverá ficar semelhante ao seguinte:

Sugestão

Poderá encontrar o código-fonte do tutorial na totalidade em invent.kde.org.

Como último passo, iremos adicionar alguma funcionalidade de testes a cada cartão. Em particular, será adicionada uma Action call (chamar). Contudo, em vez de uma chamada a sério, será apresentada uma notificação passiva. Como tal, iremos mudar o Component do card para o seguinte:

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
            Component {
                id: card
                Kirigami.Card {
                    height: view.cellHeight - Kirigami.Units.largeSpacing
                    banner {
                        title: i18nc("@title", "%1 %2", model.firstname, model.lastname)
                        titleIcon: "im-user"
                    }
                    contentItem: Column {
                        id: content
                        spacing: Kirigami.Units.smallSpacing

                        Controls.Label {
                            wrapMode: Text.WordWrap
                            text: i18nc("@label", "Mobile: %1", model.cellphone)
                        }

                        Controls.Label {
                            wrapMode: Text.WordWrap
                            text: i18nc("@label", "Email: %1", model.email)
                        }
                    }

                    actions: [
                        Kirigami.Action {
                            text: "Call"
                            icon.name: "call-start"
                            onTriggered: {
                                showPassiveNotification("Calling %1 %2...".arg(model.firstname).arg(model.lastname))
                            }
                        }                                        

Assim, adicionámos uma Kirigami.Action que, assim que for desencadeada (ao carregar no botão da acção), irá apresentar uma notificação passiva .

Resultado

Finalmente, a nossa aplicação deverá ficar parecida com o seguinte:

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

Kirigami.ApplicationWindow {
    id: root
    title: "Kirigami Tutorial"
    pageStack.initialPage: mainPageComponent

    Component {
        id: mainPageComponent

        Kirigami.ScrollablePage {
            title: "Address book (prototype)"
            
            Kirigami.CardsGridView{
                id: view
                model: ListModel {
                    id: mainModel
                }
                delegate: card
            }

            Component.onCompleted: {
                mainModel.append({
                    "firstname": "Pablo",
                    "lastname": "Doe",
                    "cellphone": "6300000002",
                    "email" : "jane-doe@example.com",
                    "photo": "qrc:/konqi.jpg"
                });
                mainModel.append({
                    "firstname": "Paul",
                    "lastname": "Adams",
                    "cellphone": "6300000003",
                    "email" : "paul-adams@example.com",
                    "photo": "qrc:/katie.jpg"
                });
                mainModel.append({
                    "firstname": "John",
                    "lastname": "Doe",
                    "cellphone": "6300000001",
                    "email" : "john-doe@example.com",
                    "photo": "qrc:/konqi.jpg"
                });
                mainModel.append({
                    "firstname": "Ken",
                    "lastname": "Brown",
                    "cellphone": "6300000004",
                    "email" : "ken-brown@example.com",
                    "photo": "qrc:/konqi.jpg"
                });
                mainModel.append({
                    "firstname": "Al",
                    "lastname": "Anderson",
                    "cellphone": "6300000005",
                    "email" : "al-anderson@example.com",
                    "photo": "qrc:/katie.jpg"
                });
                mainModel.append({
                    "firstname": "Kate",
                    "lastname": "Adams",
                    "cellphone": "6300000005",
                    "email" : "kate-adams@example.com",
                    "photo": "qrc:/konqi.jpg"
                });
            }

            Component {
                id: card
                Kirigami.Card {
                    height: view.cellHeight - Kirigami.Units.largeSpacing
                    banner {
                        title: i18nc("@title", "%1 %2", model.firstname, model.lastname)
                        titleIcon: "im-user"
                    }
                    contentItem: Column {
                        id: content
                        spacing: Kirigami.Units.smallSpacing

                        Controls.Label {
                            wrapMode: Text.WordWrap
                            text: i18nc("@label", "Mobile: %1", model.cellphone)
                        }

                        Controls.Label {
                            wrapMode: Text.WordWrap
                            text: i18nc("@label", "Email: %1", model.email)
                        }
                    }

                    actions: [
                        Kirigami.Action {
                            text: "Call"
                            icon.name: "call-start"
                            onTriggered: {
                                showPassiveNotification("Calling %1 %2...".arg(model.firstname).arg(model.lastname))
                            }
                        }                                        
                    ]
                }
            }
        }
    }
}

Grelha com acção de chamada desencadeada

Próximos passos

Colors and themes in Kirigami