AtlasForm

A form of Sections and AtlasFormEntry rows that knows when it is valid, shows every error with validate() and gives its entries the settings they save to.

Since 1.5.0

An AtlasForm holds Sections of AtlasFormEntry rows. It is a Qt Quick Layouts ColumnLayout, so anything else can sit beside the Sections (a button row, an InfoBanner). The form does not draw anything of its own: it collects its entries (they register when they are created and leave when they are destroyed) and answers for all of them. A page of an AtlasPreferencesDialog is an AtlasForm.

Example

AtlasForm {
    id: form
    settings: AtlasSettings { group: "Account" }
    onAccepted: save()

    Section {
        title: qsTr("Account")
        AtlasFormEntry {
            label: qsTr("Name")
            required: true
            settingKey: "Name"
            AtlasTextField { }
        }
        AtlasFormEntry {
            label: qsTr("Email")
            AtlasTextField { validator: AtlasEmailValidator { } }
        }
    }
    PrimaryButton {
        text: qsTr("Save")
        enabled: form.valid
        onClicked: save()
    }
}

Bind a primary button to enabled: form.valid, or leave it enabled and call form.validate() when it is clicked: validate() shows what is wrong and moves the focus there.

Properties

Name	Type	Default	Description
`entries`	`var` (read-only)	`[]`	The entries inside, as an array, in reading order (their order in the item tree).
`settings`	`AtlasSettings`	`null`	Where the entries with a `settingKey` save. On a page of an AtlasPreferencesDialog the dialog's `settings` are used when the page has none.
`valid`	`bool` (read-only)	—	True when every entry is valid. An entry that is disabled or hidden by the app counts as valid, and `validate()` never focuses it; one on a page that is not shown still counts.

Signals

Name	Description
`accepted()`	Return was pressed in a single-line field while the form is valid. When the form is not valid Return does what `validate()` does.

Methods

Signature	Description
`validate()`	Shows the error of every entry (not only those the user has left), moves the keyboard focus to the first invalid entry in reading order and returns `valid`.

Accessibility

The form adds no accessible item. Each entry gives its control an accessible name (its label) and description (its help and error); see AtlasFormEntry.