Adding the SatelliteWindowController interface to _window.dart

[mattkae]

What's new?

• Added the concept of a SatelliteWindowController and SatelliteWindow widget to the _window.dart API
• Wrote tests for it
• Throwing "unsupported" for all existing WindowingOwners when trying to create it
• Stubbed it in the example application
• Implemented a "happy" implementation in the flutter_test package

Pre-launch Checklist

• I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
• I read the [Tree Hygiene] wiki page, which explains my responsibilities.
• I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
• I signed the [CLA].
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is [test-exempt].
• I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
• All existing and new tests are passing.

[gemini-code-assist]

Code Review

This pull request introduces a new experimental SatelliteWindow and SatelliteWindowController to the windowing API. The changes are well-structured, including API definitions, platform stubs, a test implementation, and an example. The code follows existing patterns and is well-documented. I have a couple of minor suggestions: one to adhere to the Dart style guide for a one-line method, and another to fix a typo in an error message.

[loic-sharma]

Just curious, why can't we change the satellite's position when it is reparented? Is that something we can't support on all platforms?

---

Previously the docs state:

Satellite windows maintain their position relative to their parent

What happens if I reparent a satellite window, and then move the new parent? Will the satellite window maintain its position relative to its new parent? I expect that might result in funky behavior.

[mattkae]

We can change the satellite's position, but we figured that would be too jarring for users.

The best example is a word processing application. Imagine you have two windows open each with their own document, but sharing the same satellite window toolbar. When one document is closed, you would expect the satellite toolbar to remain open in the same position instead of snapping to a new anchor position next to the other document.

In this case, the satellite window will now maintain its position relative to the remaining document.

[loic-sharma]

Gotcha, that makes sense.

Would it make sense to add a move({required Rect anchorRect, required WindowPositioner positioner}) method to SatelliteWindowController? This would update the satellite window position once. I imagine this would be useful in reparenting scenarios if you do want this slightly jarring experience. I'm OK punting this until later, just a thought.

[mattkae]

Yeah let's punt it for now, and see if it comes up. Intuition tells me that the user probably won't want to do that, but who knows. We have that type of method for tooltips and popups.

[justinmc]

• I can't get the example to run, see my comments below.

• I see this is beyond the stuff that you guys decided to call MVP in your doc, are there any implications for pre/post MVP work and our plans for shipping it in general?

• Overall this PR looks fine but there's one thing that I want to think through. Let's say I'm building an app on only one platform, say macOS. SatelliteWindow uses NSPanel under the hood on macOS, which looks like it takes 3 boolean parameters (isFloatingPanel, becomesKeyOnlyIfNeeded, and worksWhenModal). Let's say I need to individually set one of those booleans for my use case. What are my options? How much of the multiwindow code will be unusable for me and how much can I still manage to use?

[mattkae]

• I can't get the example to run, see my comments below.

Fixed 👍 bad merge

* I see this is beyond the stuff that you guys decided to call [MVP in your doc](https://docs.google.com/document/d/1eQG-IS7r4_S9_h50MY_hSGwUVtgSTRSLzu7MLzPNd2Y/edit?tab=t.0#heading=h.4y3d6rrizqfa), are there any implications for pre/post MVP work and our plans for shipping it in general?

Satellites were always intended to follow after the other window types, so we figured we'd open up the conversation now to get the ball rolling 😄 These can very well ship with the rest of the windowing API, but we expected them to be a bit more controversial as they have no precedent in Flutter or Material.

* Overall this PR looks fine but there's one thing that I want to think through. Let's say I'm building an app on only one platform, say macOS. SatelliteWindow uses [NSPanel](https://developer.apple.com/documentation/appkit/nspanel) under the hood on macOS, which looks like it takes 3 boolean parameters (isFloatingPanel, becomesKeyOnlyIfNeeded, and worksWhenModal). Let's say I need to individually set one of those booleans for my use case. What are my options? How much of the multiwindow code will be unusable for me and how much can I still manage to use?

At the moment, your options are limited. We haven't yet tackled the problem of "how do I add this platform-specific configuration to my window" yet. This is something that we'll really have to talk about for Win32, macOS, and Linux. I have a feeling that this will involve designing an API that exposes many of those features, which is no small task.

The "escape hatch" that the user has at the moment is to override the WindowingOwner with their own implementation to create their custom satellite window.

[knopp]

Overall this PR looks fine but there's one thing that I want to think through. Let's say I'm building an app on only one platform, say macOS. SatelliteWindow uses NSPanel under the hood on macOS, which looks like it takes 3 boolean parameters (isFloatingPanel, becomesKeyOnlyIfNeeded, and worksWhenModal). Let's say I need to individually set one of those booleans for my use case. What are my options? How much of the multiwindow code will be unusable for me and how much can I still manage to use?

We will be exposing raw window handle (NSWindow*, HWND and GtkWindow*). Once you have the NSWindow you can pretty much change any attribute that you want. There are plans to expose message handling on windows too, so you can for example handle WM_NCHITTEST if you want completely customizable window.

We will likely want to expose some of the NSWindowDelegate methods too. The nice thing is we can do all this per platform implementation and we don't need to with lowest common denominator.

[loic-sharma]

I'd also add a sentence that explains how destroying the parent BaseWindowController affects this SatelliteWindowController.

It'd likely be worth adding a similar comment to dialog, tooltip, and popups window controllers too.

[mattkae]

I added it just to satellite for now.

I am going to revise some of the documentation for the other windows after this, as satellites have brought up a bunch of nits that we should address there.

[loic-sharma]

SGTM, thanks!

[justinmc]

LGTM 👍

Thanks for the explanations of the API here @mattkae and @knopp, I think the problem is a lot smaller than I was assuming. As discussed offline I think the best way to prove this is to include an example of the use of something like the raw NSWindow* used alongside the rest of the usual multiwindow infrastructure like RegularWindow etc. But that can wait for another PR, once we have exposed the raw window handles.

Landing this PR won't delay the removal of the feature flag, will it? I just want to make sure that adding satellites in the framework isn't going to delay everything else by expanding the scope of the engine work.

[loic-sharma]

LGTM!

[mattkae]

Landing this PR won't delay the removal of the feature flag, will it? I just want to make sure that adding satellites in the framework isn't going to delay everything else by expanding the scope of the engine work.

No it should not. We want to keep the feature flag around while we gain some early users of the windowing system. This is just another window that we'll get feedback on, albeit a less-used window in all likelihood.