Treeland foreign toplevel manager v3

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 or list 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_v3 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_v3. 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_v3 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_v3>)
Argument
Type
Description
relative_surfaceobject<wl_surface>
anchor surface for preview and tooltip positioning
idnew_id<treeland_dock_preview_context_v3>
the new dock preview context object
create a dock preview context for a surface

Create a treeland_dock_preview_context_v3 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_v3.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_v3>
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_v3.destroy for more information.

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

Outstanding treeland_foreign_toplevel_handle_v3 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_v3 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_v3 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_v3 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_v3 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_v3.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_v3.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_v3 properties to be atomically applied. Other protocols which extend the treeland_foreign_toplevel_handle_v3 interface may use this event to also atomically apply any pending state.

This event must not be sent after the treeland_foreign_toplevel_handle_v3.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_v3 interface must also ignore requests other than their destructors.

Argument
Type
Description
parentobject<treeland_foreign_toplevel_handle_v3>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_v3 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 a client-drawn tooltip surface, both positioned relative to the anchor surface supplied to get_dock_preview_context.

The object is created by treeland_foreign_toplevel_manager_v3.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.

The preview and the tooltip share one popover slot: showing either one replaces whatever the context displayed before.

Version 2 adds the show_list request, which shows the same preview as show but asks for a vertical list of rows instead of thumbnails. show keeps its thumbnail meaning in both versions.

destroy()
destroy the dock preview context

Destroy the treeland_dock_preview_context_v3 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_v3.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.

This request always asks for the thumbnail presentation. A client that wants the list presentation sends show_list instead, which takes the same arguments.

The identifiers argument is a wl_array of uint32 identifier values, each matching the identifier sent by the treeland_foreign_toplevel_handle_v3.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. If a tooltip is visible, the preview replaces it as well: the tooltip is hidden.

show_tooltip_surface(surface: object<wl_surface>, x: int, y: int, direction: uint<treeland_dock_preview_context_v3.direction>)
Argument
Type
Description
surfaceobject<wl_surface>
the wl_surface to display as the tooltip content
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_v3.direction>
which side of the anchor surface the tooltip appears on
show a client-drawn tooltip surface

Display the given surface as the tooltip of this context, at (x, y) in the coordinate space of the anchor surface and on the side indicated by direction. The compositor computes the final position from these values and may move the tooltip to keep it on the output; clients must not assume the request is honored exactly. Any tooltip this context displayed before is replaced.

The compositor draws its popover frame (tint, border, shadow) exactly behind the surface and uses the surface's committed logical size as the tooltip size. There is no extra padding on any side: the client is responsible for its own inner padding and for keeping its content inside the rounded corners. The client provides content only and must not draw its own popover background, otherwise it covers the frame the compositor draws.

The surface must already have a committed buffer when this request is sent. A surface without content is a client error: the compositor shows nothing for that request. Asking for a surface that is already shown, with the same or a new position, is allowed and needs no further commit; commits after the tooltip is shown update its content.

A request for a surface other than the one this context already shows replaces the tooltip, and the compositor may animate the switch, shrinking and fading out the replaced tooltip into the new one. Showing the surface this context already shows is not a replacement: the compositor keeps drawing that one surface, moved to the new position, and plays no animation, even when the surface committed different content in the meantime. A client that wants a transition between two tooltips therefore has to put them on separate surfaces; one surface repainted in place changes the tooltip without animating.

This request assigns a compositor-side role to the surface, so the surface must be owned by the calling client and must not have any other role yet; the anchor surface of this context cannot be used either. Otherwise the compositor raises invalid_surface. The role is never released: once a surface has been shown as a tooltip it can only be shown as a tooltip again. The compositor does not scale the tooltip; if it does not fit on the output it may be clipped.

The surface receives no pointer or keyboard input, no focus and no activation. It is owned by the client: the compositor only stops using it and never destroys it.

close()
hide the popover

Request that the compositor hide the currently visible popover, that is the preview popup and the tooltip surface alike. If nothing is visible this request is a no-op.

A hidden tooltip is not destroyed and keeps the role of its surface; the client shows it again with another show_tooltip_surface request.

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_v3.direction>
which side of the anchor surface the preview appears on
show a list preview of the given toplevels

Behaves exactly like show, except that the compositor presents the toplevels as a vertical list of rows, one row per toplevel, instead of thumbnails side by side.

The arguments and the popup placement are the same as show, and the two requests replace each other exactly like two calls of show do.

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.

error { invalid_surface } 
Argument
Value
Description
invalid_surface0
the wl_surface is not owned by this client, has another role, or is the anchor surface
protocol errors for this interface

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

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