Distance Display Formatting

Distance Display Formatting#

The Distance Resolution preference controls whether workout distances are shown in small units (meters/yards — "high resolution") or large units (km/miles — "low resolution") across the app UI. It is a pure display setting with no effect on the underlying distance values stored in the database.

Preference Definition#

Defined in lib/preferences/distance_resolution.dart:

Constant	Value
`distanceResolution`	`"Distance Resolution High/Low"` (display label)
`distanceResolutionTag`	`"distance_resolution"` (pref key)
`distanceResolutionDefault`	`false` (low resolution — km/mi — by default)
`distanceResolutionDescription`	`"On: high resolution - m or yd, Off: low resolution - km or mi."`

The default is false (low resolution), meaning users see km/mi unless they explicitly toggle the setting on .

Settings UI#

The preference is exposed as a PrefCheckbox in the User Experience Preferences screen (lib/ui/preferences/user_experience_preferences.dart), directly below the metric/imperial (SI) unit toggle.

It is initialized at startup in lib/utils/init_preferences.dart as part of the getPrefDefaults() map.

Display Logic#

Three functions in lib/utils/display.dart implement the formatting. All accept a bool si (metric vs. imperial) and bool highRes (distance resolution preference):

distanceString(distance, si, highRes) — formats the numeric value:
- si + highRes → integer meters (toStringAsFixed(0))
- si + !highRes → km to 2 decimal places (distance / 1000)
- !si + highRes → yards (distance * m2yard)
- !si + !highRes → miles (distance * m2mile)
distanceUnit(si, highRes) — returns the unit label ("m", "km", "yd", or "mi").
distanceByUnit(distance, si, highRes, {autoRes}) — combines value + unit into a single string. When autoRes: true, it auto-selects resolution based on magnitude: switches to high-res below 999 m (SI) or ~914 m (imperial, i.e., 1000 yd), overriding the user preference for small lap distances.

Screens That Consume `highRes`#

Each screen reads the preference in initState() and passes it as _highRes to the display functions. No live observation is wired — the value is captured once on screen load.

Screen	File	Usage
Activity list	`lib/ui/activities.dart`	`distanceString(_si, _highRes)` + `distanceUnit` in list rows
Activity details	`lib/ui/details/activity_details.dart`	`distanceString` + `distanceUnit` in the stats header
Recording screen	`lib/ui/recording/recording_screen.dart`	live measurement rows + leaderboard lap info via `distanceByUnit(..., autoRes: true)`
Sport leaderboard	`lib/ui/leaderboards/sport_leaderboard.dart`	`distanceStringWithUnit(_si, _highRes)` in workout summaries
Device leaderboard	`lib/ui/leaderboards/device_leaderboard.dart`	`distanceStringWithUnit(_si, _highRes)` in workout summaries

Key Design Notes#

Orthogonal to SI/imperial. The si flag (from unitSystemTag) controls which unit system (metric vs. imperial); highRes controls which magnitude within that system. Both flags are always passed together.
No recalculation. The raw distance value (stored in meters) is never changed — only the formatted string varies.
autoRes override. The recording screen uses autoRes: true for lap/leaderboard delta distances, so very short segments automatically show in m/yd regardless of the user setting .
Default is low-res (km/mi). Engineers adding new distance display calls should default to distanceResolutionDefault = false and read distanceResolutionTag from the preference service for consistency.