Listas

Os objectos Listview podê-lo-ão ajudar a mostrar os objectos de um modelo de forma atraente. Para usar uma lista, tem de ter em conta três coisas:

1. O modelo, que contém os dados que deseja apresentar na sua lista
2. O delegado, que define como será apresentado cada elemento no modelo
3. A lista em si, que irá mostrar informações do modelo de acordo com o método-delegado

Se quiser mais informações, a documentação do Qt tem uma página informativa sobre o tópico.

Criar uma lista básica

Uma lista tem duas propriedades essenciais que deveremos prestar atenção:

• O model, que aceita os dados ou o id do objecto que contém os dados
• O delegate, que aceita o componente-delegado que será usado para mostrar os dados no modelo

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.Page {

    ListView {
        id: myList

        // Fornecer um número na propriedade `model`irá gerar esse conjunto de itens de dados a
        // começar no 0.
        model: 200

        delegate: Kirigami.BasicListItem {
            label: "Item " + modelData
        }
    }
}

Nos casos em que os dados do seu modelo só contêm um dado individual, como exemplo acima, simplesmente poderá capturar os dados do modelo, usando como referência o modelData.

Una nota sobre os métodos delegados: se o seu modelo contém objectos com dados em propriedades com nomes, o nome dessas propriedades ficará automaticamente exposto ao seu delegado e só irá necessitar desses nomes no seu delegado.

ListModel {
    id: myModel
    ListElement { type: "Item"; number: 0 }
    ListElement { type: "Item"; number: 1 }
    ListElement { type: "Item"; number: 2 }
    ListElement { type: "Item"; number: 3 }
}

ListView {
    id: myList

    model: myModel

    delegate: Kirigami.BasicListItem {
        label: type + " " + number
    }
}

O Kirigami oferece um conjunto de componentes que foram desenhados de forma específica para serem usados em listas, como o Kirigami.BasicListItem , o Kirigami.CheckableListItem e o Kirigami.SwipeListItem , os quais se baseiam no Kirigami.AbstractListItem . Também existem o Kirigami.CheckDelegate , o Kirigami.RadioDelegate e o Kirigami.SwitchDelegate , que estão desenhados para tirar partido destes controlos específicos.

Contudo, não está limitado a usar estes componentes e poderá escolher os que deseja. Contudo, isto pode significar algumas afinações na sua disposição.

Mensagens de substituição

Em alguns casos, poderá querer usar uma lista que está vazia até que o utilizador faça algo. Nesses casos, o uso de uma Kirigami.PlaceholderMessage pode ser uma forma atraente de dizer ao seu utilizador que a lista está vazia e que poderão fazer algo quanto a isso.

Irá querer geralmente colocar uma PlaceholderMessage no centro da ListView e também irá querer que a mesma não ocupe a largura total da ListView. Também irá querer que não apareça visível assim que o modelo da ListView comece a ser preenchido com dados: felizmente, as ListViews têm uma propriedade chamada count que facilita isto em grande medida.

Também poderá querer adicionar uma acção útil à sua mensagem de substituição. Isto poderá ser feito se adicionar uma acção à propriedade PlaceholderMessage.helpfulAction .

ListView {
    id: myList

    model: ListModel { id: myModel }

    delegate: Kirigami.BasicListItem {
        label: text
    }

    Kirigami.PlaceholderMessage {
        anchors.centerIn: parent
        width: parent.width - Kirigami.Units.largeSpacing * 4
        visible: myList.count === 0
        text: "Add something to me!"

        helpfulAction: Kirigami.Action {
            icon.name: "list-add"
            text: "Add"
            onTriggered: myModel.append({"text": "Hello!!"})
        }
    }
}