TimeInput class

Optimized Time Input Text Field Component

A specialized text input widget for time entry that provides intuitive user experience with smart cursor positioning, automatic formatting, and robust focus management.

Key Features:

Smart Cursor Positioning: Always places cursor where user taps, even after focus changes
Dual Text Modes: Displays formatted time (HH:MM z/L) when unfocused, digits-only when focused
Automatic Formatting: Converts user input to proper time format on focus loss
Keyboard Navigation: Supports Enter (submit) and Escape (revert) keys
Input Validation: Real-time validation with helpful error messages
Performance Optimized: Uses cached regex patterns and efficient character code checks
Timezone Display: Shows 'z' for UTC, 'L' for local (optional), or no suffix by default

Usage:

TimeInput(
  title: "Start Time",
  time: DateTime.now(),
  onSubmitted: (timeOfDay) => print("Selected: $timeOfDay"),
  onChanged: (timeOfDay) => print("Changed: $timeOfDay"), // Optional
  autoFocus: true, // Optional
  isUtc: false, // Use local time
  showLocalIndicator: true, // Show 'L' for local time
)

Behavior:

On Focus: Shows digits-only text (e.g., "1030" for 10:30)
On Blur: Shows formatted text (e.g., "10:30 z" for UTC, "10:30 ʟ" or "10:30" for local)
On Tap: Positions cursor at equivalent position in digits-only text
On Enter: Formats current input and submits
On Escape: Reverts to original value and submits

Technical Improvements:

Enhanced cursor handling with proper position management
Custom TextInputFormatter for consistent input formatting
Reduced redundant formatting calls with cached regex patterns
Simplified state management with efficient focus tracking
Better focus event handling and cursor positioning
Optimized performance with static regex patterns and character code checks
Cleaner separation of concerns between input and display formatting

Inheritance

Available extensions

GenericExtensions

Constructors

TimeInput({required String title, required dynamic onSubmitted(TimeOfDay? time), Key? key, DateTime? time, TimeOfDay? defaultTime, bool isUtc = true, bool autoFocus = false, bool replaceAllTextOnAutoFocus = false, dynamic onChanged(TimeOfDay? time)?, InputDecoration? inputDecoration, Map<String, Color>? colorPerTitle, EdgeInsetsGeometry? contentPadding, double? inputFontSize, double? borderRadius, bool isEmptyWhenTimeNull = false, bool showClearButton = false, String? focusRole, bool showLocalIndicator = false, bool enableDebugLogs = false}): const

Properties

autoFocus → bool: Whether the input should automatically gain focus when widget is created
final
borderRadius → double?: Optional border radius for the input field
final
colorPerTitle → Map<String, Color>?: Optional color mapping for title styling based on title text
final
contentPadding → EdgeInsetsGeometry?: Optional content padding for the input field
final
defaultTime → TimeOfDay?: final
enableDebugLogs → bool: Enables verbose internal debug logs (focus transitions, text changes, formatter traces).
final
focusRole → String?: Optional role string used to tag the internal FocusNode for traversal policies.
final
hashCode → int: The hash code for this object.
no setterinherited
inputDecoration → InputDecoration?: Custom input decoration (uses default styling if null)
final
inputFontSize → double?: Optional font size for the input field label
final
isEmptyWhenTimeNull → bool: final
isUtc → bool: Whether the input should automatically gain focus when widget is created
final
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
onChanged → dynamic Function(TimeOfDay? time)?: Optional callback triggered during text changes while focused Useful for real-time validation or preview
final
onSubmitted → dynamic Function(TimeOfDay? time): Callback triggered when time input is submitted (Enter key or focus loss) Called with the parsed TimeOfDay or null if invalid
final
replaceAllTextOnAutoFocus → bool: Whether the input should automatically gain focus when widget is created
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
showClearButton → bool: final
showLocalIndicator → bool: Whether to show 'ʟ' (small capital L) indicator for local time when isUtc is false If false (default), local time is displayed without suffix (e.g., "12:56") If true, local time is displayed with 'ʟ' suffix (e.g., "12:56 ʟ") UTC time always shows 'z' suffix regardless of this setting
final
time → DateTime?: Initial time value to display (defaults to current time if null)
final
title → String: The label text displayed above the input field
final

Methods

addMaterialWidget() → Material: Available on Widget, provided by the GenericExtensions extension
addTooltipWidget(String toolTip) → Tooltip: Available on Widget, provided by the GenericExtensions extension
borderRadius([BorderRadiusGeometry? borderRadius]) → Widget: Available on Widget, provided by the GenericExtensions extension
boxDecoration([BoxDecoration? boxDecoration]) → Widget: Available on Widget, provided by the GenericExtensions extension
colorFilter([ColorFilter? colorFilter]) → Widget: Available on Widget, provided by the GenericExtensions extension
set parent widget in center
createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<TimeInput>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited