Skip to content

Commit fabacd6

Browse files
Prasad  Navalevictorsanni
andauthored
Add PlatformDispatcher.onAlwaysUse24HourFormatChanged callback (flutter#194670)
Part of flutter#194637 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] All existing and new tests are passing. ## Description This PR introduces the engine API foundation for tracking platform 24-hour time format changes at runtime (split from the original full-stack PR per review feedback). ### Changes 1. **`dart:ui.PlatformDispatcher`**: - Added `onAlwaysUse24HourFormatChanged` callback getter, setter, and zone tracking. - Updated `_updateUserSettingsData` to invoke `onAlwaysUse24HourFormatChanged` whenever `alwaysUse24HourFormat` changes. - Added documentation comments to `alwaysUse24HourFormat` referencing the new callback. 2. **Web Engine (`lib/web_ui`)**: - Added `onAlwaysUse24HourFormatChanged` to `PlatformDispatcher` interface and `EnginePlatformDispatcher` implementation. - Implemented `invokeOnAlwaysUse24HourFormatChanged()` with zone preservation. - Added unit tests in `platform_dispatcher_test.dart` verifying callback invocation and zone preservation with per-test isolated dispatcher. 3. **Framework Debug Overrides (`packages/flutter`)**: - Updated `_debugNotifyViewMetricsOverrideChanged` in `debug.dart` to forward `onAlwaysUse24HourFormatChanged`. - Updated comments in `debug.dart` to reflect that `alwaysUse24HourFormat` now announces through `onAlwaysUse24HourFormatChanged`. - Updated `_DebugViewMetricsPlatformDispatcher` and tests in `debug_view_metrics_override_test.dart`. 4. **Engine Unit Tests**: - Added unit test in `engine/src/flutter/lib/ui/fixtures/ui_test.dart` verifying that `onAlwaysUse24HourFormatChanged` is invoked only when `alwaysUse24HourFormat` changes, and remains unaffected by unrelated settings. Cleaned up dispatcher callback at test completion. *Note: Framework layer integration (`WidgetsBindingObserver.didChangeAlwaysUse24HourFormat` and `MediaQuery` updates) will follow in Part 2 once this engine API lands.* [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests --------- Co-authored-by: Victor Sanni <[email protected]>
1 parent fedbcd8 commit fabacd6

8 files changed

Lines changed: 178 additions & 15 deletions

File tree

‎engine/src/flutter/lib/ui/fixtures/ui_test.dart‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1514,8 +1514,10 @@ void hooksTests() async {
15141514
late Zone innerZone;
15151515
late Zone runZoneTextScaleFactor;
15161516
late Zone runZonePlatformBrightness;
1517+
late Zone runZoneAlwaysUse24HourFormat;
15171518
late double? textScaleFactor;
15181519
late Brightness? platformBrightness;
1520+
late bool? alwaysUse24HourFormat;
15191521

15201522
runZoned(() {
15211523
innerZone = Zone.current;
@@ -1527,6 +1529,10 @@ void hooksTests() async {
15271529
runZonePlatformBrightness = Zone.current;
15281530
platformBrightness = window.platformBrightness;
15291531
};
1532+
PlatformDispatcher.instance.onAlwaysUse24HourFormatChanged = () {
1533+
runZoneAlwaysUse24HourFormat = Zone.current;
1534+
alwaysUse24HourFormat = PlatformDispatcher.instance.alwaysUse24HourFormat;
1535+
};
15301536
});
15311537

15321538
window.onTextScaleFactorChanged!();
@@ -1550,6 +1556,55 @@ void hooksTests() async {
15501556
);
15511557
expectIdentical(runZonePlatformBrightness, innerZone);
15521558
expectEquals(platformBrightness, Brightness.dark);
1559+
1560+
textScaleFactor = null;
1561+
platformBrightness = null;
1562+
alwaysUse24HourFormat = null;
1563+
1564+
PlatformDispatcher.instance.onAlwaysUse24HourFormatChanged!();
1565+
_callHook(
1566+
'_updateUserSettingsData',
1567+
1,
1568+
'{"textScaleFactor": 0.5, "platformBrightness": "dark", "alwaysUse24HourFormat": false}',
1569+
);
1570+
expectIdentical(runZoneAlwaysUse24HourFormat, innerZone);
1571+
expectEquals(alwaysUse24HourFormat, false);
1572+
1573+
PlatformDispatcher.instance.onAlwaysUse24HourFormatChanged = null;
1574+
});
1575+
1576+
await test('onAlwaysUse24HourFormatChanged is not invoked when unrelated user settings change', () {
1577+
int calls = 0;
1578+
final bool initialFormat = PlatformDispatcher.instance.alwaysUse24HourFormat;
1579+
PlatformDispatcher.instance.onAlwaysUse24HourFormatChanged = () {
1580+
calls++;
1581+
};
1582+
1583+
// Toggle alwaysUse24HourFormat to trigger callback once.
1584+
_callHook(
1585+
'_updateUserSettingsData',
1586+
1,
1587+
'{"textScaleFactor": 1.0, "platformBrightness": "light", "alwaysUse24HourFormat": ${!initialFormat}}',
1588+
);
1589+
expectEquals(calls, 1);
1590+
1591+
// Unrelated user setting changes (platformBrightness and textScaleFactor) without changing alwaysUse24HourFormat.
1592+
_callHook(
1593+
'_updateUserSettingsData',
1594+
1,
1595+
'{"textScaleFactor": 1.5, "platformBrightness": "dark", "alwaysUse24HourFormat": ${!initialFormat}}',
1596+
);
1597+
expectEquals(calls, 1);
1598+
1599+
// alwaysUse24HourFormat changes back.
1600+
_callHook(
1601+
'_updateUserSettingsData',
1602+
1,
1603+
'{"textScaleFactor": 1.5, "platformBrightness": "dark", "alwaysUse24HourFormat": $initialFormat}',
1604+
);
1605+
expectEquals(calls, 2);
1606+
1607+
PlatformDispatcher.instance.onAlwaysUse24HourFormatChanged = null;
15531608
});
15541609

15551610
await test('onFrameDataChanged preserves callback zone', () {

‎engine/src/flutter/lib/ui/platform_dispatcher.dart‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1142,6 +1142,9 @@ class PlatformDispatcher {
11421142
/// The setting indicating whether time should always be shown in the 24-hour
11431143
/// format.
11441144
///
1145+
/// The [onAlwaysUse24HourFormatChanged] callback is called whenever this
1146+
/// value changes.
1147+
///
11451148
/// This option is used by [showTimePicker].
11461149
bool get alwaysUse24HourFormat => _configuration.alwaysUse24HourFormat;
11471150

@@ -1297,6 +1300,23 @@ class PlatformDispatcher {
12971300
_onSystemFontFamilyChangedZone = Zone.current;
12981301
}
12991302

1303+
/// A callback that is invoked whenever [alwaysUse24HourFormat] changes value.
1304+
///
1305+
/// The framework invokes this callback in the same zone in which the callback
1306+
/// was set.
1307+
///
1308+
/// See also:
1309+
///
1310+
/// * [WidgetsBindingObserver], for a mechanism at the widgets layer to
1311+
/// observe when this callback is invoked.
1312+
VoidCallback? get onAlwaysUse24HourFormatChanged => _onAlwaysUse24HourFormatChanged;
1313+
VoidCallback? _onAlwaysUse24HourFormatChanged;
1314+
Zone _onAlwaysUse24HourFormatChangedZone = Zone.root;
1315+
set onAlwaysUse24HourFormatChanged(VoidCallback? callback) {
1316+
_onAlwaysUse24HourFormatChanged = callback;
1317+
_onAlwaysUse24HourFormatChangedZone = Zone.current;
1318+
}
1319+
13001320
// Called from the engine, via hooks.dart
13011321
void _updateUserSettingsData(String jsonData) {
13021322
final data = json.decode(jsonData) as Map<String, Object?>;
@@ -1364,6 +1384,9 @@ class PlatformDispatcher {
13641384
if (systemFontFamilyChanged) {
13651385
_invoke(onSystemFontFamilyChanged, _onSystemFontFamilyChangedZone);
13661386
}
1387+
if (alwaysUse24HourFormatChanged) {
1388+
_invoke(onAlwaysUse24HourFormatChanged, _onAlwaysUse24HourFormatChangedZone);
1389+
}
13671390
}
13681391

13691392
/// Whether the user has requested that updateSemantics be called when the

‎engine/src/flutter/lib/web_ui/lib/platform_dispatcher.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,9 @@ abstract class PlatformDispatcher {
152152
VoidCallback? get onSystemFontFamilyChanged;
153153
set onSystemFontFamilyChanged(VoidCallback? callback);
154154

155+
VoidCallback? get onAlwaysUse24HourFormatChanged;
156+
set onAlwaysUse24HourFormatChanged(VoidCallback? callback);
157+
155158
bool get semanticsEnabled;
156159

157160
VoidCallback? get onSemanticsEnabledChanged;

‎engine/src/flutter/lib/web_ui/lib/src/engine/platform_dispatcher.dart‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1063,6 +1063,9 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
10631063
/// The setting indicating whether time should always be shown in the 24-hour
10641064
/// format.
10651065
///
1066+
/// The [onAlwaysUse24HourFormatChanged] callback is called whenever this
1067+
/// value changes.
1068+
///
10661069
/// This option is used by [showTimePicker].
10671070
@override
10681071
bool get alwaysUse24HourFormat => configuration.alwaysUse24HourFormat;
@@ -1430,6 +1433,31 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
14301433
invoke(_onSystemFontFamilyChanged, _onSystemFontFamilyChangedZone);
14311434
}
14321435

1436+
/// A callback that is invoked whenever [alwaysUse24HourFormat] changes value.
1437+
///
1438+
/// The framework invokes this callback in the same zone in which the
1439+
/// callback was set.
1440+
///
1441+
/// See also:
1442+
///
1443+
/// * [WidgetsBindingObserver], for a mechanism at the widgets layer to
1444+
/// observe when this callback is invoked.
1445+
@override
1446+
ui.VoidCallback? get onAlwaysUse24HourFormatChanged => _onAlwaysUse24HourFormatChanged;
1447+
ui.VoidCallback? _onAlwaysUse24HourFormatChanged;
1448+
Zone? _onAlwaysUse24HourFormatChangedZone;
1449+
@override
1450+
set onAlwaysUse24HourFormatChanged(ui.VoidCallback? callback) {
1451+
_onAlwaysUse24HourFormatChanged = callback;
1452+
_onAlwaysUse24HourFormatChangedZone = Zone.current;
1453+
}
1454+
1455+
/// Engine code should use this method instead of the callback directly.
1456+
/// Otherwise zones won't work properly.
1457+
void invokeOnAlwaysUse24HourFormatChanged() {
1458+
invoke(_onAlwaysUse24HourFormatChanged, _onAlwaysUse24HourFormatChangedZone);
1459+
}
1460+
14331461
/// Whether the user has requested that [updateSemantics] be called when
14341462
/// the semantic contents of window changes.
14351463
///

‎engine/src/flutter/lib/web_ui/test/engine/platform_dispatcher/platform_dispatcher_test.dart‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -551,6 +551,37 @@ void testMain() {
551551
});
552552
});
553553

554+
test('invokeOnAlwaysUse24HourFormatChanged calls onAlwaysUse24HourFormatChanged', () {
555+
var called = false;
556+
void callback() {
557+
called = true;
558+
}
559+
560+
dispatcher.onAlwaysUse24HourFormatChanged = callback;
561+
expect(dispatcher.onAlwaysUse24HourFormatChanged, same(callback));
562+
563+
dispatcher.invokeOnAlwaysUse24HourFormatChanged();
564+
expect(called, isTrue);
565+
});
566+
567+
test('invokeOnAlwaysUse24HourFormatChanged preserves the zone', () {
568+
final Zone zone1 = Zone.current.fork();
569+
final Zone zone2 = Zone.current.fork();
570+
Zone? invokedZone;
571+
572+
zone1.runGuarded(() {
573+
dispatcher.onAlwaysUse24HourFormatChanged = () {
574+
invokedZone = Zone.current;
575+
};
576+
});
577+
578+
zone2.runGuarded(() {
579+
dispatcher.invokeOnAlwaysUse24HourFormatChanged();
580+
});
581+
582+
expect(invokedZone, same(zone1));
583+
});
584+
554585
test('adds the accessibility placeholder', () {
555586
final DomElement placeholder = domDocument.querySelector('flt-semantics-placeholder')!;
556587
expect(placeholder.isConnected, isTrue);

‎packages/flutter/lib/src/foundation/debug.dart‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -680,8 +680,8 @@ class DebugViewMetricsOverride with Diagnosticable {
680680

681681
// The metrics dart:ui delivers through PlatformDispatcher.onMetricsChanged,
682682
// plus alwaysUse24HourFormat, which dart:ui reports through
683-
// PlatformDispatcher.onPlatformConfigurationChanged because it has no
684-
// callback of its own.
683+
// PlatformDispatcher.onAlwaysUse24HourFormatChanged (as well as
684+
// onPlatformConfigurationChanged).
685685
//
686686
// This grouping, `_accessibilityFeatures`, and the standalone `textScaling`
687687
// and `platformBrightness` are what `_changesFrom`, and so == and hashCode,
@@ -723,8 +723,8 @@ class DebugViewMetricsOverride with Diagnosticable {
723723
// override and [other]: the view metrics (onMetricsChanged), the text scaling
724724
// table (onTextScaleFactorChanged), the brightness
725725
// (onPlatformBrightnessChanged), the accessibility flags
726-
// (onAccessibilityFeaturesChanged), and the 24 hour format, which is one of
727-
// the view metrics but is also announced through
726+
// (onAccessibilityFeaturesChanged), and the 24 hour format (onAlwaysUse24HourFormatChanged),
727+
// which is one of the view metrics but is also announced through
728728
// onPlatformConfigurationChanged.
729729
//
730730
// The one definition of "changed" that == and the replay of dart:ui
@@ -1196,9 +1196,9 @@ ui.FlutterView debugViewWithMetricsOverrides(ui.FlutterView view) {
11961196
// changed on every wrapped dispatcher, so that the framework re-reads them as
11971197
// it would after a platform change: the platform configuration first when a
11981198
// platform-wide setting changed, then the callback of each group that changed,
1199-
// in the order dart:ui uses. alwaysUse24HourFormat has no callback of its own
1200-
// and rides onMetricsChanged, the one notification the framework treats as
1201-
// "re-read everything about this view".
1199+
// in the order dart:ui uses. alwaysUse24HourFormat is announced through
1200+
// onAlwaysUse24HourFormatChanged, and also rides onMetricsChanged, the one
1201+
// notification the framework treats as "re-read everything about this view".
12021202
//
12031203
// Like the engine, this does not let one callback's failure cancel the ones
12041204
// after it, or the framework would be left reading a metric it was never told
@@ -1215,6 +1215,8 @@ void _debugNotifyViewMetricsOverrideChanged(_Changes changes) {
12151215
if (platformConfiguration) (ui.PlatformDispatcher d) => d.onPlatformConfigurationChanged,
12161216
if (changes.textScaling) (ui.PlatformDispatcher d) => d.onTextScaleFactorChanged,
12171217
if (changes.platformBrightness) (ui.PlatformDispatcher d) => d.onPlatformBrightnessChanged,
1218+
if (changes.alwaysUse24HourFormat)
1219+
(ui.PlatformDispatcher d) => d.onAlwaysUse24HourFormatChanged,
12181220
if (changes.accessibilityFeatures)
12191221
(ui.PlatformDispatcher d) => d.onAccessibilityFeaturesChanged,
12201222
if (changes.viewMetrics) (ui.PlatformDispatcher d) => d.onMetricsChanged,
@@ -1675,6 +1677,12 @@ class _DebugViewMetricsPlatformDispatcher implements ui.PlatformDispatcher {
16751677
set onTextScaleFactorChanged(ui.VoidCallback? callback) =>
16761678
_dispatcher.onTextScaleFactorChanged = callback;
16771679

1680+
@override
1681+
ui.VoidCallback? get onAlwaysUse24HourFormatChanged => _dispatcher.onAlwaysUse24HourFormatChanged;
1682+
@override
1683+
set onAlwaysUse24HourFormatChanged(ui.VoidCallback? callback) =>
1684+
_dispatcher.onAlwaysUse24HourFormatChanged = callback;
1685+
16781686
@override
16791687
ui.ViewFocusChangeCallback? get onViewFocusChange => _dispatcher.onViewFocusChange;
16801688
@override

‎packages/flutter/test/foundation/debug_view_metrics_override_test.dart‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1294,6 +1294,7 @@ void main() {
12941294
wrapped.onPlatformConfigurationChanged = () => notifications.add('configuration');
12951295
wrapped.onTextScaleFactorChanged = () => notifications.add('textScaleFactor');
12961296
wrapped.onPlatformBrightnessChanged = () => notifications.add('platformBrightness');
1297+
wrapped.onAlwaysUse24HourFormatChanged = () => notifications.add('alwaysUse24HourFormat');
12971298
wrapped.onAccessibilityFeaturesChanged = () => notifications.add('accessibilityFeatures');
12981299
wrapped.onMetricsChanged = () => notifications.add('metrics');
12991300

@@ -1318,9 +1319,9 @@ void main() {
13181319
'accessibilityFeatures',
13191320
]);
13201321

1321-
// The 24 hour format has no callback of its own: the configuration
1322-
// notification is the only one that names it, and onMetricsChanged is
1323-
// what tells the framework to re-read it.
1322+
// The 24 hour format announces onAlwaysUse24HourFormatChanged and
1323+
// onPlatformConfigurationChanged, and onMetricsChanged is what tells the
1324+
// framework to re-read it.
13241325
notifications.clear();
13251326
debugSetViewMetricsOverride(
13261327
1,
@@ -1332,7 +1333,7 @@ void main() {
13321333
alwaysUse24HourFormat: true,
13331334
),
13341335
);
1335-
expect(notifications, <String>['configuration', 'metrics']);
1336+
expect(notifications, <String>['configuration', 'alwaysUse24HourFormat', 'metrics']);
13361337

13371338
// A table that scales differently but reports the same factor is still a
13381339
// change of text scaling.
@@ -1376,17 +1377,15 @@ void main() {
13761377
wrapped.onMetricsChanged = () => notifications.add('metrics');
13771378
wrapped.onTextScaleFactorChanged = () => notifications.add('textScaleFactor');
13781379
wrapped.onPlatformBrightnessChanged = () => notifications.add('platformBrightness');
1380+
wrapped.onAlwaysUse24HourFormatChanged = () => notifications.add('alwaysUse24HourFormat');
13791381
wrapped.onAccessibilityFeaturesChanged = () => notifications.add('accessibilityFeatures');
13801382

13811383
for (final MapEntry<String, _MetricChange> entry in _perMetricChange.entries) {
13821384
debugSetViewMetricsOverride(1, _fullyPopulated);
13831385
notifications.clear();
13841386
debugSetViewMetricsOverride(1, entry.value(_fullyPopulated));
13851387
expect(notifications.toSet(), switch (entry.key) {
1386-
// dart:ui has no callback of its own for the 24 hour format: it
1387-
// reports it through the configuration notification, and the
1388-
// framework re-reads it when the view metrics change.
1389-
'alwaysUse24HourFormat' => <String>{'configuration', 'metrics'},
1388+
'alwaysUse24HourFormat' => <String>{'configuration', 'alwaysUse24HourFormat', 'metrics'},
13901389
'textScaling' => <String>{'configuration', 'textScaleFactor'},
13911390
'platformBrightness' => <String>{'configuration', 'platformBrightness'},
13921391
final String metric when viewMetrics.contains(metric) => <String>{'metrics'},
@@ -1469,6 +1468,16 @@ void main() {
14691468
});
14701469

14711470
group('engine roll tolerance', () {
1471+
test('forwards onAlwaysUse24HourFormatChanged', () {
1472+
final fake = _TwoViewPlatformDispatcher();
1473+
final ui.PlatformDispatcher dispatcher = debugApplyViewMetricsOverrides(fake);
1474+
var calls = 0;
1475+
dispatcher.onAlwaysUse24HourFormatChanged = () => calls += 1;
1476+
expect(fake.onAlwaysUse24HourFormatChanged, isNotNull);
1477+
fake.onAlwaysUse24HourFormatChanged!();
1478+
expect(calls, 1);
1479+
});
1480+
14721481
test('wrappers declare no noSuchMethod', () {
14731482
final fake = _TwoViewPlatformDispatcher();
14741483
final ui.PlatformDispatcher dispatcher = debugApplyViewMetricsOverrides(fake);
@@ -1573,6 +1582,9 @@ class _TwoViewPlatformDispatcher implements ui.PlatformDispatcher {
15731582
@override
15741583
ui.VoidCallback? onTextScaleFactorChanged;
15751584

1585+
@override
1586+
ui.VoidCallback? onAlwaysUse24HourFormatChanged;
1587+
15761588
@override
15771589
ui.ViewFocusChangeCallback? onViewFocusChange;
15781590

‎packages/flutter/test/widgets/debug_view_metrics_override_test.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1517,6 +1517,9 @@ class _CurvedTextScalingPlatformDispatcher implements ui.PlatformDispatcher {
15171517
@override
15181518
ui.VoidCallback? onTextScaleFactorChanged;
15191519

1520+
@override
1521+
ui.VoidCallback? onAlwaysUse24HourFormatChanged;
1522+
15201523
@override
15211524
dynamic noSuchMethod(Invocation invocation) =>
15221525
throw UnimplementedError('${invocation.memberName} is not needed by these tests.');

0 commit comments

Comments
 (0)