AtlasFormEntry

An AtlasFormEntry is one row in a Section of an AtlasForm: the label (and help under it) on the leading side, the control on the trailing side. The control is the one item declared inside the entry; any Atlas.Ui control works, and so does a plain Item. In a narrow row (less than 22 grid units), for a tall control (a text area), and for a control too wide to fit beside the label, the control goes under the label (stacked).

An entry is valid when it has no errorText, is not required and empty, and its control's acceptableInput is not false (the Atlas validators and TextField.validator set it; an optional field that is empty is never unacceptable). The error shows under the row, with an error symbol, and the control gets a red outline (a control that draws its own error, such as AtlasTextField, keeps its own):

• the app's errorText shows at once, as AtlasTextField.errorText does;
• the requiredText and invalidText errors show only after the user has left the control once (focus moving to something else; a combo box's open list is not leaving), or after AtlasForm.validate(). After that they follow the control live and go as soon as it is fine.

Each error is announced with Accessible.announce() when it appears. Clicking the label focuses the control.

The entry gives the control its accessible name (label; the control's own name stays when the label is empty) and description (help, then the error shown). Empty means: no text, not checked, index -1, no path, no shortcut. A colour is never empty.

Example

AtlasFormEntry {
    label: qsTr("Port")
    help: qsTr("1 to 65535")
    required: true
    settingKey: "Port"
    AtlasSpinBox { from: 1; to: 65535 }
}

Properties

Settings that save themselves

With a settingKey the control takes the stored value when the entry is created (the control's own value is the default when the key is missing) and every user edit is written with AtlasSettings.setValue(). The edit is detected with the control's own edit signal. A change of the key made by another writer (AtlasSettings.changed(key)) updates the control.

Only a valid value is saved: while the entry is invalid (an unacceptable text, a required control that is empty) an edit is not written. A string over 64 KiB is not saved (one warning), and a stored string over 64 KiB is ignored, so a huge paste cannot make the settings file unreadable. A key that AtlasSettings would refuse (brackets, =, a leading # or ;, control characters, over 200 characters) warns once and is ignored. A stored shortcut is read back through its portable form. A loaded path is untrusted text: validate it before use.

A stored value that does not fit the property (text for a switch) is ignored with a warning that names the key. A password is never loaded or saved, whatever settingProperty says: the control, or anything inside it (a field in a wrapper Item), counts as a password when it is an AtlasPasswordField, hides what is typed (echoMode other than Normal), sets Qt.ImhSensitiveData or reports Accessible.passwordEdit. One warning names the key. A field switched to a password later may already have saved what was typed before. An entry with a settingKey and no settings (the form has none, and it is not on a page of a dialog that has) warns.

Keyboard

The entry takes no Tab stop; the control inside does. Return in a single-line field emits AtlasForm.accepted() while the form is valid.

Accessibility

The control has the accessible name label and the description help followed by the error shown. Errors are announced when they appear.