Kirigami Addons FormCard QML Types

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 QtQuick.Controls as Controls
 import org.kde.kirigamiaddons.formcard as FormCard

 FormCard.FormCardDialog {
     id: dialog

     signal profileCreated(string name)

     title: i18nc("@title:window", "Create Profile")
     standardButtons: Controls.Dialog.Ok | Controls.Dialog.Cancel

     FormCard.FormTextFieldDelegate {
         id: nameField
         label: i18nc("@label:textbox", "Profile name")
     }

     FormCard.FormDelegateSeparator {}

     FormCard.FormSwitchDelegate {
         text: i18nc("@option:check", "Use as default")
     }

     onAccepted: profileCreated(nameField.text)
 }

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