Treeland foreign toplevel manager v3
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.
treeland_foreign_toplevel_manager_v3
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()
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()
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_surface | object<wl_surface> | anchor surface for preview and tooltip positioning |
| id | new_id<treeland_dock_preview_context_v3> | the new dock preview context object |
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.
toplevel(toplevel: new_id<treeland_foreign_toplevel_handle_v3>)
Argument | Type | Description |
|---|---|---|
| toplevel | new_id<treeland_foreign_toplevel_handle_v3> | the new toplevel handle |
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()
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.
error { invalid_surface, context_already_exists }
Argument | Value | Description |
|---|---|---|
| invalid_surface | 0 | the relative_surface passed to get_dock_preview_context is not a valid wl_surface owned by the calling client |
| context_already_exists | 1 | 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 |
Error values raised as protocol errors on misuse of treeland_foreign_toplevel_manager_v3 requests.
treeland_foreign_toplevel_handle_v3
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 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 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 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 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 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.
Argument | Type | Description |
|---|---|---|
| output | object<wl_output>allow null | preferred output for fullscreen, or null for compositor choice |
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 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.
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()
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.
Argument | Type | Description |
|---|---|---|
| surface | object<wl_surface> | surface that contains the visual representation |
| x | int | x offset in surface-local coordinates |
| y | int | y offset in surface-local coordinates |
| width | int | width of the rectangle in surface-local coordinates |
| height | int | height of the rectangle in surface-local coordinates |
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 |
|---|---|---|
| pid | uint | process ID of the 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 |
|---|---|---|
| title | string | the current title of the toplevel |
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_id | string | the current application ID of the toplevel |
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 |
|---|---|---|
| identifier | uint | unique stable identifier for this 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.
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.
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 |
|---|---|---|
| state | array | array of active treeland_foreign_toplevel_handle_v3.state enum values encoded as uint32 |
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()
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()
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.
parent(parent: object<treeland_foreign_toplevel_handle_v3>)
Argument | Type | Description |
|---|---|---|
| parent | object<treeland_foreign_toplevel_handle_v3>allow null | the parent toplevel handle, or null if there is no parent |
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.
state { maximized, minimized, activated, fullscreen, attention }
Argument | Value | Description |
|---|---|---|
| maximized | 0 | the toplevel is maximized |
| minimized | 1 | the toplevel is minimized |
| activated | 2 | the toplevel has keyboard focus |
| fullscreen | 3 | the toplevel is fullscreen |
| attention | 4 | the toplevel is requesting user attention |
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_geometry | 0 | the provided set_icon_geometry dimensions are invalid |
Error values raised as protocol errors on misuse of treeland_foreign_toplevel_handle_v3 requests.
treeland_dock_preview_context_v3
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 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.
show(identifiers: array, x: int, y: int, direction: uint<treeland_dock_preview_context_v3.direction>)
Argument | Type | Description |
|---|---|---|
| identifiers | array | array of uint32 toplevel identifiers to preview |
| x | int | x offset of the preview popup in anchor-surface-local coordinates |
| y | int | y offset of the preview popup in anchor-surface-local coordinates |
| direction | uint<treeland_dock_preview_context_v3.direction> | which side of the anchor surface the preview appears on |
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 |
|---|---|---|
| surface | object<wl_surface> | the wl_surface to display as the tooltip content |
| x | int | x offset of the tooltip in anchor-surface-local coordinates |
| y | int | y offset of the tooltip in anchor-surface-local coordinates |
| direction | uint<treeland_dock_preview_context_v3.direction> | which side of the anchor surface the tooltip appears on |
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()
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.
show_list(identifiers: array, x: int, y: int, direction: uint<treeland_dock_preview_context_v3.direction>)
Argument | Type | Description |
|---|---|---|
| identifiers | array | array of uint32 toplevel identifiers to preview |
| x | int | x offset of the preview popup in anchor-surface-local coordinates |
| y | int | y offset of the preview popup in anchor-surface-local coordinates |
| direction | uint<treeland_dock_preview_context_v3.direction> | which side of the anchor surface the preview appears on |
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()
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()
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_surface | 0 | the wl_surface is not owned by this client, has another role, or is the anchor surface |
Error values raised as protocol errors on misuse of treeland_dock_preview_context_v3 requests.
Argument | Value | Description |
|---|---|---|
| top | 0 | preview appears above the anchor surface |
| right | 1 | preview appears to the right of the anchor surface |
| bottom | 2 | preview appears below the anchor surface |
| left | 3 | preview appears to the left of 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
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT