Add ViewportBuilder::with_monitor for targeting specific monitors

[Le-Syl21]

Summary

Adds ViewportBuilder::with_monitor(index) and ViewportCommand::SetMonitor(index) for targeting a specific monitor at viewport creation or at runtime.

This is useful whenever an app needs to open borderless fullscreen on a specific output — kiosks, pinball cabinets, digital signage, multi-monitor dashboards. It's also the only portable way to target a specific output under Wayland, since Wayland doesn't expose absolute window positions to clients; with_position is silently ignored there.

Implementation

• egui/src/viewport.rs: adds monitor: Option<usize> to ViewportBuilder, with_monitor(index) setter, ViewportCommand::SetMonitor(index) variant, and diff detection in patch().
• egui-winit/src/lib.rs:
  • In create_window (after building WindowAttributes but before event_loop.create_window(...)): resolves event_loop.available_monitors().nth(index) and calls with_fullscreen(Some(Fullscreen::Borderless(Some(monitor.clone())))) on the attributes.
  • In process_viewport_command: handles SetMonitor(idx) by resolving via window.available_monitors().nth(idx) + window.set_fullscreen(Some(Fullscreen::Borderless(Some(monitor)))).
  • Out-of-range index is logged as a warning and silently ignored (no panic, no state mutation).

Usage

// Window opens in borderless fullscreen on monitor index 1
let options = eframe::NativeOptions {
    viewport: egui::ViewportBuilder::default()
        .with_title("kiosk")
        .with_decorations(false)
        .with_monitor(1),
    ..Default::default()
};

// At runtime, move the root viewport to monitor 2:
ctx.send_viewport_cmd(egui::ViewportCommand::SetMonitor(2));

Why not just with_position(monitor.position)?

• Wayland clients cannot read global positions — with_position is effectively a no-op.
• X11 + Mutter/GNOME race: OuterPosition is dropped if set before the window is mapped. Even with repeat-send loops, the window sometimes lands on the monitor the cursor is on rather than the requested one.
• macOS / Windows Fullscreen::Borderless(Some(handle)) is the OS-native API for borderless fullscreen on a specific screen.

Using winit's MonitorHandle explicitly sidesteps all of these — same API path as when users press F11 in apps.

Relationship to viewport rotation (PR #8113)

Completely orthogonal — with_monitor doesn't depend on rotation and vice versa. They're submitted separately because they're independent features. In practice they combine well for cabinet/kiosk apps (rotate the root on a specific playfield output, non-rotated secondary viewports on other screens).

Test plan

• cargo check --workspace clean on Linux (X11 + Wayland)
• Manual on X11 + Mutter (GNOME 46): window lands on the requested monitor in borderless fullscreen, no race with OuterPosition.
• Manual downstream in a multi-monitor kiosk app (pinball cabinet launcher, 3 monitors) — with_monitor(idx) places each viewport on the correct screen deterministically.
• Out-of-range index produces a warning log, app continues normally.
• Reviewer: any concerns on naming (with_monitor vs e.g. with_monitor_index) before final polish.

🤖 Contributions from Claude Code

[github-actions]

Preview is being built...

Preview will be available at https://egui-pr-preview.github.io/pr/8117-viewport-target-monitor

View snapshot changes at kitdiff