Treeland Wine window state

window state query and control for Wine

This protocol provides window state management capabilities required by Wine (the Windows API compatibility layer) that are not available through standard Wayland protocols.

Standard xdg-shell lacks:

  • any way to read whether a toplevel is minimized,
  • any way to programmatically unminimize a toplevel,
  • any way to request activation without a valid xdg-activation token originating from a prior user interaction,
  • any way to request a visual attention hint (taskbar flash) without stealing focus.

This protocol fills those gaps. A client obtains a treeland_wine_window_state_v1 object for each xdg_toplevel whose state it needs to observe or control. The compositor remains the final authority: every request is advisory, and the compositor reports the authoritative state through events.

The key words "must", "must not", "should", "should not", and "may" in this document are to be interpreted as described in IETF RFC 2119.

Warning! This protocol is EXPERIMENTAL and under active development. It may change at any time, including in backward-incompatible ways, without incrementing the interface major version and without prior notice. No compatibility guarantees of any kind are provided. Clients and compositors must track the upstream definition in treeland-protocols and must not rely on the current interface names, requests, events, or semantics remaining stable across releases.

global entry point for Wine window state control

Lets a Wine client create per-toplevel state objects. The compositor should restrict binding to trusted clients identified by app_id or an equivalent policy mechanism.

The client must destroy all child treeland_wine_window_state_v1 objects before destroying this object.

destroy()
destroy the manager

Destroys this manager object. The client must destroy every treeland_wine_window_state_v1 created through this manager before sending this request; otherwise the compositor must raise an implementation-defined protocol error.

get_window_state(id: new_id<treeland_wine_window_state_v1>, toplevel: object<xdg_toplevel>)
Argument
Type
Description
idnew_id<treeland_wine_window_state_v1>
toplevelobject<xdg_toplevel>
create a state object for an xdg_toplevel

Creates a treeland_wine_window_state_v1 bound to the given xdg_toplevel. At most one state object may exist for each toplevel; requesting a second one is a toplevel_already_bound error. If the xdg_toplevel has been destroyed or has no configured role, the compositor must raise a defunct_toplevel error.

Upon creation, the compositor immediately sends a state_changed event to report the current state of the toplevel.

Argument
Value
Description
toplevel_already_bound0
a state object already exists for the given toplevel
defunct_toplevel1
the xdg_toplevel has no associated role or has been destroyed

per-toplevel state observation and control

Observes and controls the lifecycle state for one xdg_toplevel surface.

State flags are reported via the state_changed event. Each flag corresponds to a Windows window state that xdg-shell does not expose to clients.

If the associated xdg_toplevel is destroyed, this object becomes inert. All subsequent requests are ignored and no further events are emitted. The client should destroy the inert object.

destroy()
destroy this state object

Destroys the state object. This does not affect the associated xdg_toplevel.

unminimize()
request that the toplevel be unminimized

Requests that the compositor restore this toplevel from the minimized state.

Standard xdg-shell provides xdg_toplevel.set_minimized but no way to reverse it. This request fills that gap.

If the toplevel is not currently minimized, this request has no effect. If the compositor honors the request, it emits a state_changed event with the minimized flag cleared.

This corresponds to the Wine/Windows ShowWindow(SW_RESTORE) call on a minimized window.

Argument
Type
Description
serialuint
client-assigned serial for correlating with activate_denied
reasonuint<treeland_wine_window_state_v1.activate_reason>
why the client is requesting activation
seatobject<wl_seat>
the seat on which to activate
request that the toplevel be activated

Requests that the compositor give keyboard focus to this toplevel and raise it in the stacking order.

serial is a client-assigned value that is echoed back in any activate_denied event for this request, allowing the client to correlate denials when multiple activations are in flight.

The reason argument informs the compositor about the context of the activation. Compositors should generally honor user_request and restore activations, and may choose to deny or convert programmatic activations into attention requests based on focus-stealing prevention policy.

If the compositor accepts the request, no activate_denied event is sent. Acceptance does not guarantee immediate keyboard focus: if another surface (e.g. a layer-shell surface with exclusive keyboard interactivity) currently holds focus, the compositor places this toplevel at the head of the focus fallback queue and activates it once the exclusive focus is released. The client will observe the eventual focus grant through the normal xdg_toplevel.configure activated state.

If the compositor denies the request, it emits an activate_denied event carrying the same serial, and may set the attention flag via state_changed.

Corresponds to the Wine/Windows SetForegroundWindow API. Under X11, Wine sends a _NET_ACTIVE_WINDOW client message with source indication; this request serves the same role under Wayland.

set_attention(count: uint, timeout_ms: uint)
Argument
Type
Description
countuint
number of flashes; 0 for indefinite
timeout_msuint
desired flash interval in milliseconds; 0 for default; forwarded as a hint only
request a user attention hint (taskbar flash)

Asks the compositor to signal that this toplevel needs user attention in the taskbar or dock. This must not steal keyboard focus.

The compositor forwards this hint to the taskbar via the foreign toplevel manager protocol. Whether the taskbar honors count and timeout_ms is implementation-defined and not guaranteed by the compositor; clients must not rely on exact flash behavior.

count specifies how many times to flash. 0 means flash indefinitely until the window is activated, corresponding to FLASHW_TIMER in the Windows FlashWindowEx API.

timeout_ms specifies the desired interval between flashes in milliseconds. 0 requests the compositor or taskbar default rate. This value is forwarded as a hint only.

Sending this request replaces any currently active attention hint. To stop flashing, use clear_attention.

This request covers the taskbar/tray component (FLASHW_TRAY) of the Windows FlashWindowEx API. Title-bar caption flashing (FLASHW_CAPTION) is handled by Wine's client-side decoration layer and is outside the scope of this protocol.

Under X11, Wine sets _NET_WM_STATE_DEMANDS_ATTENTION; this request serves the same role under Wayland.

clear_attention()
cancel a user attention hint

Cancels any active attention hint set via set_attention. If no hint is active, this request has no effect.

The compositor emits a state_changed event with the attention flag cleared.

Corresponds to FlashWindowEx with FLASHW_STOP.

Argument
Type
Description
stateuint<treeland_wine_window_state_v1.state>
current state bitfield
window state flags have changed

Emitted whenever the state flags of the toplevel change.

This event is sent:

  • immediately after the treeland_wine_window_state_v1 is created, to report current state,
  • when the user or compositor minimizes or restores the window,
  • when an attention hint is set or cleared.

The state argument is a bitfield of treeland_wine_window_state_v1.state values. Flags not present in the bitfield are considered unset.

activate_denied(serial: uint)
Argument
Type
Description
serialuint
serial from the corresponding activate request
activation request was denied

Emitted when the compositor denies an activate request. The serial matches the serial field of the activate request that was denied.

The compositor may have set the attention flag via state_changed instead. The client must not retry the activation automatically.

state { minimized, attention } 
Argument
Value
Description
minimized1
the toplevel is minimized (iconified)
attention2
the toplevel is requesting user attention (taskbar flash active)
window state flags

Bitfield of window states that the compositor tracks for this toplevel. These supplement the states delivered by xdg_toplevel.configure. Keyboard focus (activated) is excluded because it is already delivered by xdg_toplevel; duplicating it here would create two conflicting sources of truth.

activate_reason { user_request, programmatic, restore } 
Argument
Value
Description
user_request0
the user explicitly asked to activate this window (e.g. taskbar click)
programmatic1
the application is activating itself (e.g. SetForegroundWindow without direct user gesture)
restore2
the window is being restored from a minimized or hidden state
reason for an activation request

Provides semantic context for an activate request so the compositor can apply appropriate focus-stealing prevention policy.


Compositor Support

No compositor support found

SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT