Treeland compositor action

compositor action triggering for treeland

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 a privileged DDE client such as the dock, the shutdown applet, or the greeter to trigger compositor actions directly, without registering a keyboard or gesture shortcut.

This protocol is independent of treeland_shortcut_manager_v3 and of any other Treeland protocol. The action values defined here form their own value space: they are not aligned with, and must not be assumed to match, the action enum of the shortcut manager. The compositor maps them to internal actions through its own table, and future versions of either protocol may add, renumber, or remove entries without regard to the other.

Following the split used by KWin, this protocol exposes only actions that are independent of the currently active window and of an in-progress keyboard task-switching sequence: workspace switching, show-desktop, the multitask overview, screen zoom, the FPS overlay, and session-level actions (lock, shutdown menu, user switch). Actions that act on the currently active window (maximize, minimize, close, move, resize, show the window menu, snap tiling, and moving a window across workspaces) and the task-switch stepping actions depend on implicit runtime state (the active window or an ongoing Alt-Tab-like sequence) and are not exposed here; they remain available only as keyboard or gesture shortcuts registered through treeland_shortcut_manager_v3. Exposing those window-level actions as a directly callable interface would let a background client manipulate a window chosen by keyboard focus rather than by explicit reference, which is the same reason KWin keeps them behind kglobalaccel instead of offering them on its DBus interface.

The compositor must reject bind attempts from non-privileged clients.

This interface is stateless: each request is an independent one-shot action. The compositor does not send events in response to these requests; clients that need to observe the resulting session state should use the appropriate session or idle protocols instead.

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

compositor action trigger

A global that exposes compositor actions to a privileged DDE client.

The compositor must reject bind attempts from non-privileged clients.

Only window-independent actions are exposed here; actions that target the currently active window or step an in-progress task switch are not part of this interface and must be triggered as shortcuts through treeland_shortcut_manager_v3. See the protocol-level description for the rationale.

All actions are triggered with the trigger request, which takes an action argument.

The compositor should ignore an action it cannot perform, for example locking while a lock screen is already active; clients must not assume an action has taken effect.

The shutdown-menu actions show the shutdown and session menu; they differ only in which menu button receives the default keyboard focus. shutdown_menu expresses no preference; the power_off, reboot, suspend, hibernate, and log_out entries request focus on the matching button. Showing the menu does not perform the power action itself; the compositor or greeter carries out the chosen action after the user confirms.

destroy()
destroy the compositor action object

Destroy the treeland_compositor_action_v1 object. This request does not alter any compositor, shell, or session state.

Argument
Type
Description
actionuint<treeland_compositor_action_v1.action>
the compositor action to trigger
trigger a compositor action

Trigger the compositor action identified by the action argument. The compositor should ignore the request when the action cannot be performed, for example locking while a lock screen is already active, or showing the shutdown menu while a lock screen is already active. Clients must not assume the action has taken effect.

The shutdown-menu actions show the menu; they do not perform the power action itself.

Argument
Value
Description
workspace_11
switch to workspace 1
workspace_22
switch to workspace 2
workspace_33
switch to workspace 3
workspace_44
switch to workspace 4
workspace_55
switch to workspace 5
workspace_66
switch to workspace 6
workspace_77
switch to workspace 7
workspace_88
switch to workspace 8
workspace_99
switch to workspace 9
workspace_1010
switch to workspace 10
workspace_1111
switch to workspace 11
workspace_1212
switch to workspace 12
prev_workspace13
switch to the previous workspace
next_workspace14
switch to the next workspace
show_desktop15
toggle show-desktop mode
open_multitask_view16
open the multitask overview
close_multitask_view17
close the multitask overview
toggle_multitask_view18
toggle the multitask overview
zoom_in19
zoom in the screen
zoom_out20
zoom out the screen
zoom_reset21
reset the screen zoom level
toggle_fps_display22
toggle the compositor FPS overlay
lockscreen23
lock the screen
shutdown_menu24
show the shutdown/session menu with no default-focus preference
show_user_switch25
show the user switch UI
shutdown_menu_power_off26
show the shutdown/session menu, focusing the power-off button
shutdown_menu_reboot27
show the shutdown/session menu, focusing the reboot button
shutdown_menu_suspend28
show the shutdown/session menu, focusing the suspend button
shutdown_menu_hibernate29
show the shutdown/session menu, focusing the hibernate button
shutdown_menu_log_out30
show the shutdown/session menu, focusing the log-out button
compositor actions

Shell actions exposed through the trigger request, limited to those independent of the currently active window.

The values are specific to this protocol. They are not aligned with the action enum of treeland_shortcut_manager_v3, and clients must not build any mapping between the two enums.

Actions that target the currently active window (maximize, minimize, close, move, resize, show the window menu, snap tiling, and moving a window across workspaces) and the task-switch stepping actions are not part of this enum; they depend on the active window or an in-progress switching sequence and are reachable only as shortcuts via treeland_shortcut_manager_v3.

Values 25-30 (show_user_switch and the focused shutdown-menu actions) have no counterpart in the shortcut manager because they are triggered by a shell client rather than a keyboard shortcut. The focused shutdown-menu entries behave like shutdown_menu but request default focus on the matching button.


Compositor Support

No compositor support found

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