Wayland, Windows, MacOS: Popup Implementation

[Murmele]

Implement proper decorationless popups by specifying the type of the child window with with_type()

With this PR different kind of child windows can be created

• Popups: Special windows without any decoration which can be positioned relative to the parent
• Window: Normal window with a parent or not

The type can be specified during creation of the Window using the window_attributes and the with_type() function. As default a normal Window is used. If Popup is choosen a parent must be specified, otherwise the Popup creation fails with an Error returned by the new() function.

Related issues: #403 and #4256

• Tested on all platforms changed
• Added an entry to the changelog module if knowledge of this change could be valuable to users
• Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior
• Created or updated an example program if it would help users understand this functionality

Platforms

• Wayland
  • Testing grabbing
    • Gnome (Mutter)
    • Kde Plasma
• Windows
• MacOs
• X11

Wayland:

Bildschirmaufzeichnung.vom.2026-06-04.13-18-16.mp4

This work is sponsored by the NLnet foundation

[kchibisov]

I think the idea with those pop-ups were to have a separate type other than glue to window, because as you said, they are very restricted on some platforms and on some platform it's indeed just a Window.

so in top-level API I would have them, as a separate type with its own restrictions, and what not, I'm also not sure if those things can be owned by the user, really, I think popups should be more like something you create from e.g. Window so Window::create_popup type of API call, that may take an ActiveEventLoop or ActiveEventLoop. EventLoop having an api like ActiveEventLoop::create_pop(&dyn Window, PopupProperties) as generally better in my opinion.

Popups need to be closed in reverse order (children before parents), otherwise you get a protocol violation:

Exactly why I want to have them owned by Parent, whether it's window or some other thing.

Generally, I think the initial plan was to have some kind of trait Surface and then for event loop to have ActiveEventLoop::create_popup(&mut dyn Surface, so it adds popup for the Surface so API is a bit more future proof.

@tronical would like to hear your opinion here since you're representing ui toolkit side 😅

I just want to account for other special surfaces Wayland people can create which has their own popup type that is certainly not different than standard popup.

[tronical]

I think the idea with those pop-ups were to have a separate type other than glue to window, because as you said, they are very restricted on some platforms and on some platform it's indeed just a Window.

so in top-level API I would have them, as a separate type with its own restrictions, and what not, I'm also not sure if those things can be owned by the user, really, I think popups should be more like something you create from e.g. Window so Window::create_popup type of API call, that may take an ActiveEventLoop or ActiveEventLoop. EventLoop having an api like ActiveEventLoop::create_pop(&dyn Window, PopupProperties) as generally better in my opinion.

Popups need to be closed in reverse order (children before parents), otherwise you get a protocol violation:

Exactly why I want to have them owned by Parent, whether it's window or some other thing.

That's indeed an interesting constraint (reverse order required).

Generally, I think the initial plan was to have some kind of trait Surface and then for event loop to have ActiveEventLoop::create_popup(&mut dyn Surface, so it adds popup for the Surface so API is a bit more future proof.

@tronical would like to hear your opinion here since you're representing ui toolkit side 😅

I just want to account for other special surfaces Wayland people can create which has their own popup type that is certainly not different than standard popup.

I see the discrepancy, but I also see that - wayland aside - popups have more in common with Window than not. Another surface abstraction is tempting indeed, but my feeling is that it may be worthwhile to go with this approach first and learn from it.

(disclaimer: I'm biased though as I'm Martin's colleague :)

[kchibisov]

The problem with Wayland, is that if you randomly use it wrongly, it really likes killing applications with protocol errors, so my suggestion is mostly to try solve it on type system level, or at least make it less likely, so users won't have to debug Wayland when it breaks in their cross platform app.

I also remember that popups can be discarded/removed on user behalf and winit window is kind of persistent now.

[HigherOrderLogic]

For Wayland: shouldnt we also use the xdg-dialog-v1 protocol to mark it as dialog? This implementation doesnt seems to use that protocol atm.

[kchibisov]

I think dialog protocol serves a different purpose, and also not widely available?

[HigherOrderLogic]

I think dialog protocol serves a different purpose

Ah right, I didnt read the PR description carefully, my bad. Originally thought it was popup dialog.

and also not widely available?

All 3 most popular compositors right now, KWin, Mutter and Hyprland, implement it so I dont think it's a problem.

[Murmele]

For Wayland: shouldnt we also use the xdg-dialog-v1 protocol to mark it as dialog? This implementation doesnt seems to use that protocol atm.

This will be implemented in a second step. There I will use this protocol

[Murmele]

@kchibisov @kchibisov Thanks for the feedback. And the patches. I will go through it next days and integrate them.

The problem with Wayland, is that if you randomly use it wrongly, it really likes killing applications with protocol errors, so my suggestion is mostly to try solve it on type system level, or at least make it less likely, so users won't have to debug Wayland when it breaks in their cross platform app.

I also remember that popups can be discarded/removed on user behalf and winit window is kind of persistent now.

I will have a look into it how to integrate the popup as child of another popup/window so the reverse order could be solved automatically.

[Murmele]

@kchibisov @CryZe @tronical

In 90ebef0 I implemented the correct popup order destroyment. I had the problem that the Popup Item it self contained a window state and therefore it got not delegated to the compositor that the popup shall be deleted. This I fixed in ac4a329 by storing only a Weak pointer of the window state in the Popup struct (popup_state: Weak<Mutex<WindowState>>).
What do you think about instead of returning a Box<dyn Window> returning a Weak pointer. So the event loop basically stores the state popup and the user has only a weak pointer and if the popup was destroyed for some reason (Parent destroyed, ...) then the pointer is invalid and the user is aware that it does not exist anymore?

[kchibisov]

What do you think about instead of returning a Box returning a Weak pointer. So the event loop basically stores the state popup and the user has only a weak pointer and if the popup was destroyed for some reason (Parent destroyed, ...) then the pointer is invalid and the user is aware that it does not exist anymore?

I like that you also came to a conclusion I had for the window storage, as in basically user has some handle but the Window itself is only owned by winit.

I'll think about it a bit since we want to plug it into the current design, but generally, I think that's how it should be, honestly, even though a lot of folks disagree with me on that matter...