Kirigami Addons FormCard QML Types

Form controls for settings pages and dialogs.

The FormCard module provides controls for settings pages and other forms. Import it with an alias so that its types are easy to distinguish from regular Qt Quick Controls:

import org.kde.kirigamiaddons.formcard as FormCard

Organizing a form

A FormCardPage is a scrollable page that arranges form sections. Each section normally has a FormHeader followed by a FormCard. Put the header beside the card in the page, not inside it. The card holds one or more form delegates, such as FormSwitchDelegate, FormSliderDelegate, FormTextFieldDelegate, or FormButtonDelegate. The card lays out its delegates vertically and supplies their shared background.

import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
    title: i18nc("@title", "Settings")

    FormCard.FormHeader {
        title: i18nc("@title:group", "Account")
    }

    FormCard.FormCard {
        autoSeparators: true

        FormCard.FormTextFieldDelegate {
            label: i18nc("@label:textbox", "Display name")
        }

        FormCard.FormSwitchDelegate {
            text: i18nc("@option:check", "Show online status")
        }
    }
}

Add another header and card for another section. The card's FormCard::autoSeparators property inserts separators between visible delegates when enabled. You can also add FormDelegateSeparator explicitly when you need to control where a separator appears.

Creating a custom delegate

Use AbstractFormDelegate as the root of a reusable QML component. It supplies the card's padding, hover and click behavior, and default background. Provide a contentItem with an implicit size, and expose any additional properties your delegate needs. For example, save the following as CounterDelegate.qml:

import QtQuick.Controls as Controls
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.AbstractFormDelegate {
    id: root

    property int count: 0

    text: i18nc("@action:button", "Count: %1").arg(count)
    onClicked: root.count++

    contentItem: Controls.Label {
        text: root.text
    }
}

Use CounterDelegate inside a FormCard, just like the built-in delegates. The inherited text property also gives this clickable delegate an accessible name. To remove the default background for a different design, set background: null.

Using delegates in a dialog

FormCardDialog provides a dialog header, a vertical layout for form delegates, and optional standard buttons. Place delegates directly inside it; no FormCard or FormCardPage is needed. Use standardButtons to choose the actions and handle onAccepted or onRejected as with a Qt Quick Controls Dialog:

import org.kde.kirigamiaddons.formcard as FormCard
import QtQuick.Controls

FormCard.FormCardDialog {
    title: "Add Thingy"
    autoSeparators: true

    standardButtons: Dialog.Ok | Dialog.Cancel
    FormCard.FormTextFieldDelegate {
        label: i18nc("@label:textbox Notebook name", "Name:")
    }

    FormCard.FormButtonDelegate {
        text: i18nc("@action:button", "Color")
        icon.name: "color-picker"
    }

    FormCard.FormButtonDelegate {
        text: i18nc("@action:button", "Icon")
        icon.name: "preferences-desktop-emoticons"
    }
}

Call dialog.open() from the action that should show the form. Custom delegates based on AbstractFormDelegate can also be placed directly in a FormCardDialog.

AboutKDEPage: An "About KDE" page using Form components.
AboutPage: An AboutPage that displays the about data using Form components.
AbstractFormDelegate: A base item for delegates to be used in a FormCard.
FormArrow: An arrow UI component used in Form delegates.
FormButtonDelegate: A Form delegate that corresponds to a clickable button.
FormCard: A single card that follows a form style.
FormCardDialog: A dialog designed to use FormCard delegates as its content.
FormCardPage: A scrollable page used as a container for one or more FormCards.
FormCheckDelegate: A Form delegate that corresponds to a checkbox.
FormColorDelegate: A FormCard delegate for colors.
FormComboBoxDelegate: A Form delegate that corresponds to a ComboBox.
FormDateTimeDelegate: FormDateTimeDelegate is a delegate for FormCard that lets the user enter either a date, a time or both.
FormDelegateBackground: A background for Form delegates.
FormDelegateCollapsible: A delegate designed to display or hide formcard contents.
FormDelegateSeparator: A context-aware separator.
FormFileDelegate: A Form delegate that let the user select a file.
FormFolderDelegate: A Form delegate that let the user select a folder.
FormGridContainer: This component render a grid of small cards.
FormHeader: A header item for a form card.
FormIconDelegate: A FormCard delegate for icons.
FormLinkDelegate: A form delegate that contains a URL.
FormPasswordFieldDelegate: A Form delegate that corresponds to a password field.
FormPlaceholderMessageDelegate: A placeholder message indicating that a FormCard is empty.
FormRadioDelegate: A Form delegate that corresponds to a radio button.
FormRadioSelectorDelegate: A FormCard delegate that allows switching between multiple options.
FormSectionText: A standard delegate label.
FormSliderDelegate: A form delegate for selecting a value with a slider.
FormSpinBoxDelegate: A Form delegate that corresponds to a spinbox.
FormSwitchDelegate: A Form delegate that corresponds to a switch.
FormTextAreaDelegate: A Form delegate that corresponds to a text area.
FormTextDelegate: A Form delegate that corresponds to a text label and a description.
FormTextFieldDelegate: A Form delegate that corresponds to a text field.

Kirigami Addons FormCard QML Types

#Organizing a form

#Creating a custom delegate

#Using delegates in a dialog

#Contents

Organizing a form

Creating a custom delegate

Using delegates in a dialog

Contents