Form layouts

Os componentes Kirigami.FormLayout tornam simples para si a criação de formulários em conformidade com as Linhas-Mestras de Interface Humana do KDE. São óptimas para janelas de configuração e para grandes grupos de controlos e campos de entrada relacionados entre si.

Quando tiverem espaço suficiente, as disposições dos formulários irão ocupar duas colunas. A coluna da esquerda será ocupada pelos textos fornecidos pelos componentes-filhos do formulário, enquanto o lado direito será ocupado pelos filhos propriamente ditos. Em janelas com mais restrições de espaço (ou em dispositivos móveis), os formulários irão consistir numa única coluna vertical com os textos dos componentes-filhos colocados logo acima do seu componente respectivo.

Formulário simples

Os componentes Kirigami.FormLayout são semelhantes aos componentes Layout do QtQuick, como o ColumnLayout ou o RowLayout. Os componentes filhos serão organizados automaticamente de acordo com o tamanho disponível na disposição do formulário.

Os filhos de um Kirigami.FormLayout têm uma propriedade chamada Kirigami.FormData.label. Esta propriedade permite-lhe mudar o texto que será apresentado no componente-filho em questão.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    pageStack.initialPage: Kirigami.Page {

        Kirigami.FormLayout {
            anchors.fill: parent

            Controls.TextField {
                Kirigami.FormData.label: "TextField 1:"
            }
            Controls.TextField {
                Kirigami.FormData.label: "TextField 2:"
            }
            Controls.TextField {
                Kirigami.FormData.label: "TextField 3:"
            }
        }
    }
}

Secções e separadores

Os FormLayouts também podem ser divididos em secções. Definir onde começa uma secção é tão simples como configurar o Kirigami.FormData.isSection de um componente-filho como verdadeiro. Isto irá fornecer ao componente alguma margem-extra no topo para demarcar o início da secção nova.

Os componentes Kirigami.Separator são mais adequados para iniciar secções novas. Um Kirigami.Separator irá desenhar uma linha horizontal fina, marcando o fim de uma secção. Se não quiser ter uma linha desenhada entre secções, poderá usar uma propriedade Item normal do QML. Em alternativa, poderá usar a propriedade Kirigami.FormData.isSection em qualquer outro componente.

Contudo, isto não é recomendado. Nos componentes em que o Kirigami.FormData.isSection é igual a true, o texto da legenda indicado para a propriedade Kirigami.FormData.label deste componente serão apresentados como o texto do cabeçalho da secção.

Este texto de cabeçalho é maior que o texto das legendas normais, dando aos utilizadores uma dica visual interessante sobre o que diz respeito o formulário.

Kirigami.FormLayout {
    anchors.fill: parent

    Controls.TextField {
        Kirigami.FormData.label: "TextField 1:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 2:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 3:"
    }
    Kirigami.Separator {
        Kirigami.FormData.isSection: true
        Kirigami.FormData.label: "New Section!"
    }
    ColumnLayout {
        Kirigami.FormData.label: "Radio buttons"
        Controls.RadioButton {
            text: "Radio 1"
            checked: true
        }
        Controls.RadioButton {
            text: "Radio 2"
        }
        Controls.RadioButton {
            text: "Radio 3"
        }
    }
    Item {
        Kirigami.FormData.isSection: true
        Kirigami.FormData.label: "Another Section! (lineless though)"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 4:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 5:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 5:"
    }
}

Filhos com marcações

Uma funcionalidade útil do Kirigami.FormLayout é que poderá adicionar opções de marcação aos seus filhos. Isto poderá ser útil em páginas de configuração, onde poderá querer que o utilizador active ou desactive uma dada configuração, assim como fornecer mais informações extra sobre essa configuração, como por exemplo num campo de texto.

Kirigami.FormLayout {
    anchors.fill: parent

    Controls.TextField {
        Kirigami.FormData.label: "First name:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "Middle name:"
        Kirigami.FormData.checkable: true
        enabled: Kirigami.FormData.checked
    }
    Controls.TextField {
        Kirigami.FormData.label: "Last name:"
    }
}

Forçar um formato para computador ou dispositivo móvel

Se preferir que a disposição do seu formulário fique consistente, independentemente do ambiente da sua aplicação, poderá usar a propriedade wideMode do componente Kirigami.FormLayout:

• Quando for configurada como verdadeira, a disposição do formulário ficará estruturada como se estivesse num formato amplo e optimização para computadores (em duas colunas)
• Se for falso, a disposição do formulário ficará estruturada num formato para dispositivos móveis (única coluna)

Kirigami.FormLayout {
    anchors.fill: parent
    wideMode: false

    Controls.TextField {
        Kirigami.FormData.label: "TextField 1:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 2:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 3:"
    }
}

Alinhar as suas legendas

Existem instâncias em que deseja atribuir uma legenda a componentes que tenham mais que uma linha ou a uma lista de componentes. Isto pode ser obtido se colocar a Kirigami.FormData.label no ColumnLayout, como poderá ter reparado nas Secções e Separadores. Por omissão, a legenda está posicionada verticalmente ao centro da disposição, o que nem sempre é desejável. Podemos mudar isto com a ajuda do Kirigami.FormData.labelAlignment.

Kirigami.FormLayout {
    anchors.fill: parent

    ColumnLayout {
        Kirigami.FormData.label: "This is a label:"
        Kirigami.FormData.labelAlignment: Qt.AlignTop

        Controls.Label {
            text: "This is some rather long text \nthat should elide to multiple lines \nto show how the label gets aligned."
            elide: Text.elideLeft
        }
    }
}

A definição do alinhamento das legendas é particularmente conveniente para gerir os componentes ou listas de componentes cujo tamanho não conhece de antemão. O Elisa é um óptimo exemplo disto:

Podemos fazer algo semelhante a isto com um operador ternário em JavaScript:

Kirigami.FormLayout {
    anchors.fill: parent

    ColumnLayout {
        Kirigami.FormData.label: "This is a label:"
        Kirigami.FormData.labelAlignment: labelText.text.lineCount > 1 ? Qt.AlignTop : Qt.AlignVCenter

        Controls.Label {
            id: labelText
            text: "This is some rather long text \nthat should elide to a new line \nso it appears below the Form Label."
            elide: Text.elideLeft
        }
    }
}