Usar fitxers i senyals separats

Separar el codi difícil de manejar en diferents fitxers i adjuntar els senyals als vostres components.

Però, per què?

Per primera vegada, separarem alguns dels nostres components en els seus propis fitxers en QML. Si seguim afegint coses a main.qml, ràpidament serà difícil saber què fa què, i correm el risc d'enterbolir el nostre codi.

Primer haurem d'afegir els nostres fitxers nous dins del nostre resources.qrc, el qual hem creat a la primera part d'aquesta guia d'aprenentatge.

<RCC>
    <qresource prefix="/">
        <file alias="main.qml">contents/ui/main.qml</file>
        <file alias="AddEditSheet.qml">contents/ui/AddEditSheet.qml</file>
        <file alias="KountdownDelegate.qml">contents/ui/KountdownDelegate.qml</file>
    </qresource>
</RCC>

Usar els nostres fitxers nous

Ens caldrà trobar alguna forma d'utilitzar els nostres fitxers nous en el main.qml. Afortunadament, tot el que hem de fer és incloure una declaració d'aquests components en el nostre main.qml, com aquesta:

AddEditSheet {
    id: addEditSheet
}

Estendre el nostre full d'afegir a un full d'afegir/editar

Mentre que a l'última guia d'aprenentatge hem fet que el nostre botó d'afegir un compte enrere fes alguna cosa, el botó d'editar en les nostres targetes de compte enrere encara segueix inactiu. També hem creat un full d'afegir que ara podríem reutilitzar perquè també serveixi com un full d'editar... però abans d'arribar a això, necessitem afegir un parell de coses addicionals al nostre main.qml.

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
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")

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

    ListModel {
        id: kountdownModel
    }

    // Fetches item from addEditSheet.qml and does action on signal
    AddEditSheet {
        id: addEditSheet
        onAdded: kountdownModel.append({
            "name": name,
            "description": description,
            "date": Date.parse(kdate)
        });
        onEdited: kountdownModel.set(index, {
            "name": name,
            "description": description,
            "date": Date.parse(kdate)
        });
        onRemoved: kountdownModel.remove(index, 1)
    }

    // Function called by 'edit' button on card and by 'add'-Action
    function openPopulatedSheet(mode, index = -1, listName = "", listDesc = "", listDate = "") {
        addEditSheet.mode = mode
        addEditSheet.index = index;
        addEditSheet.name = listName
        addEditSheet.description = listDesc
        addEditSheet.kdate = listDate

        addEditSheet.open()
    }

    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: openPopulatedSheet("add")
        }

        Kirigami.CardsListView {
            id: layout
            model: kountdownModel
            delegate: KountdownDelegate {}
        }
    }
}

Els canvis clau que hem realitzat impliquen l'addició de la nostra definició de component AddEditSheet (i KountdownDelegate més avall) i una funció nova anomenada openPopulateSheet().

Vegem la nostra definició AddEditSheet:

AddEditSheet { 
    id: addEditSheet
    onEdited: kountdownModel.set(index, {
        name,
        description,
        date,
    });
    onAdded: kountdownModel.append({
        name,
        description,
        date,
    });
}

onAdded i onEdited són controladors de senyals. Igual com onTriggered es crida quan fem clic sobre una acció, també podem utilitzar controladors que responguin als nostres senyals personalitzats.

AddEditSheet.qml

Mirant el nostre nou AddEditSheet.qml (el nostre full d'afegir recuperat), podem veure com funcionen aquests senyals:

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

// Overlay sheets appear over a part of the window
Kirigami.OverlaySheet {
    id: addEditSheet

    // Sheet mode
    property string mode: "add"

    property int index: -1
    property alias name: nameField.text
    property alias description: descriptionField.text
    property alias kdate: dateField.text

    // Signals can be read and certain actions performed when these happen
    signal added (string name, string description, var kdate)
    signal edited(int index, string name, string description, var kdate)
    signal removed(int index)

    header: Kirigami.Heading {
        // i18nc is useful for adding context for translators
        text: mode === "add" ? i18nc("@title:window", "Add kountdown") :
            i18nc("@title:window", "Edit kountdown")
    }
    // Form layouts help align and structure a layout with several inputs
    Kirigami.FormLayout {
        // Textfields let you input text in a thin textbox
        Controls.TextField {
            id: nameField
            // Provides label attached to the textfield
            Kirigami.FormData.label: i18nc("@label:textbox", "Name:")
            // Placeholder text is visible before you enter anything
            placeholderText: i18n("Event name (required)")
            // What to do after input is accepted (i.e. pressed enter)
            // In this case, it moves the focus to the next field
            onAccepted: descriptionField.forceActiveFocus()
        }
        Controls.TextField {
            id: descriptionField
            Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
            placeholderText: i18n("Optional")
            onAccepted: dateField.forceActiveFocus()
        }
        Controls.TextField {
            id: dateField
            Kirigami.FormData.label: i18nc("@label:textbox", "Date:")
            inputMask: "0000-00-00"
            placeholderText: i18n("YYYY-MM-DD")
        }
        // This is a button.
        Controls.Button {
            id: deleteButton
            Layout.fillWidth: true
            text: i18nc("@action:button", "Delete")
            visible: mode === "edit"
            onClicked: {
                addEditSheet.removed(addEditSheet.index)
                close();
            }
        }
        Controls.Button {
            id: doneButton
            Layout.fillWidth: true
            text: i18nc("@action:button", "Done")
            // Button is only enabled if the user has entered something into the nameField
            enabled: nameField.text.length > 0
            onClicked: {
                // Add a listelement to the kountdownModel ListModel
                if(mode === "add") {
                    addEditSheet.added(
                        nameField.text,
                        descriptionField.text,
                        dateField.text
                    );
                }
                else {
                    addEditSheet.edited(
                        index,
                        nameField.text,
                        descriptionField.text,
                        dateField.text
                    );
                }
                close();
            }
        }
    }
}

Quan se'ls crida, els senyals invoquen als seus controladors. En aquest cas, hem creat dos senyals, added i edited, que podem invocar amb resultats diferents, i als quals podem adjuntar informació sobre el compte enrere que estem afegint o creant. Una cosa interessant sobre els senyals és que exposen les variables definides en elles a les funcions que les estan escoltant, amb el qual podem cridar a aquests noms de variable en els nostres controladors onEdited i onAdded en el main.qml. Els nostres senyals són invocats pel botó «Done» depenent d'en què s'estableixi la propietat mode, definida a la part superior de la nostra AddEditSheet.

La propietat mode també controla diverses altres coses: principalment, en què s'ha establert el títol del nostre full i quin text s'inclourà en els nostres camps de text. No obstant això, de manera predeterminada, la nostra propietat mode estarà establerta per a afegir...

El que ens porta de tornada al main.qml i la nostra funció openPopulateSheet() nova. És possible que hàgiu notat que aquesta és la que es cridarà ara quan s'activi l'acció d'afegir un compte enrere. Aquesta funció pren diversos arguments que s'han proporcionat amb valors predeterminats. Això és útil quan senzillament volem afegir un compte enrere, perquè podem tenir la crida a la funció concisa openPopulateSheet("add"). Més important encara, aquesta funció estableix totes les propietats rellevants a AddEditSheet.

function openPopulatedSheet(mode, index = -1, listName = "", listDesc = "", listDate = "") {
    addEditSheet.mode = mode
    addEditSheet.index = index;
    addEditSheet.name = listName
    addEditSheet.description = listDesc
    addEditSheet.kdate = listDate

    addEditSheet.open()
}

El mode canvia el full d'afegir/editar depenent de si aquest argument està establert a "add" o a "edit".
Es necessita un index, de manera que quan desem el nostre compte enrere editat, es modifiqui el correcte
listName, listDesc i listDate són els detalls rellevants del compte enrere que han de col·locar-se en els camps del full.

Per descomptat, per a emprar el nostre full per a qualsevol cosa a més d'afegir comptes enrere, primer haurem de fer que funcioni el botó d'editar en les nostres targetes. Però si veieu la nostra Kirigami.CardsListView en el main.qml...

Kirigami.CardsListView {
    id: layout
    model: kountdownModel
    delegate: KountdownDelegate {}
}

KountdownDelegate.qml

Substituïm la nostra Kirigami.AbstractCard per una definició de component delegat des de KountdownDelegate.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
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.AbstractCard {
    id: kountdownDelegate
    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: i18n("%1 days", Math.round((date-Date.now())/86400000))
            }

            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
                // Column spanning within grid layout (vertically in this case)
                Layout.columnSpan: 2
                text: i18n("Edit")
                onClicked: openPopulatedSheet("edit", index, name, description, new Date(date).toISOString().slice(0,10))
            }
        }
    }
}

La propietat onClicked del botó «Edita» en les nostres targetes, ara crida a la funció openPopulateSheet(), amb les propietats de l'element de llista obtingudes des de la targeta establertes com els arguments per a aquesta funció. Amb aquestes, el full es pot omplir amb el text correcte.

Amb això, ja tenim un full completament funcional on podrem afegir i editar els nostres comptes enrere!

Crear fulls superposats

Passos següents