Skip to content

Conversation

@JakkuSakura
Copy link

This PR improves the “custom titlebar / custom decorations” story end-to-end: it adds two examples, fills in a missing backend capability (X11 window menu), and fixes a macOS
crash when toggling decorations.

What’s in this PR

  • New example: winit/examples/custom_decorations.rs
    • Demonstrates titlebar-less windows via WindowAttributes::with_decorations(false).
    • Shows the minimal primitives needed to keep expected window UX when drawing your own chrome:
      • Move: Window::drag_window() by dragging a top bar region.
      • Resize: Window::drag_resize_window(ResizeDirection) by dragging edges/corners.
      • Window/system menu: Window::show_window_menu(position) on right click (no-op where unsupported).
      • Basic caption buttons (minimize/maximize/close) with hover hit-testing and cursor feedback.
    • Rendering is intentionally toolkit-free: solid background + top bar + button rects using softbuffer.
  • New example: winit/examples/custom_titlebar.rs
    • Demonstrates “OS-provided titlebar customization knobs” where available:
      • macOS: transparent/unified titlebar and related attributes.
      • Windows: titlebar/border colors and backdrop type.
    • Includes runtime toggles for quick manual verification.
  • Example support utilities: winit/examples/util/fill.rs
    • Adds fill_window_with_top_bar(...) and fill_window_with_top_bar_and_rects(...) (plus a tiny Rect helper) so examples can render simple custom chrome without a UI toolkit.

Backend/library changes

  • X11: implement Window::show_window_menu via _GTK_SHOW_WINDOW_MENU when the WM advertises support.
    • winit-x11/src/atoms.rs
    • winit-x11/src/window.rs
  • Docs: update platform support notes for Window::show_window_menu.
    • winit-core/src/window.rs
  • macOS: avoid panic when the view is temporarily detached from a window (can happen during decoration toggles).
    • winit-appkit/src/view.rs
    • (plus small related adjustments in AppKit crate as needed)

Why this is necessary

  • decorations(false) is the foundation for titlebar-less windows across platforms, but without a canonical recipe users frequently ship windows that can’t be moved/resized or that
    lose access to the system menu.
  • The new example provides a minimal, portable blueprint for “draw your own titlebar” using existing winit primitives, and acts as a regression target for pointer events + drag/
    window-menu APIs.
  • X11 window menu support closes a real gap in the custom-decorations story (Windows and Wayland already support it; X11 now does where the WM cooperates).
  • The macOS detachment fix addresses a crash encountered when toggling decorations rapidly.

How to test

  • cargo run -p winit --example custom_decorations
    • Drag top bar to move; drag edges/corners to resize; right click to request system menu; click caption buttons.
  • cargo run -p winit --example custom_titlebar
    • Use keybindings to toggle platform-specific titlebar options.

Notes / Limitations

  • X11 window menu is best-effort: it depends on WM support for _GTK_SHOW_WINDOW_MENU (checked via _NET_SUPPORTED).
  • Caption button visuals are intentionally simple; example focuses on mechanics and API usage rather than native styling.

closes #3664
related to #4100, but my focus in on MacOS and adds examples. I'm fine merging the code and test if either is merged first

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

Customize titlebar

1 participant