Listas

As listas 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.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.13 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 - ainda que isto possa 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 helpfulAction do Kirigami.PlaceHolderMessage.

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

Cabeçalhos das listas

As ListView's também suportam componentes de cabeçalho com a propriedade header e o Kirigami oferece um componente atraente para esse fim: Kirigami.ItemViewHeader. Fornecemos este este componente com texto para a propriedade title e a localização de uma imagem para a propriedade backgroundImage.source e é tudo.

Uma propriedade interessante da lista é a headerPositioning. Esta afecta a forma como o nosso cabeçalho se irá mover quando estivermos a interagir com uma lista extensa que se expanda para lá da altura da página. O headerPositioning poderá ser configurado com três diferentes opções:

• ListView.OverlayHeader: Nesta configuração, o cabeçalho contrair-se-á quando começarmos a deslocar para baixo, mas continuará visível num estado mais componente.
• ListView.PullBackHeader: O cabeçalho irá desaparecer quando nos deslocarmos para baixo, mas voltará a aparecer à medida que nos deslocamos para cima, mesmo que não tenha chegado ao topo da lista.
• ListView.InlineHeader: O cabeçalho irá actuar como parte da lista e permanece no topo da lista.

ListView {
  id: myList

  headerPositioning: ListView.OverlayHeader
  header: Kirigami.ItemViewHeader {
  backgroundImage.source: "../banner.jpg"
    title: "LongListView"
  }

  model: 200

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