Treeland compositor action
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.
treeland_compositor_action_v1
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 treeland_compositor_action_v1 object. This request does not alter any compositor, shell, or session state.
trigger(action: uint<treeland_compositor_action_v1.action>)
Argument | Type | Description |
|---|---|---|
| action | uint<treeland_compositor_action_v1.action> | the compositor action to trigger |
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.
action { workspace_1, workspace_2, workspace_3, workspace_4, workspace_5, workspace_6, workspace_7, workspace_8, workspace_9, workspace_10, workspace_11, workspace_12, prev_workspace, next_workspace, show_desktop, open_multitask_view, close_multitask_view, toggle_multitask_view, zoom_in, zoom_out, zoom_reset, toggle_fps_display, lockscreen, shutdown_menu, show_user_switch, shutdown_menu_power_off, shutdown_menu_reboot, shutdown_menu_suspend, shutdown_menu_hibernate, shutdown_menu_log_out }
Argument | Value | Description |
|---|---|---|
| workspace_1 | 1 | switch to workspace 1 |
| workspace_2 | 2 | switch to workspace 2 |
| workspace_3 | 3 | switch to workspace 3 |
| workspace_4 | 4 | switch to workspace 4 |
| workspace_5 | 5 | switch to workspace 5 |
| workspace_6 | 6 | switch to workspace 6 |
| workspace_7 | 7 | switch to workspace 7 |
| workspace_8 | 8 | switch to workspace 8 |
| workspace_9 | 9 | switch to workspace 9 |
| workspace_10 | 10 | switch to workspace 10 |
| workspace_11 | 11 | switch to workspace 11 |
| workspace_12 | 12 | switch to workspace 12 |
| prev_workspace | 13 | switch to the previous workspace |
| next_workspace | 14 | switch to the next workspace |
| show_desktop | 15 | toggle show-desktop mode |
| open_multitask_view | 16 | open the multitask overview |
| close_multitask_view | 17 | close the multitask overview |
| toggle_multitask_view | 18 | toggle the multitask overview |
| zoom_in | 19 | zoom in the screen |
| zoom_out | 20 | zoom out the screen |
| zoom_reset | 21 | reset the screen zoom level |
| toggle_fps_display | 22 | toggle the compositor FPS overlay |
| lockscreen | 23 | lock the screen |
| shutdown_menu | 24 | show the shutdown/session menu with no default-focus preference |
| show_user_switch | 25 | show the user switch UI |
| shutdown_menu_power_off | 26 | show the shutdown/session menu, focusing the power-off button |
| shutdown_menu_reboot | 27 | show the shutdown/session menu, focusing the reboot button |
| shutdown_menu_suspend | 28 | show the shutdown/session menu, focusing the suspend button |
| shutdown_menu_hibernate | 29 | show the shutdown/session menu, focusing the hibernate button |
| shutdown_menu_log_out | 30 | show the shutdown/session menu, focusing the log-out button |
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
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT