Time input behavior

Time input behavior#

This document states the behavior a time-of-day input must have. The Go Fyne TimeEntry widget implements it. The same rules apply to any other front end that edits a time field.

The problem#

A time-of-day field holds an exact value, such as 19:00. A person types a loose form, such as 7, 7:30, 7pm, or 07.30. A bare hour has two readings. The input must guess which one the person means. The guess is helpful, and it is also a guess. The input must never let a guess overwrite what the person typed.

Rules#

  1. Accept every keystroke. The input holds any text, including text that is not a time.

  2. Show a validation error for text that does not parse. Do not reject the keystroke, and do not replace the text.

  3. Keep the text exactly as typed while the input has focus.

  4. Write each parseable edit through to the model as the person types.

  5. Keep the last good value in the model when an edit does not parse. The bad text stays in the input, with the error against it.

  6. When focus leaves the input, write the reading back as text in one canonical form. 7pm becomes 7:00 PM.

  7. When focus leaves the input and the text does not parse, keep the text and keep the error.

  8. When the input is empty and focus leaves it, show the value from the model. An optional field stays empty and means unset.

Reading a bare hour#

Two layers pick between the morning reading and the evening reading.

  1. A window, which the model declares per field. A field with a 09:00 to 21:00 window reads 7 as 7:00 PM and 10 as 10:00 AM.

  2. A bias, which the form sets at run time. An end-of-span field takes a bias of “after the start time”.

A zero-padded hour is a 24-hour value, so 07 is always 7:00 AM. An explicit am or pm marker is always exact. The canonical form carries a marker, so canonical text has one reading only.

Scope of a bias#

A bias steers the next edit. It does not reach back.

The input keeps the bias that read the current text. The reading stays pinned to that bias. A new bias applies to the next keystroke in that input. The value in the model does not move, the text does not change, and the reading the input reports does not change.

This matters for a chained run of inputs, such as a start and an end. A change in the start sets a new bias on the end. The end keeps its value, because the person is not typing in it. Only the input under the cursor changes value.

The natural typing order still reads in step. A person types 7 in the start and then 9 in the end. The start reads 7:00 PM. The end reads 9:00 PM, because the bias was already in place when the person typed it.

Why the input reports its reading#

The input exposes its reading next to the text through Resolved, Display, and the OnResolved callback. A form can echo the reading, such as starts 7:00 PM. This makes the guess visible before a save.

The reading always agrees with the value in the model. The text, the model, and the echo state the same time.