Criar folhas sobrepostas

Aprender a lidar com as folhas sobrepostas.

Tornar a nossa aplicação útil

Temos uma janela, temos cartões e temos acções. Contudo, ainda precisamos de descobrir uma forma de introduzir um nome, descrição e data à nossa escolha.

Uma forma de o fazermos é criar uma nova página onde colocamos os elementos de entrada necessários. Contudo, uma página inteira dedicada apenas a solicitar um nome, descrição e data parece um pouco excessivo.

Em vez disso, iremos usar uma folha sobreposta.

Folha de adição de contagem

O novo componente que vamos adicionar é um Kirigami.OverlaySheet. As folhas sobrepostas ficam sobre o conteúdo da janela e poderão ser usadas para uma grande variedade de fins, como fornecer informações extra que sejam relevantes para o conteúdo actual. São uma espécie de janelas instantâneas especiais, com a diferença que não podem ser movidas.

Kirigami.OverlaySheet {
	id: addSheet
	header: Kirigami.Heading {
		text: i18nc("@title:window", "Add kountdown")
	}
	Kirigami.FormLayout {
		Controls.TextField {
			id: nameField
			Kirigami.FormData.label: i18nc("@label:textbox", "Name:")
			placeholderText: i18n("Event name (required)")
			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:")
			placeholderText: i18n("YYYY-MM-DD")
			inputMask: "0000-00-00"
		}
		Controls.Button {
			id: doneButton
			Layout.fillWidth: true
			text: i18nc("@action:button", "Done")
			enabled: nameField.text.length > 0
			onClicked: {
				kountdownModel.append({
					name: nameField.text, 
					description: descriptionField.text, 
					// O método parse() processa um texto e devolve o número de milisegundos desde 1 de Janeiro de
					// 1970, às 00:00:00 UTC.
					date: Date.parse(dateField.text)
				});
				nameField.text = ""
				descriptionField.text = ""
				dateField.text = ""
				addSheet.close();
			}
		}
	}
}

Podemos atribuir às folhas sobrepostas um cabeçalho. O mesmo é atribuído através da propriedade header. Passámos o nosso com um Kirigami.Heading que contém um título relevante: ‘Add Kountdown’ (Adicionar uma Contagem).

Depois chegamos ao Kirigami.FormLayout. Este permite-nos criar facilmente formulários altamente adaptativos, os quais mostra as legendas dos campos e os campos propriamente ditos, tanto em ecrãs panorâmicos como em dispositivos móveis mais estreitos. Estas disposições de formulários estão desenhadas para lidarem com uma grande variedade de tipos de campos, ainda que para já nos foquemos com campos simples do tipo Controls.Textfield, que nos dão campos de texto simples onde poderemos escrever as coisas.

Criámos os elementos Controls.Textfield que funcionam como:

  1. Introdução do nome da nossa contagem
  2. Introdução da descrição da nossa contagem
  3. Introdução da data contra a qual estamos a fazer a contagem, que deverá ser indicada no formato AAAA-MM-DD.

Dentro de cada um destes elementos Controls.Textfield, estamos a configurar uma propriedade Kirigami.FormData.label que lhe permite definir legendas para eles. O formulário irá apresentar os textos correctos para cada um destes campos de texto. Iremos também definir o texto de substituição dentro dos campos com a propriedade placeholderText – este texto irá desaparecer assim que o utilizador começar a escrever algo no campo. Finalmente, iremos também configurar a propriedade onAccepted para invocar o método forceActiveFocus() do campo seguinte; isto irá mudar o campo activo assim que o utilizador carregar na tecla ENTER, melhorando a usabilidade do nosso formulário.

Também definimos uma propriedade chamada inputMask no campo de texto da nossa data. Se configurarmos a mesma como "0000-00-00", impedimos que o utilizador escreva algo que possa quebrar a funcionalidade da aplicação (como por exemplo texto), restringindo-os a indicar apenas números e traços, que poderemos então usar para tentar processar um objecto de data.

No fim do nosso formulário estamos a incluir um botão que adiciona a nossa nova contagem decrescente ao modelo da lista. Configurámos a propriedade enabled com uma instrução condicional que verifica se o campo do nome está vazio ou não: se estiver, o botão fica desactivado, e vice-versa. Quando o botão for carregado, ele invoca o método append do nosso modelo de lista kountdownModel, adicionando um objecto de JavaScript que inclui as propriedades que fornecemos. Também nos certificamos que limpamos os campos de texto, configurando as suas propriedades text respectivas com um texto vazio. Finalmente, podemos invocar um método na nossa folha sobreposta, o close(), que a irá fechar.

Usar a nossa folha

actions.main: Kirigami.Action {
	id: addAction
	icon.name: "list-add"
	text: i18nc("@action:button", "Add kountdown")
	onTriggered: addSheet.open()
}

As folhas sobrepostas têm dois métodos, o open() e o close(), que controlam a abertura e o fecho deste componente. Neste caso, configurámos a folha para ser aberta quando activarmos a nossa acção. Assim que tivermos gravado os nossos ficheiros e compilado o nosso programa, seremos capazes de adicionar as nossas próprias contagens decrescentes personalizadas!