TimeSpanPicker
A TimeSpanPicker is a BaseField<TimeSpan> for durations: one number segment per unit, a unit letter or a separator after each segment, and the NumericUpDown buttons.
<UIToolbox.TimeSpanPicker label="Task" value="01:30:45" />
<UIToolbox.TimeSpanPicker label="Trip" format="DaysHoursMinutes" value="2.04:00:00" max-value="30.00:00:00" />
<UIToolbox.TimeSpanPicker label="Timer" format="HoursMinutes" min-value="00:15:00" max-value="08:00:00" show-labels="false" />
<UIToolbox.TimeSpanPicker label="Sprint" units="Weeks Days" value="14.00:00:00" />
<UIToolbox.TimeSpanPicker label="Cook" format="HoursMinutes" input-mode="Text" value="00:45:00" />
<UIToolbox.TimeSpanPicker label="Slot" format="HoursMinutes" steps="Minutes:15" unit-letters="Hours:Std Minutes:Min" />
| Member | Description |
|---|---|
value |
The duration. Listen with RegisterValueChangedCallback. |
Format (format) |
The units: HoursMinutesSeconds (the default), HoursMinutes, MinutesSeconds, DaysHoursMinutes or DaysHoursMinutesSeconds. The value loses the parts smaller than the smallest unit. A set of Format also sets Units. |
Units (units) |
Any set of TimeSpanUnit values: Weeks, Days, Hours, Minutes, Seconds and Milliseconds. The picker removes duplicates and shows the units from the largest to the smallest. An empty set throws ArgumentException. The UXML attribute takes the names, separated by spaces or commas, in any case; it ignores an unknown name. Set format or units, not both. |
InputMode (input-mode) |
Segments (the default): one number field per unit. Text: one text field that shows the whole duration and takes typing. |
TextInput |
The TextField of the Text mode. |
TryParseText(text, out span) |
Reads a duration in the text forms below. Returns false for other text. |
ValueText, MinValueText, MaxValueText (value, min-value, max-value) |
The value and the limits in the .NET "c" format, [d.]hh:mm:ss. "05:30" is 5 hours 30 minutes; 365 days is "365.00:00:00". |
MinValue, MaxValue |
The limits. The minimum is zero or more: the picker shows no negative durations. |
ShowLabels (show-labels) |
Unit letters (w, d, h, m, s, ms by default) after the segments (true), or "." after the days and before the milliseconds and ":" between the other segments. |
GetUnitLetter(unit), SetUnitLetter(unit, letter) (unit-letters) |
The letter of a unit in the segments and in the text, such as "Std" for hours. The Text mode reads the letters that the picker shows, in any case, and not the default ones. A letter must not be empty or have digits, spaces, ":" or "."; two units cannot have the same letter (the case is ignored). SetUnitLetter throws ArgumentException for a bad letter. The UXML attribute takes "Unit:letter" pairs, such as unit-letters="Hours:Std Minutes:Min", and ignores a bad pair. |
GetStep(unit), SetStep(unit, count) (steps) |
How many of a unit one step adds, such as 15 minutes. The default is 1. SetStep throws ArgumentOutOfRangeException for a count under 1. The UXML attribute takes "Unit:count" pairs, such as steps="Minutes:15 Seconds:5", and ignores a bad pair. |
SnapToStep (snap-to-step) |
False: a step adds its count. True: a step goes to the next multiple of the step in its direction, so a 15-minute step gives 0, 15, 30 and 45 only. |
Validate |
Returns false for a duration that the user cannot type or step to. The picker keeps the old value. A code set of value skips it. |
Increment(unit), Decrement(unit), ActiveUnit |
Steps one step of the unit (see SetStep), as the keys do, and the unit that the buttons step. |
SegmentField(unit) |
The LongField of a unit, or null when the format does not show it. |
- The largest unit has no upper limit:
HoursMinutesshows 36 hours as 36 and 0. - A typed number carries into the larger units: 90 in the minutes gives 1 hour 30 minutes. A segment commits on Enter or when it loses focus.
- Up and Down (the arrow keys or the gamepad), the mouse wheel (while a segment has focus) and the buttons step the unit of the last focused segment. A step carries: 59 seconds plus one second is 1 minute. A step past a limit stops at the limit.
- The segment's own change event stops in the picker. The picker sends one
ChangeEvent<TimeSpan>per change. - UXML durations are strings, for the same reason as the dates of
DatePicker. - A week is 7 days.
Weeks Daysshows 16 days as 2 and 2. - The
Textmode shows "1h 30m 5s" withShowLabels, or "1:30:05" without. It reads two forms, and commits on Enter or when it loses focus:- Numbers with unit letters, in any order, with decimals: "1.5h", "2h 15m", "90s", "1m 250ms". A unit that the picker does not show carries into the others.
- Whole numbers with ":" or ".": "1:30" puts the last number in the smallest unit and the others in the larger units, from the right. More numbers than units is an error.
- Text that the picker cannot read, or a refused value, shows the old value again.
- In the
Textmode, Up and Down, the wheel and the buttons step the unit under the caret. The step commits the typed text first, so one key press can send two change events. The picker selects the stepped number after the step. - A step of more than 1 adds the count: with a 15-minute step, 0:07 steps to 0:22. With
snap-to-step, 0:07 steps up to 0:15 and down to 0:00, and a value on a multiple adds the step. The multiples count from zero over the whole duration, so a 7-minute step gives 1:03 after 0:56, not 1:07. A step past a limit stops at the limit. - The ":" form takes whole numbers only; use a unit letter for a decimal.
Styling
| Class | Element |
|---|---|
tb-time-span-picker |
The field. |
tb-time-span-picker__segment |
The number field of a unit (42 px wide, right-aligned). |
tb-time-span-picker__unit |
A unit letter after a segment (muted). |
tb-time-span-picker__separator |
The "." or ":" between segments when ShowLabels is false (muted). |
tb-time-span-picker__text |
The text field of the Text input mode (grows, 96 px or more). |
tb-time-span-picker__spinner |
The up and down buttons. They also have the tb-numeric-up-down__spinner, __up and __down classes, and the NumericUpDown rules style them. |