Skip to content

Commit e0d804f

Browse files
authored
[ios] Update the screen in didUpdateEffectiveGeometry (flutter#195508)
This is a follow up to flutter#195199 As discussed [in this thread](flutter#195199 (comment)), For a fixed-size FlutterView, `viewDidLayoutSubviews` is called when switching from outer to inner display, but not called when switching from inner to outer display. This is a puzzling behavior (possibly a bug in UIKit), but it does prove that relying on `viewDidLayoutSubviews` is not complete. The only API we can find that triggers when a scene changes screen is `didUpdateEffectiveGeometry`. There won't be a breaking change, but it would require `FlutterSceneLifeCycleProvider` users to add a one-liner for this to work. We should update our website to include this ([PR](flutter/website#14012)): ``` @available(iOS 26.0, *) func windowScene(_ windowScene: UIWindowScene, didUpdateEffectiveGeometry previousEffectiveGeometry: UIWindowScene.Geometry) { sceneLifeCycleDelegate.windowScene(windowScene, didUpdateEffectiveGeometry: previousEffectiveGeometry) } ``` ## Testing I have manually verified with a fixed-size 300x300 FlutterView, and confirmed the information is correctly updated when switching screen. It is not possible to write integration test - I don't think there's a `simctl` sub-command that allows us to fold/unfold the simulator. We could add a integration test in the future if such api become available. Fixes flutter#195177 *If you had to change anything in the [flutter/tests] repo, include a link to the migration guide as per the [breaking change policy].* ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [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 in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [ ] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/CONTRIBUTING.ai.md [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [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/ [flutter/tests]: https://github.com/flutter/tests [flutter/website]: https://github.com/flutter/website [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent b9a8a15 commit e0d804f

6 files changed

Lines changed: 177 additions & 3 deletions

File tree

‎engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterSceneLifeCycle.h‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,22 @@ API_AVAILABLE(ios(13.0))
258258
performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
259259
completionHandler:(void (^)(BOOL succeeded))completionHandler;
260260

261+
#pragma mark - Responding to geometry changes
262+
263+
/**
264+
* Updates the display information of the Flutter engines associated with `windowScene`.
265+
*
266+
* Call this from `-[UIWindowSceneDelegate windowScene:didUpdateEffectiveGeometry:]`. UIKit calls
267+
* that method whenever a `UIWindowScene` moves between screens, even if no Flutter view changes
268+
* size. `FlutterSceneDelegate` forwards this automatically.
269+
*
270+
* `previousEffectiveGeometry` is nonnull to match UIKit, but UIKit passes `nil` on the first call
271+
* while the scene is being created. This method ignores it.
272+
*/
273+
- (void)windowScene:(UIWindowScene*)windowScene
274+
didUpdateEffectiveGeometry:(UIWindowSceneGeometry*)previousEffectiveGeometry
275+
API_AVAILABLE(ios(26.0));
276+
261277
@end
262278

263279
/**

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/FlutterSceneDelegate.mm‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,15 @@ - (void)windowScene:(UIWindowScene*)windowScene
102102
completionHandler:completionHandler];
103103
}
104104

105+
#pragma mark - Responding to geometry changes
106+
107+
- (void)windowScene:(UIWindowScene*)windowScene
108+
didUpdateEffectiveGeometry:(UIWindowSceneGeometry*)previousEffectiveGeometry
109+
API_AVAILABLE(ios(26.0)) {
110+
[self.sceneLifeCycleDelegate windowScene:windowScene
111+
didUpdateEffectiveGeometry:previousEffectiveGeometry];
112+
}
113+
105114
#pragma mark - Helpers
106115

107116
- (BOOL)registerSceneLifeCycleWithFlutterEngine:(FlutterEngine*)engine scene:(UIScene*)scene {

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/FlutterSceneDelegateTest.m‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -272,6 +272,28 @@ - (void)testWindowScenePerformActionForShortcutItem {
272272
completionHandler:[OCMArg any]]);
273273
}
274274

275+
- (void)testWindowSceneDidUpdateEffectiveGeometry {
276+
if (@available(iOS 26.0, *)) {
277+
[self setupMockApplication];
278+
279+
FlutterSceneDelegate* sceneDelegate = [[FlutterSceneDelegate alloc] init];
280+
id mockSceneDelegate = OCMPartialMock(sceneDelegate);
281+
282+
FlutterPluginSceneLifeCycleDelegate* mockLifecycleDelegate =
283+
OCMClassMock([FlutterPluginSceneLifeCycleDelegate class]);
284+
OCMStub([mockSceneDelegate sceneLifeCycleDelegate]).andReturn(mockLifecycleDelegate);
285+
286+
id scene = OCMClassMock([UIWindowScene class]);
287+
id geometry = OCMClassMock([UIWindowSceneGeometry class]);
288+
289+
[((FlutterSceneDelegate*)mockSceneDelegate) windowScene:scene
290+
didUpdateEffectiveGeometry:geometry];
291+
292+
OCMVerify(times(1), [mockLifecycleDelegate windowScene:scene
293+
didUpdateEffectiveGeometry:geometry]);
294+
}
295+
}
296+
275297
- (void)testRegisterSceneLifeCycleWithFlutterEngine {
276298
[self setupMockApplication];
277299

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/FlutterSceneLifeCycle.mm‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -510,6 +510,30 @@ - (void)windowScene:(UIWindowScene*)windowScene
510510
}
511511
}
512512

513+
#pragma mark - Responding to geometry changes
514+
515+
// UIKit declares `previousEffectiveGeometry` as nonnull, but passes `nil` for it on the initial
516+
// call while the scene is being created. This is a UIKit bug. If Apple fixes it by marking the
517+
// parameter nullable, that is a breaking change for every Swift implementer of
518+
// `UIWindowSceneDelegate`, and this method will change to match.
519+
//
520+
// This parameter is still intentionally nonnull to match UIKit, rather than nullable:
521+
// - This method then only changes when UIKit's does, so Flutter never introduces a breaking change
522+
// here on its own. If it were nullable, Swift callers could pass an optional, and changing it to
523+
// nonnull later (e.g. if Apple stops passing `nil`) would break them.
524+
// - Like the other methods of this class, it mirrors the UIKit callback exactly, so forwarding is a
525+
// direct pass-through with matching types.
526+
- (void)windowScene:(UIWindowScene*)windowScene
527+
didUpdateEffectiveGeometry:(UIWindowSceneGeometry*)previousEffectiveGeometry
528+
API_AVAILABLE(ios(26.0)) {
529+
// The scene may have moved to a different screen. Unlike `viewDidLayoutSubviews`, this is called
530+
// even if the Flutter view's size did not change (e.g. a fixed-size view in an add-to-app host).
531+
// `updateDisplays` skips the update if the display information has not changed.
532+
for (FlutterEngine* engine in [self searchFlutterEnginesWithinScene:windowScene]) {
533+
[engine updateDisplays];
534+
}
535+
}
536+
513537
#pragma mark - Helpers
514538

515539
- (void)handleDeeplinkingForEngine:(FlutterEngine*)engine

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/FlutterSceneLifeCycleTest.mm‎

Lines changed: 101 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -696,7 +696,7 @@ - (void)testSceneWillConnectToSessionOptionsHandledByApplicationPluginMultipleEn
696696

697697
[delegate registerSceneLifeCycleWithFlutterEngine:mockEngine scene:mockScene];
698698
[delegate registerSceneLifeCycleWithFlutterEngine:mockEngine2 scene:mockScene];
699-
XCTAssertEqual([delegate searchFlutterEnginesWithinScene:mockScene].count, 2.0);
699+
XCTAssertEqual([delegate searchFlutterEnginesWithinScene:mockScene].count, 2U);
700700

701701
[delegate scene:mockScene willConnectToSession:session options:options];
702702
OCMVerify(times(1), [mockLifecycleDelegate scene:mockScene
@@ -1514,6 +1514,106 @@ - (void)testWindowScenePerformActionForShortcutItemHandledByNoPlugin {
15141514
completionHandler:handler]);
15151515
}
15161516

1517+
- (void)testWindowSceneDidUpdateEffectiveGeometryUpdatesDisplaysOfEnginesInScene {
1518+
if (@available(iOS 26.0, *)) {
1519+
FlutterPluginSceneLifeCycleDelegate* delegate =
1520+
[[FlutterPluginSceneLifeCycleDelegate alloc] init];
1521+
1522+
id mocks = [self mocksForEvents];
1523+
id mockScene = mocks[@"mockScene"];
1524+
// An engine whose view controller is in the scene, e.g. a fixed-size FlutterViewController
1525+
// embedded as a child view controller in an add-to-app host.
1526+
id viewControllerEngine = mocks[@"mockEngine"];
1527+
id mockWindow = OCMClassMock([UIWindow class]);
1528+
id mockHostViewController = OCMClassMock([UIViewController class]);
1529+
id mockFlutterViewController = OCMClassMock([FlutterViewController class]);
1530+
OCMStub([mockScene windows]).andReturn(@[ mockWindow ]);
1531+
OCMStub([mockWindow rootViewController]).andReturn(mockHostViewController);
1532+
OCMStub([mockHostViewController childViewControllers]).andReturn(@[
1533+
mockFlutterViewController
1534+
]);
1535+
OCMStub([mockFlutterViewController engine]).andReturn(viewControllerEngine);
1536+
// An engine registered with the scene by the developer.
1537+
id registeredEngine = OCMClassMock([FlutterEngine class]);
1538+
[delegate registerSceneLifeCycleWithFlutterEngine:registeredEngine scene:mockScene];
1539+
XCTAssertEqual([delegate searchFlutterEnginesWithinScene:mockScene].count, 2U);
1540+
1541+
id geometry = OCMClassMock([UIWindowSceneGeometry class]);
1542+
[delegate windowScene:mockScene didUpdateEffectiveGeometry:geometry];
1543+
1544+
OCMVerify(times(1), [viewControllerEngine updateDisplays]);
1545+
OCMVerify(times(1), [registeredEngine updateDisplays]);
1546+
} else {
1547+
XCTSkip(@"windowScene:didUpdateEffectiveGeometry: requires iOS 26.");
1548+
}
1549+
}
1550+
1551+
- (void)testWindowSceneDidUpdateEffectiveGeometryWithNilPreviousGeometryUpdatesDisplays {
1552+
if (@available(iOS 26.0, *)) {
1553+
FlutterPluginSceneLifeCycleDelegate* delegate =
1554+
[[FlutterPluginSceneLifeCycleDelegate alloc] init];
1555+
1556+
id mocks = [self mocksForEvents];
1557+
id mockEngine = mocks[@"mockEngine"];
1558+
id mockScene = mocks[@"mockScene"];
1559+
[delegate registerSceneLifeCycleWithFlutterEngine:mockEngine scene:mockScene];
1560+
1561+
// UIKit declares `previousEffectiveGeometry` as nonnull, but passes `nil` on the first call
1562+
// while the scene is being created. Passing a literal `nil` here would trigger `-Wnonnull`.
1563+
UIWindowSceneGeometry* previousEffectiveGeometry = nil;
1564+
[delegate windowScene:mockScene didUpdateEffectiveGeometry:previousEffectiveGeometry];
1565+
1566+
OCMVerify(times(1), [mockEngine updateDisplays]);
1567+
} else {
1568+
XCTSkip(@"windowScene:didUpdateEffectiveGeometry: requires iOS 26.");
1569+
}
1570+
}
1571+
1572+
- (void)testWindowSceneDidUpdateEffectiveGeometryDoesNotUpdateDisplaysOfEnginesInOtherScenes {
1573+
if (@available(iOS 26.0, *)) {
1574+
FlutterPluginSceneLifeCycleDelegate* delegate =
1575+
[[FlutterPluginSceneLifeCycleDelegate alloc] init];
1576+
1577+
id mocks = [self mocksForEvents];
1578+
id mockEngine = mocks[@"mockEngine"];
1579+
id mockScene = mocks[@"mockScene"];
1580+
id otherScene = OCMClassMock([UIWindowScene class]);
1581+
[delegate registerSceneLifeCycleWithFlutterEngine:mockEngine scene:otherScene];
1582+
1583+
[delegate windowScene:mockScene
1584+
didUpdateEffectiveGeometry:OCMClassMock([UIWindowSceneGeometry class])];
1585+
1586+
OCMVerify(never(), [mockEngine updateDisplays]);
1587+
} else {
1588+
XCTSkip(@"windowScene:didUpdateEffectiveGeometry: requires iOS 26.");
1589+
}
1590+
}
1591+
1592+
- (void)testWindowSceneDidUpdateEffectiveGeometryUpdatesDisplaysOfEnginesInSingleScene {
1593+
if (@available(iOS 26.0, *)) {
1594+
id mockApplication = OCMClassMock([UIApplication class]);
1595+
OCMStub([mockApplication sharedApplication]).andReturn(mockApplication);
1596+
OCMStub([mockApplication supportsMultipleScenes]).andReturn(NO);
1597+
1598+
FlutterPluginSceneLifeCycleDelegate* delegate =
1599+
[[FlutterPluginSceneLifeCycleDelegate alloc] init];
1600+
1601+
// In a single-scene app, every engine registers itself for the single scene when created.
1602+
id mockEngine = OCMClassMock([FlutterEngine class]);
1603+
[FlutterPluginSceneLifeCycleDelegate registerEngineForSingleScene:mockEngine];
1604+
1605+
id mockScene = OCMClassMock([UIWindowScene class]);
1606+
[delegate windowScene:mockScene
1607+
didUpdateEffectiveGeometry:OCMClassMock([UIWindowSceneGeometry class])];
1608+
1609+
OCMVerify(times(1), [mockEngine updateDisplays]);
1610+
1611+
[mockApplication stopMocking];
1612+
} else {
1613+
XCTSkip(@"windowScene:didUpdateEffectiveGeometry: requires iOS 26.");
1614+
}
1615+
}
1616+
15171617
- (NSDictionary*)mocksForEvents {
15181618
id mockEngine = OCMClassMock([FlutterEngine class]);
15191619
id mockLifecycleDelegate = OCMClassMock([FlutterEnginePluginSceneLifeCycleDelegate class]);

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/FlutterViewController.mm‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1357,8 +1357,11 @@ - (void)viewDidLayoutSubviews {
13571357
}
13581358

13591359
// Asks the engine to send updated display information to the framework, e.g. when the view is first
1360-
// placed in a window, or moves between the inner and outer displays of a device with multiple
1361-
// built-in displays. The engine skips the update if the display information has not changed.
1360+
// placed in a window, or is resized because it moved between the inner and outer displays of a
1361+
// device with multiple built-in displays. If the view moves between displays without changing size
1362+
// (e.g. a fixed-size view in an add-to-app host), it may not be laid out again, so
1363+
// `-[FlutterPluginSceneLifeCycleDelegate windowScene:didUpdateEffectiveGeometry:]` also updates the
1364+
// displays. The engine skips the update if the display information has not changed.
13621365
- (void)updateEngineDisplays {
13631366
if (self.engine.viewController != self) {
13641367
return;

0 commit comments

Comments
 (0)