foreign toplevel manager

This interface allows a client to get toplevel some info.

Warning! The protocol described in this file is currently in the testing phase. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes can only be done by creating a new major version of the extension.

stop()
Stop sending events

Indicates the client no longer wishes to receive events for new toplevels. However the compositor may emit further toplevel_created events, until the finished event is emitted.

The client must not send any more requests after this one.

Argument
Type
Description
toplevelnew_id<treeland_foreign_toplevel_handle_v1>
a toplevel has been created

This event is emitted whenever a new toplevel window is created. It is emitted for all toplevels, regardless of the app that has created them.

All initial details of the toplevel(title, app_id, states, etc.) will be sent immediately after this event via the corresponding events in treeland_foreign_toplevel_handle_v1.

finished()
the compositor has finished with the toplevel manager

This event indicates that the compositor is done sending events to the treeland_foreign_toplevel_manager_v1. The server will destroy the object immediately after sending this request, so it will become invalid and the client should free any resources associated with it.


An opened toplevel

A treeland_foreign_toplevel_handle_v1 object represents an opened toplevel window. Each app may have multiple opened toplevels.

Warning! The protocol described in this file is currently in the testing phase. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes can only be done by creating a new major version of the extension.

set_maximized()
requests that the toplevel be maximized

Requests that the toplevel be maximized. If the maximized state actually changes, this will be indicated by the state event.

unset_maximized()
requests that the toplevel be unmaximized

Requests that the toplevel be unmaximized. If the maximized state actually changes, this will be indicated by the state event.

set_minimized()
requests that the toplevel be minimized

Requests that the toplevel be minimized. If the minimized state actually changes, this will be indicated by the state event.

unset_minimized()
requests that the toplevel be unminimized

Requests that the toplevel be unminimized. If the minimized state actually changes, this will be indicated by the state event.

activate(seat: object<wl_seat>)
Argument
Type
Description
seatobject<wl_seat>
activate the toplevel

Request that this toplevel be activated on the given seat. There is no guarantee the toplevel will be actually activated.

close()
request that the toplevel be closed

Send a request to the toplevel to close itself. The compositor would typically use a shell-specific method to carry out this request, for example by sending the xdg_toplevel.close event. However, this gives no guarantees the toplevel will actually be destroyed. If and when this happens, the treeland_foreign_toplevel_handle_v1.closed event will be emitted.

set_rectangle(surface: object<wl_surface>, x: int, y: int, width: int, height: int)
Argument
Type
Description
surfaceobject<wl_surface>
xint
yint
widthint
heightint
the rectangle which represents the toplevel

The rectangle of the surface specified in this request corresponds to the place where the app using this protocol represents the given toplevel. It can be used by the compositor as a hint for some operations, e.g minimizing. The client is however not required to set this, in which case the compositor is free to decide some default value.

If the client specifies more than one rectangle, only the last one is considered.

The dimensions are given in surface-local coordinates. Setting width=height=0 removes the already-set rectangle.

destroy()
destroy the treeland_foreign_toplevel_handle_v1 object

Destroys the treeland_foreign_toplevel_handle_v1 object.

This request should be called either when the client does not want to use the toplevel anymore or after the closed event to finalize the destruction of the object.

set_fullscreen(output: object<wl_output>)
Argument
Type
Description
outputobject<wl_output>allow null
request that the toplevel be fullscreened

Requests that the toplevel be fullscreened on the given output. If the fullscreen state and/or the outputs the toplevel is visible on actually change, this will be indicated by the state and output_enter/leave events.

The output parameter is only a hint to the compositor. Also, if output is NULL, the compositor should decide which output the toplevel will be fullscreened on, if at all.

unset_fullscreen()
request that the toplevel be unfullscreened

Requests that the toplevel be unfullscreened. If the fullscreen state actually changes, this will be indicated by the state event.

pid(pid: uint)
Argument
Type
Description
piduint
Process id of application owning the window has changed

This event will be sent when the compositor has set the process id this window belongs to. This should be set once before the initial_state is sent.

title(title: string)
Argument
Type
Description
titlestring
title change

This event is emitted whenever the title of the toplevel changes.

app_id(app_id: string)
Argument
Type
Description
app_idstring
app-id change

This event is emitted whenever the app-id of the toplevel changes.

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

The identifier of each top level and its handle must be unique. Two different top layers cannot have the same identifier. This identifier is only valid as long as the top level is mapped. Identifiers must not be reused if the top level is not mapped. The compositor must not reuse identifiers to ensure there are no races when identifiers are shared between processes.

output_enter(output: object<wl_output>)
Argument
Type
Description
outputobject<wl_output>
toplevel entered an output

This event is emitted whenever the toplevel becomes visible on the given output. A toplevel may be visible on multiple outputs.

output_leave(output: object<wl_output>)
Argument
Type
Description
outputobject<wl_output>
toplevel left an output

This event is emitted whenever the toplevel stops being visible on the given output. It is guaranteed that an entered-output event with the same output has been emitted before this event.

state(state: array)
Argument
Type
Description
statearray
the toplevel state changed

This event is emitted immediately after the treeland_foreign_toplevel_handle_v1 is created and each time the toplevel state changes, either because of a compositor action or because of a request in this protocol.

done()
all information about the toplevel has been sent

This event is sent after all changes in the toplevel state have been sent.

This allows changes to the treeland_foreign_toplevel_handle_v1 properties to be seen as atomic, even if they happen via multiple events.

closed()
this toplevel has been destroyed

This event means the toplevel has been destroyed. It is guaranteed there won't be any more events for this treeland_foreign_toplevel_handle_v1. The toplevel itself becomes inert so any requests will be ignored except the destroy request.

Argument
Type
Description
parentobject<treeland_foreign_toplevel_handle_v1>allow null
parent change

This event is emitted whenever the parent of the toplevel changes.

No event is emitted when the parent handle is destroyed by the client.

Argument
Value
Description
maximized0
the toplevel is maximized
minimized1
the toplevel is minimized
activated2
the toplevel is active
fullscreen3
the toplevel is fullscreen
types of states on the toplevel

The different states that a toplevel can have. These have the same meaning as the states with the same names defined in xdg-toplevel

Argument
Value
Description
invalid_rectangle0
the provided rectangle is invalid

handle dock preview

This interface allows dock set windows preview.

Warning! The protocol described in this file is currently in the testing phase. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes can only be done by creating a new major version of the extension.

show(surfaces: array, x: int, y: int, direction: uint)
Argument
Type
Description
surfacesarray
xint
yint
directionuint
set preview surfaces

X and Y are relative to the relative_surface. surfaces wl_array is identifiers.

show_tooltip(tooltip: string, x: int, y: int, direction: uint)
Argument
Type
Description
tooltipstring
xint
yint
directionuint
close()
close preview box

close preview box

destroy()
destroy the context object

Destroy the context object.

enter()
enter preview box

This event is sent after mouse enter preview box.

leave()
leave preview box

This event is sent after mouse leave preview box.

direction { top, right, bottom, left } 
Argument
Value
Description
top0
top
right1
right
bottom2
bottom
left3
left
types of direction on the dock preview

Compositor Support

Mutter
Mutter
47.3
KWin
KWin
6.3
Sway
Sway
1.10
COSMIC
COSMIC
0.1
Hyprland
Hyprland
0.44
niri
25.02
Weston
Weston
14
Mir
Mir
2.19
GameScope
GameScope
3.15.14
Jay
1.9.0
Labwc
Labwc
0.8.2
Wayfire
Wayfire
0.9.0
Treeland
Treeland
0.5.17
Louvre
Louvre
2.14.1
treeland_foreign_toplevel_manager_v1
x
x
x
x
x
x
x
x
x
x
x
x
1
x

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