Treeland shortcut 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 to register and manage global shortcuts for keyboard key sequences, touch swipe gestures, and touch hold gestures. It also provides a one-shot shortcut capture facility for clients that need to read the next shortcut input from the user.
Global shortcuts are managed in a per-user context. Shortcuts for different users are isolated and will not interfere with each other. This behavior is transparent to clients of this interface.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
treeland_shortcut_manager_v3
A singleton global that manages global shortcut bindings for key sequences, swipe gestures, and hold gestures.
Before registering or removing bindings the client must acquire exclusive control by sending the acquire request. Only one client may hold the manager at a time within a given user session.
Bindings are registered via bind_key, bind_swipe_gesture, and bind_hold_gesture, and removed via unbind. All of these requests take effect immediately. A bind request that cannot be applied is reported with a bind_failure event; successful bind and unbind requests generate no event, and the client can use the wl_display.sync request to confirm that earlier requests have been processed.
If the client's user session is not the currently active session, bind and unbind requests are deferred: they are applied when that session becomes active again.
Destroying the manager object implicitly releases the exclusive control acquired via acquire; no separate release request is needed.
The capture_next_shortcut request is independent of acquire and may be sent at any time.
destroy()
Destroy the shortcut manager object. If the client currently holds exclusive control via acquire, that control is implicitly released so another client may acquire it. Existing shortcut bindings registered by this client remain active in the compositor until the compositor or another client removes them.
acquire()
Acquire exclusive control of the shortcut manager for this client. The client must send this request before any bind_key, bind_swipe_gesture, bind_hold_gesture, or unbind request. Sending those requests without first acquiring is a protocol error (not_acquired).
Only one client may hold the manager at a time within a given user session. If another client already holds it, the compositor sends a protocol error (occupied).
Exclusive control is released implicitly when the client destroys the manager object.
bind_key(name: string, key: string, flags: uint<treeland_shortcut_manager_v3.keybind_flag>, action: uint<treeland_shortcut_manager_v3.action>)
Argument | Type | Description |
|---|---|---|
| name | string | unique name for this keybinding |
| key | string | key sequence in QKeySequence portable text format |
| flags | uint<treeland_shortcut_manager_v3.keybind_flag> | trigger conditions for this keybinding |
| action | uint<treeland_shortcut_manager_v3.action> | compositor action to execute on activation |
Register a key sequence binding. The binding takes effect immediately.
The key argument uses the portable textual format of QKeySequence (PortableText); see https://doc.qt.io/qt-6/qkeysequence.html#toString for the format specification. Only combinations that form a valid shortcut can be registered; see the capture_next_shortcut request for the validity rules. An invalid combination is reported with bind_failure and the invalid_argument error.
The name argument must be unique among all existing bindings. If a binding with the same name already exists, this request is reported with bind_failure and the name_conflict error.
If a binding with the same key sequence and action already exists, this request updates its flags to the new value rather than failing. This upsert-on-trigger semantics applies only to bind_key; bind_swipe_gesture and bind_hold_gesture treat duplicate trigger-action pairs as errors.
Sending this request without first acquiring is a protocol error (not_acquired).
bind_swipe_gesture(name: string, finger: uint, direction: uint<treeland_shortcut_manager_v3.direction>, action: uint<treeland_shortcut_manager_v3.action>)
Argument | Type | Description |
|---|---|---|
| name | string | unique name for this swipe gesture binding |
| finger | uint | number of fingers required for the swipe |
| direction | uint<treeland_shortcut_manager_v3.direction> | required swipe direction |
| action | uint<treeland_shortcut_manager_v3.action> | compositor action to execute on activation |
Register a swipe gesture binding. The binding takes effect immediately.
The name argument must be unique among all existing bindings. If a binding with the same name already exists, this request is reported with bind_failure and the name_conflict error.
If a binding with the same finger count, direction, and action already exists, this request is reported with bind_failure and the duplicate_binding error.
If direction is not one of the defined direction enum values, this request is reported with bind_failure and the invalid_argument error.
Sending this request without first acquiring is a protocol error (not_acquired).
bind_hold_gesture(name: string, finger: uint, action: uint<treeland_shortcut_manager_v3.action>)
Argument | Type | Description |
|---|---|---|
| name | string | unique name for this hold gesture binding |
| finger | uint | number of fingers required for the hold |
| action | uint<treeland_shortcut_manager_v3.action> | compositor action to execute on activation |
Register a hold gesture binding. The binding takes effect immediately.
The name argument must be unique among all existing bindings. If a binding with the same name already exists, this request is reported with bind_failure and the name_conflict error.
If a binding with the same finger count and action already exists, this request is reported with bind_failure and the duplicate_binding error.
Sending this request without first acquiring is a protocol error (not_acquired).
unbind(name: string)
Argument | Type | Description |
|---|---|---|
| name | string | name of the binding to remove |
Remove the binding identified by name. The removal takes effect immediately. If no binding with the given name exists, this request is silently ignored.
Sending this request without first acquiring is a protocol error (not_acquired).
capture_next_shortcut(surface: object<wl_surface>, seat: object<wl_seat>, capture: new_id<treeland_shortcut_capture_v3>)
Argument | Type | Description |
|---|---|---|
| surface | object<wl_surface> | surface used to validate keyboard focus |
| seat | object<wl_seat>allow null | seat to capture from, or null to capture from any available seat |
| capture | new_id<treeland_shortcut_capture_v3> | one-shot capture object |
Create a treeland_shortcut_capture_v3 object and start a one-shot capture of the next shortcut input. This request does not require acquire and does not modify existing bindings.
The surface argument must be a wl_surface owned by the requesting client. If it is not, the compositor sends a protocol error (invalid_surface).
The compositor handles at most one capture at a time, regardless of which client requested it. A capture is also considered in progress until the compositor has consumed the key_release of the last captured key, so that the release cannot trigger a shortcut bound in the meantime. If a capture is already in progress, the compositor emits failed with reason busy on the newly created object immediately after creation.
If the seat argument is not null, the compositor verifies that the keyboard focus of that seat is on the surface. If the seat argument is null, the compositor selects a seat whose keyboard focus is on the surface. If no seat has keyboard focus on the surface, the compositor emits failed with reason not_active on the newly created object immediately after creation. Clients must be prepared to handle a capture object that fails immediately.
Input from seats other than the validated seat is not intercepted and is processed normally. On the validated seat the capture intercepts input with priority over registered shortcut bindings.
While the capture is pending, input from the validated seat is handled as follows. If the surface loses keyboard focus, the compositor emits failed with reason aborted and lets the current event continue to its new focus target. Auto-repeat events are consumed silently. A pointer button or wheel event terminates the capture with reason interrupted and is consumed. A key_press of a pure modifier key (Ctrl, Alt, Shift, and similar) is consumed silently; its key_release terminates the capture with reason interrupted, unless the key is the Meta (Super) key: releasing Meta with no other modifier held emits captured with the shortcut "Meta". A key_press of any other key terminates the capture immediately on the press. If the pressed combination is a valid shortcut the compositor emits captured and consumes the key_release that follows; otherwise it emits failed with reason interrupted. In the captured and interrupted cases the triggering input event is consumed and not forwarded to any client.
A valid shortcut is one of: a non-modifier key combined with Ctrl, Alt, or Meta; a standalone function key (F1 to F35); a standalone key such as Delete, Backspace, Pause, Print, Insert, Help, Menu, or Cancel; Shift combined with Space, Escape, Tab, or a navigation key (Home, End, PageUp, PageDown, and arrows); a standalone media, browser, brightness, or launch key; or the Meta (Super) key pressed alone. An unmodified alphanumeric key and an unmodified Escape are not valid shortcuts.
activated(name: string, flags: uint<treeland_shortcut_manager_v3.keybind_flag>)
Argument | Type | Description |
|---|---|---|
| name | string | name of the activated binding |
| flags | uint<treeland_shortcut_manager_v3.keybind_flag> | key event type that triggered activation |
Emitted when a binding registered with action notify is activated. The name argument identifies the binding by its unique name. The flags argument indicates which key event triggered the activation, using the keybind_flag enum values.
bind_failure(name: string, error: uint<treeland_shortcut_manager_v3.bind_error>)
Argument | Type | Description |
|---|---|---|
| name | string | name of the rejected binding |
| error | uint<treeland_shortcut_manager_v3.bind_error> | reason for the failure |
Emitted when a bind_key, bind_swipe_gesture, or bind_hold_gesture request could not be applied; the rejected binding has no effect. The name argument identifies the rejected binding; the error argument provides the reason.
If the requesting client's session is not active, the bind request is applied (and possibly rejected) only when that session becomes active again, so this event may be emitted long after the request was sent. Each rejected request is reported separately; other bindings of the same client are not affected.
Argument | Value | Description |
|---|---|---|
| down | 1 | swipe towards the bottom of the screen |
| left | 2 | swipe towards the left of the screen |
| up | 3 | swipe towards the top of the screen |
| right | 4 | swipe towards the right of the screen |
Cardinal directions used to specify the direction of a swipe gesture binding. The value 0 is reserved and must not be used as a direction argument.
action { notify, 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, maximize, cancel_maximize, minimize, move_window, resize_window, close_window, show_window_menu, move_window_to_prev_workspace, move_window_to_next_workspace, show_desktop, open_multitask_view, close_multitask_view, toggle_multitask_view, taskswitch_next, taskswitch_prev, taskswitch_sameapp_next, taskswitch_sameapp_prev, tile_left, tile_right, tile_top, tile_bottom, tile_top_left, tile_top_right, tile_bottom_left, tile_bottom_right, zoom_in, zoom_out, zoom_reset, toggle_fps_display, lockscreen, shutdown_menu }
Argument | Value | Description |
|---|---|---|
| notify | 0 | emit an activated event to the client |
| 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 |
| maximize | 15 | maximize the active window |
| cancel_maximize | 16 | restore the active window from maximized state |
| minimize | 17 | minimize the active window |
| move_window | 18 | enter window move mode for the active window |
| resize_window | 19 | enter window resize mode for the active window |
| close_window | 20 | close the active window |
| show_window_menu | 21 | show the window menu for the active window |
| move_window_to_prev_workspace | 22 | move the active window to the previous workspace |
| move_window_to_next_workspace | 23 | move the active window to the next workspace |
| show_desktop | 24 | toggle show-desktop mode |
| open_multitask_view | 25 | open the multitask overview |
| close_multitask_view | 26 | close the multitask overview |
| toggle_multitask_view | 27 | toggle the multitask overview |
| taskswitch_next | 28 | select the next task in the switcher |
| taskswitch_prev | 29 | select the previous task in the switcher |
| taskswitch_sameapp_next | 30 | select the next window of the same application in the switcher |
| taskswitch_sameapp_prev | 31 | select the previous window of the same application in the switcher |
| tile_left | 32 | tile the active window to the left half of the screen |
| tile_right | 33 | tile the active window to the right half of the screen |
| tile_top | 34 | tile the active window to the top half of the screen |
| tile_bottom | 35 | tile the active window to the bottom half of the screen |
| tile_top_left | 36 | tile the active window to the top-left quarter of the screen |
| tile_top_right | 37 | tile the active window to the top-right quarter of the screen |
| tile_bottom_left | 38 | tile the active window to the bottom-left quarter of the screen |
| tile_bottom_right | 39 | tile the active window to the bottom-right quarter of the screen |
| zoom_in | 40 | zoom in the screen |
| zoom_out | 41 | zoom out the screen |
| zoom_reset | 42 | reset the screen zoom level |
| toggle_fps_display | 43 | toggle the compositor FPS overlay |
| lockscreen | 44 | lock the screen |
| shutdown_menu | 45 | show the shutdown/session menu |
Actions that the compositor executes when a shortcut with this action is activated.
The notify action is special: instead of performing a compositor-side operation, the compositor emits an activated event on this interface so the client can respond.
keybind_flag { key_press, key_release, repeat }
Argument | Value | Description |
|---|---|---|
| key_press | 0x1 | trigger on key press |
| key_release | 0x2 | trigger on key release |
| repeat | 0x4 | trigger on auto-repeat while the key is held |
Flags that control when a key binding fires relative to the key event lifecycle.
key_press: fires when the key is pressed. key_release: fires when the key is released. repeat: fires repeatedly while the key is held down (auto-repeat). Only meaningful when combined with key_press; combining with key_release causes both the press and the release auto-repeat events to fire.
Common combinations:
bind_error { name_conflict, duplicate_binding, invalid_argument, internal_error }
Argument | Value | Description |
|---|---|---|
| name_conflict | 1 | a binding with this name already exists |
| duplicate_binding | 2 | an identical trigger-and-action combination already exists |
| invalid_argument | 3 | an argument has an invalid or out-of-range value |
| internal_error | 4 | an unrecoverable compositor-internal error occurred |
Error codes carried by the bind_failure event to describe why a bind request was rejected.
error { occupied, not_acquired, invalid_surface }
Argument | Value | Description |
|---|---|---|
| occupied | 1 | the shortcut manager is already held by another client |
| not_acquired | 2 | the client sent a bind or unbind request without first acquiring the manager |
| invalid_surface | 3 | the surface argument is not owned by the requesting client |
Error codes sent as protocol errors via wl_display.error.
treeland_shortcut_capture_v3
Represents a single pending request to capture the next shortcut input from the user, created by treeland_shortcut_manager_v3.capture_next_shortcut.
The compositor captures input once and emits at most one terminal event: either captured or failed. After a terminal event is sent this object becomes inert; the client should destroy it promptly.
If the client destroys this object while capture is still pending, the capture is cancelled and no terminal event is sent.
destroy()
Destroy this capture object. If capture is still pending, destroying the object cancels it; no terminal event will be sent after this request is processed.
captured(key: string)
Argument | Type | Description |
|---|---|---|
| key | string | captured shortcut sequence in QKeySequence portable text format |
Emitted when the compositor captured one shortcut input for this request. The key argument carries the shortcut sequence in the same QKeySequence portable text format used by treeland_shortcut_manager_v3.bind_key. A capture of the Meta (Super) key pressed alone is reported as the shortcut "Meta".
This is a terminal event; the object is now inert.
failed(reason: uint<treeland_shortcut_capture_v3.failed_reason>)
Argument | Type | Description |
|---|---|---|
| reason | uint<treeland_shortcut_capture_v3.failed_reason> | reason the capture failed |
Emitted when the compositor could not deliver a captured shortcut. The reason argument describes why. See the failed_reason enum for details.
This is a terminal event; the object is now inert.
failed_reason { busy, aborted, not_active, interrupted }
Argument | Value | Description |
|---|---|---|
| busy | 1 | a capture is already in progress, or the release of the last captured key is still being consumed |
| aborted | 2 | the surface lost keyboard focus while the capture was pending |
| not_active | 3 | the provided surface did not have keyboard focus at the time of the request |
| interrupted | 4 | the first intercepted input was not a valid shortcut sequence |
Describes why the compositor could not deliver a captured shortcut to the client.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT