Creación de hojas superpuestas

Familiarizarse con las hojas superpuestas.

Hacer que nuestra aplicación sea útil

Tenemos una ventana, tenemos tarjetas y tenemos acciones. Sin embargo, todavía necesitamos encontrar alguna forma de introducir un nombre, una descripción y una fecha de nuestra elección.

Una forma de hacerlo sería crear una nueva página para colocar los elementos de entrada necesarios. Sin embargo, una página entera dedicada a proporcionar un nombre, una descripción y una fecha parece un poco excesiva.

En lugar de ello, vamos a usar una hoja superpuesta.

Hoja para añadir una cuenta regresiva

El nuevo componente que añadimos es Kirigami.OverlaySheet. Las hojas superpuestas se colocan sobre el contenido de la ventana y se pueden usar para diversos propósitos, como proporcionar información adicional relevante para el contenido actual. Son como elegantes ventanas emergentes, excepto que no se pueden mover.

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, 
					// El método parse() analiza una cadena de texto y devuelve el número de milisegundos desde el
					// 1 de enero de 1970, a las 00:00:00 UTC.
					date: Date.parse(dateField.text)
				});
				nameField.text = ""
				descriptionField.text = ""
				dateField.text = ""
				addSheet.close();
			}
		}
	}
}

Podemos proporcionar una cabecera a las hojas superpuestas. Esto se define en la propiedad header. Hemos proporcionado a la nuestra un Kirigami.Heading que contiene un título relevante: ‘Añadir Kountdown’.

Luego llegamos a un Kirigami.FormLayout. Este nos permite crear con facilidad formularios de entrada receptivos, que muestran claramente las etiquetas de las entradas y las propias entradas, tanto en pantallas panorámicas como en dispositivos móviles más estrechos. Estos formularios están diseñados para funcionar con diversos tipos de entrada, aunque nos ceñimos a entradas simples de Controls.Textfield que nos proporcionan cuadros de texto sencillos en los que escribir.

Hemos creado elementos Controls.Textfield que actúan como:

  1. Entrada para el nombre de nuestra cuenta atrás
  2. Entrada para la descripción de nuestra cuenta atrás
  3. Entrada para la fecha que vamos a contar hacia atrás, que se debe indicar con el formato YYYY-MM-DD.

Dentro de cada uno de estos elementos Controls.Textfield, hemos asignado la propiedad Kirigami.FormData.label, que nos permite definir etiquetas para ellos. El formulario mostrará las etiquetas correctas para cada una de estas entradas de texto. También hemos indicado un texto de relleno dentro de los campos con la propiedad placeholderText (este texto desaparecerá en cuanto el usuario empiece a escribir en el campo). Finalmente, también hemos definido la propiedad onAccepted para que llame al método forceActiveFocus() del siguiente campo; esto hará que cambie el campo activo cuando el usuario haya pulsado la tecla «Intro», mejorando la usabilidad del formulario.

También hemos definido una propiedad llamada inputMask del campo de texto para nuestra fecha. Al asignarle el valor "0000-00-00" se impide que el usuario introduzca algo que podría romper el funcionamiento de la aplicación (como un texto), limitándolo a introducir solo dígitos que luego se analizarán como una fecha.

Al final de nuestro formulario hemos incluido un botón que añade la nueva cuenta atrás al modelo de lista. Hemos asignado la propiedad enabled a una sentencia condicional que comprueba si el campo del nombre está vacío o no: si lo está, el botón estará desactivado, y viceversa. Al pulsar el botón, se llama al método append de nuestro modelo de lista kountdownModel, añadiendo un objeto JavaScript que incluye las propiedades que hemos proporcionado. También nos aseguramos de borrar los campos de texto asignando a sus propiedades text una cadena vacía. Finalmente, llamamos a un método de nuestra hoja superpuesta, close(), que la cierra.

Uso de nuestra hoja

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

Las hojas superpuestas tienen dos métodos, open() y close(), que controlan la apertura y el cierre de este componente. En este caso, hemos definido que la hoja se abra cuando se desencadena nuestra acción. Una vez que guardemos nuestros archivos y compilemos nuestro programa, ¡podremos añadir nuestras propias cuentas atrás personalizadas!