Dialog Boxes: Forms, Fields, and Native File Pickers

A small window titled Sign in appears with one text field labelled Name: and a Done button. (Done is the default label of a submit button; set value="Sign in" on the <input type=submit> to change it.) Type Ada, click Done, and the program prints:

Under the hood the answer is the field's name, an =, and what was typed — user=Ada — with every field ended by a single separator byte, chr$(26). between$(answer$, 'user=', chr$(26)) pulls one field's value out by its name: everything from user= up to that separator. That name=value shape is the whole convention — every control reports back under its name, and section 3 shows how to read several of them at once.

Identical result, far easier to edit. Use %text trim so the indentation that keeps your source tidy does not end up inside the string. Every example from here on could be written either way; the shape is what matters.

Entering Ada and Lovelace prints:

Each field is ended by chr$(26) — the submit button's own SUBMIT= pair included — so a field is readable by name wherever it sits in the answer, first, last, or only. A field left empty returns "". Closing the window instead of submitting returns an empty answer, so test answer$ = '' when a cancel matters. When you do not know the field names ahead of time, walk the pairs instead with elements(answer$, chr$(26)) and element$(answer$, n, chr$(26)), splitting each on its first = and skipping the empty final piece.

What each control reports under its name:

checked on a checkbox or a radio button makes it start selected; selected does the same for an <option>. rows and cols size a textarea. A <select> with size greater than one, or with multiple, is drawn as a list box instead of a dropdown.

The window opens 420 by 260 pixels on a pale ground, titled Preferences, with an <h2> heading above the field. The full set of window options — always-on-top, no-resize, a timed auto-submit, loading the body from a URL, and more — is in the reference.

Submit with the email blank and the dialog refuses and points at the empty field; type letters into Age and it refuses that too. Only a form that passes every rule closes and returns its answer, so the code after line input dialogbox can trust what it receives.

The window opens with First already holding Ada, Last holding Lovelace, and the M radio selected — each field matched to the seed by its name (a checkbox takes 1/0; a radio or select takes the option's value). Because the seed and the answer share one format, the edit-in-place idiom is a single line: show a form, take its answer, and pass that answer back as the default the next time.

The native Open dialog appears with its type box set to Sheerpower source (*.spsrc; *.spinc), so only those files are listed. Pick one and path$ holds its full path; press Cancel and path$ is empty. This is the right way to ask for a file — it uses the same chooser every other program on the machine uses, with no UI to build. The filter is written name=pattern — several patterns separated by commas, several named filters by semicolons; add , default start_dir$ after the definition to open in a particular folder.

onchange="submit" on a field submits the form the moment that field changes; onclick="submit" does it when the control is clicked. Handy for a menu-like dropdown that acts on the pick with no separate button:

Only "submit" is understood by these two. To submit after a period of inactivity instead, put autosubmit= seconds on the <sheerpower> element — the form returns on its own when the time is up, exactly as if the person had clicked the button:

call="routine_name" on an <input> runs one of your routines each time that field loses focus — live, per-field checking while the form is still open (the routine name needs an underscore, as all routine names do).

Use call when a rule is too involved for a valid word — a check against a database, say — and you want the answer before the person moves on.

<input type=image src="..."> uses a picture as the submit button. Point src at a bitmap; filespec$('@name') resolves a file that sits next to the program:

Clicking the image submits the form and also reports where it was clicked, as go.X= and go.Y= pairs in the answer — an image map, when the spot on the picture matters.

<a href="..."> draws its text as a link inside the dialog — a place to point the person at help or a web page without leaving the form.

Both headings carry a sort diamond. Click Player and the four rows re-order alphabetically; click Score and they re-order by number. The first click on a column sorts ascending, clicking the same heading again flips to descending, and clicking the other heading switches to sorting by that column. Only headings you mark <th sort> are clickable — leave sort off to keep a column fixed.

Sorting re-sequences the entire table, so each row's cells travel together, and it is purely a convenience for the person reading it — it does not change what the form returns on submit. For the full table and cell attributes, see Dialog Box Reference: Every Tag and Attribute.