Treeland shortcut manager v2
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.
treeland_shortcut_manager_v2
This interface allows privileged clients to register global shortcuts.
In treeland, global shortcuts are managed in a per-user context. Shortcuts for different users are isolated, and will not interfere with each other. This allows multiple users to use their own set of global shortcuts on the same system without conflicts. This behavior is transparent to the clients of this interface (i.e., the user context used by this protocol is the same as that of the client.)
destroy()
Destroy the shortcut manager. Existing shortcuts created through this interface remain valid.
acquire()
Acquire the shortcut manager for the current client.
This request must be sent before any bind/unbind request can be performed.
Only one client can hold exclusive control of the shortcut manager at a time, for a given session. If the shortcut manager is already acquired by another client, the compositor will raise the `occupied` protocol error.
bind_key(name: string, key: string, flags: uint<treeland_shortcut_manager_v2.keybind_flag>, action: uint<treeland_shortcut_manager_v2.action>)
Argument | Type | Description |
|---|---|---|
| name | string | unique name for the keybinding |
| key | string | key sequence for the keybinding |
| flags | uint<treeland_shortcut_manager_v2.keybind_flag> | flags for the keybinding |
| action | uint<treeland_shortcut_manager_v2.action> | compositor action to be executed |
Bind a key sequence to a compositor action.
The key sequence is specified in the string format used by QKeySequence, see https://doc.qt.io/qt-6/qkeysequence.html#toString for details.
Sending this request without first acquiring the shortcut manager will result in a `not_acquired` protocol error.
The name argument must be unique among all existing bindings. If a binding with the same name already exists, the bind_key request will fail.
The action argument specifies the compositor action to be executed when the key sequence is activated.
Each keybind has a flags argument that specifies the exact triggering condition, see the documentation of the keybind_flag enum for details.
If a binding with the same key sequence and action already exists, its flags will be updated to the new value.
Note that the binding will not take effect until a commit request is sent.
bind_swipe_gesture(name: string, finger: uint, direction: uint<treeland_shortcut_manager_v2.direction>, action: uint<treeland_shortcut_manager_v2.action>)
Argument | Type | Description |
|---|---|---|
| name | string | unique name for the swipe gesture |
| finger | uint | number of fingers required for the swipe gesture |
| direction | uint<treeland_shortcut_manager_v2.direction> | direction of the swipe gesture |
| action | uint<treeland_shortcut_manager_v2.action> | compositor action to be executed |
Bind a swipe gesture to a compositor action.
Sending this request without first acquiring the shortcut manager will result in a `not_acquired` protocol error.
The name argument must be unique among all existing bindings. If a binding with the same name already exists, the bind_swipe_gesture request will fail.
The direction argument specifies the direction towards which the swipe gesture must be performed. If this argument is not one of the defined enum values, the bind_swipe_gesture request will fail.
The action argument specifies the compositor action to be executed when the swipe gesture is activated. If a binding with the same gesture and action already exists, the bind_swipe_gesture request will fail.
Note that the binding will not take effect until a commit request is sent.
bind_hold_gesture(name: string, finger: uint, action: uint<treeland_shortcut_manager_v2.action>)
Argument | Type | Description |
|---|---|---|
| name | string | unique name for the hold gesture |
| finger | uint | number of fingers required for the hold gesture |
| action | uint<treeland_shortcut_manager_v2.action> | compositor action to be executed |
Bind a hold gesture to a compositor action.
Sending this request without first acquiring the shortcut manager will result in a `not_acquired` protocol error.
The name argument must be unique among all existing bindings. If a binding with the same name already exists, the bind_hold_gesture request will fail.
The action argument specifies the compositor action to be executed when the hold gesture is activated. If a binding with the same gesture and action already exists, the bind_hold_gesture request will fail.
Note that the binding will not take effect until a commit request is sent.
commit()
Commit the pending bindings.
This request applies all the bind_key, bind_swipe_gesture and bind_hold_gesture requests sent since the last commit.
After processing this request, the compositor will emit a `commit_success` event if the commit was successful or `commit_failure` event if the commit failed.
On a successful commit, all the pending bindings will take effect. On a failed commit, none of the pending bindings will take effect.
Sending this request without first acquiring the shortcut manager will result in a `not_acquired` protocol error.
Sending further commit requests before `commit_success` or `commit_failure` is sent is a protocol error.
unbind(name: string)
Argument | Type | Description |
|---|---|---|
| name | string | unique name of the binding to be removed |
Remove an existing binding.
Sending this request without first acquiring the shortcut manager will result in a `not_acquired` protocol error.
The binding to be removed is identified by its unique name. If no binding with the specified name exists, the unbind request has no effect.
capture_next_shortcut(surface: object<wl_surface>, seat: object<wl_seat>, capture: new_id<treeland_shortcut_capture_v1>)
Argument | Type | Description |
|---|---|---|
| surface | object<wl_surface> | surface used for focus or active validation |
| seat | object<wl_seat>allow null | seat to capture from, or null to capture from any seat |
| capture | new_id<treeland_shortcut_capture_v1> | one-shot capture object |
Request the compositor to capture the next shortcut input once, bound to the provided surface.
The capture object is created by this request via new_id. The compositor performs validation after receiving the request, and may immediately emit a terminal event on the newly created object. Clients must be prepared to handle a capture object that is failed immediately after creation.
The surface argument must be a wl_surface owned by the requesting client. Otherwise, the compositor will raise the `invalid_surface` protocol error.
The compositor must verify that the provided surface currently has keyboard focus or is active before starting capture. If this check fails, the compositor must first decide that capture does not start, and then must emit `failed` with reason `not_active` on the created object.
The compositor monitors both key_press and key_release events during capture. The shortcut candidate is established on key_press of a valid non-modifier key; the terminal event (captured or failed) is sent on key_release of that non-modifier key. Pure modifier-only key presses (e.g. Ctrl, Alt, Shift) are silently consumed while waiting for a non-modifier key. Auto-repeat events are consumed and ignored.
If the next intercepted input is not a valid shortcut input (for example: unmodified alphanumeric keys such as a, b, c, d, 1, 2, 3, unmodified Escape, or pointer button and wheel events), the compositor must fail capture with reason `interrupted`. For either `interrupted` failure or successful `captured`, the triggering input event must be consumed by the compositor and must not be forwarded to the client.
The compositor creates a treeland_shortcut_capture_v1 object and starts a one-shot capture flow for this request.
This request does not modify existing shortcut bindings. This request does not require acquire.
activated(name: string, flags: uint<treeland_shortcut_manager_v2.keybind_flag>)
Argument | Type | Description |
|---|---|---|
| name | string | binding id of the activated shortcut |
| flags | uint<treeland_shortcut_manager_v2.keybind_flag> | flags for the key event |
This event is emitted when a binding registered with action `notify` is activated.
The flags argument indicates the type of key event as defined in the keybind_flag enum.
commit_success()
This event is emitted in response to a commit request, indicating that the commit was successful.
commit_failure(name: string, error: uint<treeland_shortcut_manager_v2.bind_error>)
Argument | Type | Description |
|---|---|---|
| name | string | binding name that caused the failure |
| error | uint<treeland_shortcut_manager_v2.bind_error> | error code indicating the reason of the failure |
This event is emitted in response to a commit request, indicating that the commit has failed.
The error argument indicates the first error that caused the commit to fail.
action { notify, workspace_1, workspace_2, workspace_3, workspace_4, workspace_5, workspace_6, prev_workspace, next_workspace, show_desktop, maximize, cancel_maximize, move_window, close_window, show_window_menu, open_multitask_view, close_multitask_view, toggle_multitask_view, toggle_fps_display, lockscreen, shutdown_menu, quit, taskswitch_enter, taskswitch_next, taskswitch_prev, taskswitch_sameapp_next, taskswitch_sameapp_prev, tile_left, tile_right }
Argument | Value | Description |
|---|---|---|
| notify | 1 | notify the client when the shortcut is activated |
| workspace_1 | 2 | switch to workspace 1 |
| workspace_2 | 3 | switch to workspace 2 |
| workspace_3 | 4 | switch to workspace 3 |
| workspace_4 | 5 | switch to workspace 4 |
| workspace_5 | 6 | switch to workspace 5 |
| workspace_6 | 7 | switch to workspace 6 |
| prev_workspace | 8 | switch to the previous workspace |
| next_workspace | 9 | switch to the next workspace |
| show_desktop | 10 | toggle show desktop |
| maximize | 11 | maximize the active window |
| cancel_maximize | 12 | unmaximize the active window |
| move_window | 13 | start window move mode |
| close_window | 14 | close the active window |
| show_window_menu | 15 | show the window menu |
| open_multitask_view | 16 | open the multitask view |
| close_multitask_view | 17 | close the multitask view |
| toggle_multitask_view | 18 | toggle the multitask view |
| toggle_fps_display | 19 | toggle FPS display |
| lockscreen | 20 | lock the screen |
| shutdown_menu | 21 | show shutdown menu |
| quit | 22 | quit the compositor |
| taskswitch_enter | 23 | enter task switcher |
| taskswitch_next | 24 | switch to next task in switcher |
| taskswitch_prev | 25 | switch to previous task in switcher |
| taskswitch_sameapp_next | 26 | switch to next task of same application |
| taskswitch_sameapp_prev | 27 | switch to previous task of same application |
| tile_leftsince 3 | 28 | tile the active window to the left |
| tile_rightsince 3 | 29 | tile the active window to the right |
Compositor actions that can be assigned to a shortcut.
keybind_flag { key_press, key_release, repeat }
Argument | Value | Description |
|---|---|---|
| key_press | 0x1 | bind key press events |
| key_release | 0x2 | bind key release events |
| repeat | 0x4 | bind autorepeat events. |
Flags to specify the keybinding mode. With key_press, the action is triggered on key press. With key_release, the action is triggered on key release. With repeat, the action is repeatedly triggered if the key is held down.
Examples: key_press | repeat: the action is triggered on key press, and repeatedly triggered if the key is held down. key_press | key_release: the action is triggered on both key press and key release, auto-repeated events are ignored. key_press | key_release | repeat: note that treeland repeats both key press and key release events.
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 | a binding with this key sequence and action already exists |
| invalid_argument | 3 | an argument has an invalid value |
| internal_error | 4 | an internal compositor error occurred |
Error codes indicating the reason of a binding failure.
error { occupied, not_acquired, invalid_commit, invalid_surface }
Argument | Value | Description |
|---|---|---|
| occupied | 1 | the shortcut manager is already acquired by another client |
| not_acquired | 2 | the client has not acquired the shortcut manager |
| invalid_commit | 3 | a commit was sent while a previous commit is pending |
| invalid_surfacesince 2 | 4 | the provided surface is not owned by the requesting client |
treeland_shortcut_capture_v1
This object represents one request to capture the next shortcut input.
After creation, the compositor captures input once and may send at most one terminal event: either captured or failed.
If the client destroys this object while capture is pending, no terminal event is sent.
After a terminal event is sent, this object becomes inert. The client should destroy this object promptly after receiving captured or failed.
destroy()
Destroy this capture object.
Destroying the object cancels capture if it is still pending.
captured(key: string)
Argument | Type | Description |
|---|---|---|
| key | string | captured shortcut sequence |
The compositor captured one shortcut input for this request.
The key argument uses the same textual format as bind_key.
failed(reason: uint<treeland_shortcut_capture_v1.failed_reason>)
Argument | Type | Description |
|---|---|---|
| reason | uint<treeland_shortcut_capture_v1.failed_reason> | failure reason |
The compositor could not complete this capture request.
failed_reason { busy, aborted, not_active, interrupted }
Argument | Value | Description |
|---|---|---|
| busy | 1 | another capture is in progress |
| aborted | 2 | capture was aborted by compositor policy |
| not_active | 3 | surface focus or active validation failed |
| interrupted | 4 | capture was interrupted by a non-shortcut intercepted input |
Reasons why a one-shot capture could not complete.
Compositor Support
| treeland_shortcut_manager_v2 | ↓ | ||
| Compositors | |||
| Cage | 0.3.0 | x | |
| COSMIC | 1.11.0 | x | |
| flakewm | 3.0.5 | x | |
| GameScope | 3.17.0 | x | |
| Hyprland | 0.57.2 | x | |
| Jay | 1.14.0 | x | |
| KWin | 6.7 | x | |
| Labwc | 0.20.2 | x | |
| Louvre | 2.14.1 | x | |
| Mango | 0.16.3 | x | |
| Mir | 2.26 | x | |
| Muffin | 6.7.4 | x | |
| Mutter | 51 | x | |
| niri | 26.04 | x | |
| phoc | 0.55 | x | |
| Pila | 0.5.1 | x | |
| Qtile | 0.37.1 | x | |
| river | 0.5.0 | x | |
| Sway | 1.11 | x | |
| Treeland | 0.8.0 | 1 | |
| Wayfire | 0.9.0 | x | |
| Weston | 15.0.1 | x | |
Copyright
SPDX-FileCopyrightText: 2024-2025 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT