Treeland foreign toplevel manager v2

manage foreign toplevel windows

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.

This protocol allows privileged clients such as dock or taskbar components to observe and manage toplevel windows on behalf of the compositor. It provides access to window metadata (title, app-id, state, parent, outputs), allows requests to maximize, minimize, activate, close, or fullscreen a toplevel, and supports a dock preview context for thumbnail display and tooltip overlays.

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

observe and manage toplevel windows

A singleton global that emits one treeland_foreign_toplevel_handle_v2 object per mapped toplevel window. Clients bind this global to receive the toplevel event stream and to create dock preview contexts.

A toplevel is defined as a surface with a role similar to xdg_toplevel. XWayland surfaces may be treated like toplevels in this protocol.

Clients which only care about the current state can perform a roundtrip after binding this global.

The typical lifecycle is: 1. Client binds treeland_foreign_toplevel_manager_v2. 2. Compositor emits a toplevel event for each already-mapped toplevel, followed by individual property events and a done event on each handle. 3. As windows appear and disappear the compositor emits further toplevel events and closed events on the corresponding handles. 4. When the client no longer needs the manager it sends stop, waits for the finished event, destroys the handles, and then the manager itself. Outstanding handles remain usable until the client destroys them individually.

destroy()
destroy the manager object

This request should be called either when the client will no longer use the manager, or after the finished event has been received.

If a client wishes to destroy this object it should send a stop request and wait for a finished event, then destroy the handles and then this object.

Existing treeland_foreign_toplevel_handle_v2 objects created through this manager are not affected and must be destroyed separately by the client.

stop()
stop sending events

This request indicates that the client no longer wishes to receive events for new toplevels.

The Wayland protocol is asynchronous, meaning the compositor may send further toplevel events until the stop request is processed. The client should wait for a finished event before destroying this object.

get_dock_preview_context(relative_surface: object<wl_surface>, id: new_id<treeland_dock_preview_context_v2>)
Argument
Type
Description
relative_surfaceobject<wl_surface>
anchor surface for preview and tooltip positioning
idnew_id<treeland_dock_preview_context_v2>
the new dock preview context object
create a dock preview context for a surface

Create a treeland_dock_preview_context_v2 associated with the given surface. The surface must be a valid wl_surface owned by the calling client and serves as the anchor for all preview and tooltip positioning.

Only one dock preview context may be active per surface at a time. If the surface already has an active context, the client must destroy it via treeland_dock_preview_context_v2.destroy before creating a new one; otherwise the compositor raises the context_already_exists protocol error and does not create the requested object.

Argument
Type
Description
toplevelnew_id<treeland_foreign_toplevel_handle_v2>
the new toplevel handle
a toplevel window has been mapped

Emitted by the compositor whenever a new toplevel window is mapped. The event is sent for all toplevels regardless of which application created them.

Immediately after this event the compositor will send the initial property events (title, app_id, pid, identifier, state, output_enter, parent, and so on) on the new handle, followed by a done event. The client should treat all property events received before the first done as the initial snapshot.

finished()
the compositor has finished with the toplevel manager

This event indicates that the compositor is done sending events to this object. The client should destroy the object. See treeland_foreign_toplevel_manager_v2.destroy for more information.

The compositor must not send any more toplevel events after this event.

Outstanding treeland_foreign_toplevel_handle_v2 objects are not affected by this event.

Argument
Value
Description
invalid_surface0
the relative_surface passed to get_dock_preview_context is not a valid wl_surface owned by the calling client
context_already_exists1
get_dock_preview_context was called for a surface that already has an active dock preview context; the client must destroy the existing context first
protocol errors for this interface

Error values raised as protocol errors on misuse of treeland_foreign_toplevel_manager_v2 requests.


handle for a foreign toplevel window

Represents a single mapped toplevel window. The compositor creates this object in response to the manager's toplevel event and destroys the server-side resource when the window is unmapped (signalled by the closed event).

After the compositor sends closed, the client must not send any requests other than destroy. The client should call destroy promptly after receiving closed to release compositor-side tracking state.

All property events (title, app_id, pid, identifier, output_enter, output_leave, state, parent) are grouped by a trailing done event so that a batch of related changes appears atomic to the client.

destroy()
destroy the handle object

Destroy the treeland_foreign_toplevel_handle_v2 object and release all associated client-side resources.

This request may be sent at any time, including before the compositor sends the closed event. When sent after closed, it finalizes the destruction sequence initiated by the compositor. When sent before closed, the compositor will silently drop any further events for this handle.

When a handle is destroyed, a new handle may not be created by the compositor until the toplevel is unmapped and then remapped. Destroying a toplevel handle is not recommended unless the client is cleaning up child objects before destroying the manager, the toplevel was closed, or the handle will not be used in the future.

Other protocols which extend the treeland_foreign_toplevel_handle_v2 interface should require destructors for extension interfaces to be called before allowing the toplevel handle to be destroyed.

set_maximized()
request that the toplevel be maximized

Request that the compositor maximize the toplevel. The compositor may ignore the request. If the maximized state changes, the compositor will reflect this in a subsequent state event followed by done.

unset_maximized()
request that the toplevel be unmaximized

Request that the compositor restore the toplevel from the maximized state. The compositor may ignore the request. If the state changes, it is reflected via state and done events.

set_minimized()
request that the toplevel be minimized

Request that the compositor minimize the toplevel. The compositor may ignore the request. If the minimized state changes, the compositor will reflect this in a subsequent state event followed by done.

unset_minimized()
request that the toplevel be unminimized

Request that the compositor restore the toplevel from the minimized state. The compositor may ignore the request. If the state changes, it is reflected via state and done events.

set_fullscreen(output: object<wl_output>)
Argument
Type
Description
outputobject<wl_output>allow null
preferred output for fullscreen, or null for compositor choice
request that the toplevel enter fullscreen

Request that the compositor fullscreen the toplevel on the given output. If output is null, the compositor chooses the output. The output argument is a hint only; the compositor may fullscreen on a different output or not at all.

If the fullscreen state or visible outputs change, the compositor will reflect this via state and output_enter / output_leave events followed by done.

unset_fullscreen()
request that the toplevel leave fullscreen

Request that the compositor exit the fullscreen state for the toplevel. The compositor may ignore the request. If the state changes, it is reflected via state and done events.

activate(seat: object<wl_seat>)
Argument
Type
Description
seatobject<wl_seat>
the seat on which to activate the toplevel
request that the toplevel be activated

Request that the compositor give keyboard focus to the toplevel on the given seat. There is no guarantee the toplevel will actually be activated; the compositor may ignore the request based on seat focus policy or security considerations.

close()
request that the toplevel close itself

Send a close request to the toplevel. The compositor typically forwards this to the application using a shell-specific mechanism such as xdg_toplevel.close. There is no guarantee the application will honour the request. If the toplevel is eventually unmapped, the compositor will emit the closed event on this handle.

set_icon_geometry(surface: object<wl_surface>, x: int, y: int, width: int, height: int)
Argument
Type
Description
surfaceobject<wl_surface>
surface that contains the visual representation
xint
x offset in surface-local coordinates
yint
y offset in surface-local coordinates
widthint
width of the rectangle in surface-local coordinates
heightint
height of the rectangle in surface-local coordinates
set the icon geometry of the toplevel

Inform the compositor of the rectangle on surface that visually represents this toplevel (for example the taskbar icon or thumbnail), similar to the EWMH _NET_WM_ICON_GEOMETRY property. The compositor may use this as a hint for minimize animations or similar effects.

The client is not required to set this geometry. If unset, the compositor applies an implementation-defined default. If the client sets multiple rectangles, only the last one takes effect.

Coordinates are in surface-local space of the given surface. Setting width = height = 0 removes a previously set geometry.

The compositor raises the invalid_geometry error if the provided dimensions are otherwise out of range.

pid(pid: uint)
Argument
Type
Description
piduint
process ID of the application
process ID of the owning application

Emitted by the compositor when it knows the process ID of the application that owns this toplevel. This event is sent once as part of the initial property snapshot, before the first done event, and is not re-sent unless the owning process changes.

title(title: string)
Argument
Type
Description
titlestring
the current title of the toplevel
toplevel title has changed

Emitted whenever the title of the toplevel changes. The initial title is sent as part of the snapshot before the first done event.

app_id(app_id: string)
Argument
Type
Description
app_idstring
the current application ID of the toplevel
toplevel app-id has changed

Emitted whenever the app-id of the toplevel changes. The initial app-id is sent as part of the snapshot before the first done event.

identifier(identifier: uint)
Argument
Type
Description
identifieruint
unique stable identifier for this toplevel
a stable identifier for a toplevel

This identifier is used to check if two or more toplevel handles belong to the same toplevel.

The identifier is useful for command line tools or privileged clients which may need to reference an exact toplevel across processes or instances of the treeland_foreign_toplevel_manager_v2 global.

The compositor sends this event exactly once, when the handle is created, as part of the initial property snapshot.

The identifier must be unique per toplevel and its handles. Two different toplevels must not have the same identifier. The identifier is only valid as long as the toplevel is mapped. If the toplevel is unmapped the identifier must not be reused. An identifier must not be reused by the compositor to ensure there are no races when sharing identifiers between processes.

output_enter(output: object<wl_output>)
Argument
Type
Description
outputobject<wl_output>
the output the toplevel entered
toplevel is now visible on an output

Emitted when the toplevel becomes visible on the given output. A toplevel may be visible on multiple outputs simultaneously. This event is sent as part of the initial snapshot and whenever the set of visible outputs changes.

output_leave(output: object<wl_output>)
Argument
Type
Description
outputobject<wl_output>
the output the toplevel left
toplevel is no longer visible on an output

Emitted when the toplevel stops being visible on the given output. A corresponding output_enter event for the same output is guaranteed to have been sent before this event.

state(state: array)
Argument
Type
Description
statearray
array of active treeland_foreign_toplevel_handle_v2.state enum values encoded as uint32
toplevel state has changed

Emitted immediately after the handle is created as part of the initial property snapshot, and again each time the toplevel state changes due to a compositor action or a client request on this protocol.

The state argument is an array of uint32 values, each corresponding to an entry in the treeland_foreign_toplevel_handle_v2.state enum. An entry is present in the array when the corresponding state is active.

done()
all pending property changes have been sent

Emitted after the compositor has sent all property events for the current atomic update batch (title, app_id, pid, identifier, state, output_enter, output_leave, parent). The client should process the preceding events as a single coherent state snapshot only upon receiving done.

This allows changes to the treeland_foreign_toplevel_handle_v2 properties to be atomically applied. Other protocols which extend the treeland_foreign_toplevel_handle_v2 interface may use this event to also atomically apply any pending state.

This event must not be sent after the treeland_foreign_toplevel_handle_v2.closed event.

closed()
the toplevel window has been unmapped

Emitted when the toplevel is unmapped or destroyed by the compositor. No further property events will be sent on this handle after closed. The handle becomes inert; the client must not send any requests except destroy, which it should call promptly to release compositor-side tracking resources.

Other protocols which extend the treeland_foreign_toplevel_handle_v2 interface must also ignore requests other than their destructors.

Argument
Type
Description
parentobject<treeland_foreign_toplevel_handle_v2>allow null
the parent toplevel handle, or null if there is no parent
parent toplevel has changed

Emitted whenever the parent-child relationship of this toplevel changes. The parent arg is null when the toplevel has no parent (i.e. it is a top-level root window).

This event is not re-sent when the client destroys the parent handle; the relationship on the compositor side is unchanged by client-side destruction of the parent object.

Argument
Value
Description
maximized0
the toplevel is maximized
minimized1
the toplevel is minimized
activated2
the toplevel has keyboard focus
fullscreen3
the toplevel is fullscreen
attention4
the toplevel is requesting user attention
toplevel window state flags

Flags that describe the current state of a toplevel window. These correspond to the states with the same names defined in the xdg-toplevel interface. Each flag is encoded as a uint32 value in the array sent by the state event.

error { invalid_geometry } 
Argument
Value
Description
invalid_geometry0
the provided set_icon_geometry dimensions are invalid
protocol errors for this interface

Error values raised as protocol errors on misuse of treeland_foreign_toplevel_handle_v2 requests.


dock preview and tooltip context for a surface

Provides the dock or taskbar component with the ability to display a thumbnail preview of one or more toplevels and to show tooltip overlays, both positioned relative to the anchor surface supplied to get_dock_preview_context.

The object is created by treeland_foreign_toplevel_manager_v2.get_dock_preview_context and is valid until the client calls destroy. The compositor emits enter and leave events when the pointer enters or leaves the active preview area.

destroy()
destroy the dock preview context

Destroy the treeland_dock_preview_context_v2 object and release all associated compositor resources. Any visible preview or tooltip is hidden immediately. After this request the compositor will no longer send any event.

Argument
Type
Description
identifiersarray
array of uint32 toplevel identifiers to preview
xint
x offset of the preview popup in anchor-surface-local coordinates
yint
y offset of the preview popup in anchor-surface-local coordinates
directionuint<treeland_dock_preview_context_v2.direction>
which side of the anchor surface the preview appears on
show a thumbnail preview of the given toplevels

Request that the compositor display thumbnail previews for the toplevels identified by the identifiers array. The popup is positioned at (x, y) in the coordinate space of the anchor surface supplied at context creation, on the side indicated by direction.

The identifiers argument is a wl_array of uint32 identifier values, each matching the identifier sent by the treeland_foreign_toplevel_handle_v2.identifier event. The compositor ignores identifiers that do not correspond to a currently mapped toplevel.

Calling show while a preview is already visible replaces the previous content atomically.

show_tooltip(tooltip: string, x: int, y: int, direction: uint<treeland_dock_preview_context_v2.direction>)
Argument
Type
Description
tooltipstring
UTF-8 text to display in the tooltip
xint
x offset of the tooltip in anchor-surface-local coordinates
yint
y offset of the tooltip in anchor-surface-local coordinates
directionuint<treeland_dock_preview_context_v2.direction>
which side of the anchor surface the tooltip appears on
show a tooltip near the anchor surface

Request that the compositor display a text tooltip at (x, y) in the coordinate space of the anchor surface, on the side indicated by direction. Any previously visible tooltip from this context is replaced.

Calling show_tooltip while a preview is visible does not hide the preview; both may be visible simultaneously depending on compositor policy.

close()
hide the preview popup

Request that the compositor hide the currently visible preview popup. If no preview is visible this request is a no-op. The tooltip, if any, is not affected.

enter()
pointer entered the preview area

Emitted when the pointer device enters the active preview popup area managed by this context. The compositor sends this event only while a preview is visible (i.e. after show and before close or destroy).

leave()
pointer left the preview area

Emitted when the pointer device leaves the active preview popup area managed by this context. A corresponding enter event is guaranteed to have been sent before this event.

direction { top, right, bottom, left } 
Argument
Value
Description
top0
preview appears above the anchor surface
right1
preview appears to the right of the anchor surface
bottom2
preview appears below the anchor surface
left3
preview appears to the left of the anchor surface
position of the preview relative to the anchor surface

Specifies on which side of the anchor surface the preview popup or tooltip should appear. The compositor uses this value as a placement hint; it may choose a different side if the requested side would be clipped by the screen edge.


Compositor Support

No compositor support found

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