The forms skill
forms reads the form the user is working on and fills it. It is four actions:
| Action | Asks first | What it does |
|---|---|---|
describe_form | no | Describes every field: id, label, type, rules, current value, full description; then the pages and the lists of the form |
fill_form | yes | Writes the values the model chose, starting the insert or the edit of the record when the form edits one, and reports field by field |
find_choice | no | Searches the values a choice or a reference accepts, by part of their description |
cancel_edit | yes | Abandons what was not saved: the record goes back as it was, the fields the assistant filled get their previous values back |
The model always describes before filling - the description of fill_form tells it to, and it needs the ids - so a request becomes two steps: look, then write.
Looking: which controls are fields
The skill walks the form in tab order, which is the order the form is filled in, and keeps the controls that are visible and enabled, together with every parent: a disabled panel disables what it holds, a tab that is not shown hides its fields. The chat itself is left out, when it sits in a container of the same form.
A control is a field when a LiveBindings link binds it to a field, or when an adapter accepts it. The link comes first, as in FireMonkey; then the built-in adapters, asked from the most specific:
| Control | Field |
|---|---|
any control a TLinkControlToField binds to a field of a TBindSourceDB | the TField behind it - a check box as yes/no, a combo box as a choice among its items |
a combo a TLinkFillControlToField fills from another data set | a reference: FillValueFieldName is the code, FillDisplayFieldName the description, and the code goes to the field of the link |
any control with a published DataSource and DataField (TDBEdit, TDBMemo, TDBComboBox, TDBCheckBox, TDBRadioGroup, TDBLookupComboBox, and the third-party ones with the same properties) | the TField behind it |
TDateTimePicker | a date, or a time when its Kind is dtkTime; empty when it shows a check box and it is unchecked |
| radio buttons on the same parent | one field, a choice among their captions; a group box gives it its name and its id |
TRadioGroup | a choice among its items |
TCheckBox | yes/no |
TComboBox | a choice among its items - only those for a drop-down list, any text for an editable one |
TEdit, TMemo, TMaskEdit, TLabeledEdit, TSpinEdit, TNumberBox... | text, multi-line text, or a number when the control publishes a numeric Value |
In FireMonkey a field is read through LiveBindings when a link binds it, and through an adapter otherwise:
| Control | Field |
|---|---|
any control a TLinkControlToField binds to a field of a TBindSourceDB | the TField behind it - a check box or a switch as yes/no, a combo box as a choice among its items |
a combo a TLinkFillControlToField fills from another data set | a reference: FillValueFieldName is the code, FillDisplayFieldName the description, and the code goes to the field of the link |
TDateEdit, TTimeEdit | a date or a time; empty when IsEmpty, or unchecked with a check box |
radio buttons with the same GroupName (or, with none, on the same parent) | one field; a group box gives it its name and its id |
TCheckBox, TSwitch | yes/no |
TComboBox | a choice among its items |
TComboEdit | its items, or any text |
TMemo | multi-line text |
TEdit, TNumberBox, TSpinBox | text, or a number - integer or decimal as its ValueType says |
The links are read by their published properties, the same way in the VCL and in FireMonkey, so the library needs none of the LiveBindings units. An application adds its own kind of control with RegisterHelpChatVclFieldAdapter or RegisterHelpChatFmxFieldAdapter (skills).
Looking: what each field is called
The id is the name of the control (edFirstName): it is what the model writes back. The label is what the user reads, and the skill looks for it in the words of the screen first:
- the label whose
FocusControlis the control - the way a Delphi form says "this label is about that edit", and whatTLabeledEditdoes by itself (the FireMonkeyTLabelhas aFocusControltoo); - the caption of the control itself: a check box, a radio group, the group box of a set of radio buttons;
- the
DisplayLabelof its field, for a data-aware control; - the nearest label on its left, on the same row, or just above it;
- its text hint (the grey text of an empty edit:
TextHint,TextPromptin FireMonkey); - its name, when nothing else says anything.
Hot-key marks and a trailing colon go (&First name: reads First name). A trailing asterisk goes too, and marks the field required - the usual sign on a form.
The description is the hint of the control, the long part when it has two. This is where a developer says what the label cannot: "the VAT number, eleven digits, without the country prefix". The model follows it to the letter, so a good hint is the cheapest way to better filling.
Looking: type and rules
| Kind | What the model is told |
|---|---|
| text | text, max 40 characters - the MaxLength of an edit, the Size of a string field |
| memo | multi-line text |
| integer, number | integer number, decimal number (use "." as decimal separator) |
| date, date and time, time | date (YYYY-MM-DD), date and time (YYYY-MM-DD HH:MM), time (HH:MM) |
| yes/no | yes/no (true or false) |
| choice | one of: "Small", "Large" - and (other values allowed) for an editable combo box |
| reference | reference to a record of "Regions": give its code or its exact description, with the values when they are thirty or fewer |
The flags are required (the field is, or its label has an asterisk), read-only (the control, the field, a calculated field, a data set that cannot be modified), KEY (the field is part of the key) and secret - a password, whose value is never read.
A data-aware control says more than a plain one, because its TField knows: the type, the size, Required, ReadOnly. For a reference - a lookup field, or a lookup control such as TDBLookupComboBox on a plain field - the skill reads where the records are (LookupDataSet, or the ListSource of the control), which field is the code and which the description, and which field the code is written to.
What describe_form returns
Form: Customer (TCustomerForm)
State of Customers: browsing the record shown.
Fields (id | label | type | flags | current value), then the full description:
- edCode | Code | text, max 10 characters | KEY: the code that identifies the record, required | "C1"
- edCompany | Company | text, max 40 characters | required | "Acme"
The name as printed on the invoices.
- cbRegion | Region | reference to a record of "Regions": give its code or its exact description; one of: "1 = Lombardia", "2 = Piemonte", "3 = Liguria" | optional | "1 (Lombardia)"
- chkActive | Active | yes/no (true or false) | optional | "true"
Pages: "General" (shown), "Addresses", "Notes". Only the fields of the pages shown are listed: show_page shows another one.
Lists: grdCustomers (Customers: 120 record(s)).
When the user gives values without naming the fields, they follow the order of the fields above.
fill_form fills them: it asks the user to confirm the values and never saves - the user reviews and saves.The State line is what decides how filling starts; Pages and Lists tell the model what show_page and find_record can reach. A form of plain controls says so instead: plain fields, no record: what is written stays on the screen until the user confirms it.
Writing: the mode
When the fields belong to a record - data-aware controls - fill_form makes the record editable first, as the user would with the Insert or Edit button. The model chooses the mode from the words of the user:
| The user says | Mode | What happens |
|---|---|---|
| "insert", "add", "create", "new..." | insert | a new record (Insert); a new record already being inserted is filled |
| "modify", "change", "correct..." | edit | the record shown goes into edit (Edit) |
| "fill", "complete..." | current | the form as it is: already editing, or put in edit (or in insert, when it is empty) because its data source has AutoEdit |
And it refuses what would save behind the user's back: asked to insert while an existing record is being edited, it stops - Insert would post that record - and says the user saves it first, or cancel_edit abandons it. With AutoEdit off and mode current it says which mode to use instead of choosing. A data set that is not open, or cannot be modified, is reported the same way.
Plain controls have no record: the mode does not matter, the values go to the controls.
Writing: the values
Before anything is written the user confirms, in the confirmation dialog of the component, with the values under the labels of the form:
The assistant wants to fill these fields of "Customer". Nothing is saved:
you review the values and save.
Company: Bianchi Srl
Region: Liguria
Active: yesThen each value is read for its field:
- a text is trimmed and checked against the maximum length; a memo keeps its line breaks;
- a number is read with a point first, then in the format of the machine;
- a date is read as ISO first (
2026-10-19,2026-10-19 14:30), then in the format of the machine; - yes/no takes true/false, yes/no, sì/no, ja/nein, oui/non, 1/0;
- a choice takes the same text (case apart), else the only choice starting with it, else - for a fixed list - its position;
- a reference takes the code, else the exact description, else the only description that contains the text; when several match it lists them and asks the model to let the user choose, and when none does it points to
find_choice; - an empty string clears the field.
A plain control is written the way the user would change it, so the form hears of it: an edit fires its OnChange, a check box and a radio group their OnClick, a combo box its OnSelect (or OnChange), a date picker its OnChange. A data-aware control is written through its TField, so the validation of the field runs and its error, if any, is the reason given.
Writing: the report
Customer: 2 field(s) set, 1 not set. Nothing was saved: the form is inserting a new record,
not saved yet; the user reviews the values and saves (cancel_edit abandons them).
- Company (edCompany): set to Bianchi Srl
- Region (cbRegion): set to 3 (Liguria)
- Code (edCode): NOT set, too long: 14 characters, the maximum is 10
Required fields still empty: Code (edCode).The model reads every refusal with its reason and can correct itself, or ask the user, in the next step. The caret goes to the first field that was refused, else to the first one filled - where the user has something to look at.
find_choice
A reference with hundreds of records cannot be listed in a description. When the user says "the customer Rossi" and fill_form finds two, the model calls find_choice(field, text), reads the codes and descriptions that contain the text, asks the user which one, and fills the field with that code. For a choice field it lists the choices that contain the text.
cancel_edit
"No, leave it" is cancel_edit, which asks first: every data set of the form in insert or edit is cancelled - a new record disappears, an edited one goes back to what it was - and the plain controls the assistant filled get back the values they had before its first fill_form on that form. What the user typed by hand on plain controls is not touched.