Struct OverlaySpec

pub struct OverlaySpec<Message: Clone> {
    pub id: OverlayId,
    pub layer: Layer,
    pub anchor: Anchor,
    pub size: (u32, u32),
    pub exclusive_zone: i32,
    pub keyboard_exclusive: bool,
    pub input_region: Option<Vec<Rect>>,
    pub view: Element<Message>,
    pub on_dismiss: Option<Message>,
    pub anchor_widget_id: Option<WidgetId>,
}

Description of an additional layer-shell surface rendered on top of the main application surface.

Apps return a list of these from App::overlays each frame. The runtime creates one Wayland layer-shell surface per active overlay, renders its view to its own canvas, and dispatches input to it independently of the main surface. Overlays share the same message type as the main app — messages emitted by widgets inside an overlay are delivered to App::update exactly like messages from the main view.

Overlays are useful for building shells whose main surface sits behind regular app windows (e.g. a homescreen on Layer::Background) while still exposing on-demand panels above everything (launcher, quick settings, power menu…).

Fields

id: OverlayId

Stable identifier, used to diff overlays between frames.

layer: Layer

Wayland layer for this overlay. Typically Layer::Overlay or Layer::Top.

anchor: Anchor

Screen edges to anchor to.

size: (u32, u32)

Desired size ( width, height ) in logical pixels. 0 in either component means “fill available space in that dimension”.

exclusive_zone: i32

Exclusive zone in pixels reserved from the anchored edge. -1 requests focus without reserving space, 0 is the default for transient overlays that should not push other surfaces around.

keyboard_exclusive: bool

When true, the compositor sends keyboard events to this overlay without requiring a click first.

input_region: Option<Vec<Rect>>

Interactive input region as a list of rects (logical pixels). Only these areas receive pointer/touch input; the rest passes through. None means the full surface receives input.

view: Element<Message>

Widget tree for this overlay.

on_dismiss: Option<Message>

Message sent when the overlay should be dismissed. The runtime fires it in three situations:

1. The compositor sends xdg_popup.popup_done (xdg-popup mode) — typically when the user clicks outside the popup with the grab fully active.
2. The user presses pointer / touch on the main surface while the overlay is still mapped, and the press does not fall on the trigger rect identified by Self::anchor_widget_id. This covers compositors (notably Mutter) that route the button to the parent surface instead of breaking the popup grab when the cursor was already over the parent.
3. The user presses Escape while at least one xdg-popup overlay is open.

The application is expected to flip its is_open flag (or equivalent) to false in update() so the next frame stops returning the spec from App::overlays. The runtime is idempotent if the message arrives more than once for the same open / close cycle.

anchor_widget_id: Option<WidgetId>

When set, the overlay is rendered as a Wayland xdg-popup anchored to the rect of the widget tagged with this crate::types::WidgetId in the previous frame’s layout — the standard mechanism for combo / context-menu / tooltip popups in xdg-shell applications. The compositor positions the popup adjacent to the anchor and is allowed to flip it (drop-up instead of drop-down) when there is not enough room.

When this field is None, the overlay is rendered as a wlr-layer-shell surface — the path used by shells, panels, lock screens and overlays that need full-surface coverage. In that mode layer / anchor / exclusive_zone / keyboard_exclusive carry the placement; for the popup mode they are ignored.