Treeland shortcut manager v2

keyboard shortcut management

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

Deprecatedversion 3
global shortcuts manager for treeland

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

Destroy the shortcut manager. Existing shortcuts created through this interface remain valid.

acquire()
acquire the shortcut manager

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.

Argument
Type
Description
namestring
unique name for the keybinding
keystring
key sequence for the keybinding
flagsuint<treeland_shortcut_manager_v2.keybind_flag>
flags for the keybinding
actionuint<treeland_shortcut_manager_v2.action>
compositor action to be executed
bind a key sequence to a compositor action

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.

Argument
Type
Description
namestring
unique name for the swipe gesture
fingeruint
number of fingers required for the swipe gesture
directionuint<treeland_shortcut_manager_v2.direction>
direction of the swipe gesture
actionuint<treeland_shortcut_manager_v2.action>
compositor action to be executed
bind a swipe gesture to a compositor action

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
namestring
unique name for the hold gesture
fingeruint
number of fingers required for the hold gesture
actionuint<treeland_shortcut_manager_v2.action>
compositor action to be executed
bind a hold gesture to a compositor action

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

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
namestring
unique name of the binding to be removed
remove an existing binding

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
surfaceobject<wl_surface>
surface used for focus or active validation
seatobject<wl_seat>allow null
seat to capture from, or null to capture from any seat
capturenew_id<treeland_shortcut_capture_v1>
one-shot capture object
capture the next shortcut once

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.

Argument
Type
Description
namestring
binding id of the activated shortcut
flagsuint<treeland_shortcut_manager_v2.keybind_flag>
flags for the key event
a shortcut has been activated

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()
the last commit was successful

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
namestring
binding name that caused the failure
erroruint<treeland_shortcut_manager_v2.bind_error>
error code indicating the reason of the failure
the last commit has failed

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.

direction { down, left, up, right } 
Argument
Value
Description
down1
down direction
left2
left direction
up3
up direction
right4
right direction
Argument
Value
Description
notify1
notify the client when the shortcut is activated
workspace_12
switch to workspace 1
workspace_23
switch to workspace 2
workspace_34
switch to workspace 3
workspace_45
switch to workspace 4
workspace_56
switch to workspace 5
workspace_67
switch to workspace 6
prev_workspace8
switch to the previous workspace
next_workspace9
switch to the next workspace
show_desktop10
toggle show desktop
maximize11
maximize the active window
cancel_maximize12
unmaximize the active window
move_window13
start window move mode
close_window14
close the active window
show_window_menu15
show the window menu
open_multitask_view16
open the multitask view
close_multitask_view17
close the multitask view
toggle_multitask_view18
toggle the multitask view
toggle_fps_display19
toggle FPS display
lockscreen20
lock the screen
shutdown_menu21
show shutdown menu
quit22
quit the compositor
taskswitch_enter23
enter task switcher
taskswitch_next24
switch to next task in switcher
taskswitch_prev25
switch to previous task in switcher
taskswitch_sameapp_next26
switch to next task of same application
taskswitch_sameapp_prev27
switch to previous task of same application
tile_leftsince 328
tile the active window to the left
tile_rightsince 329
tile the active window to the right
compositor actions

Compositor actions that can be assigned to a shortcut.

keybind_flag { key_press, key_release, repeat } 
Argument
Value
Description
key_press0x1
bind key press events
key_release0x2
bind key release events
repeat0x4
bind autorepeat events.
keybinding flags

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.

Argument
Value
Description
name_conflict1
a binding with this name already exists
duplicate_binding2
a binding with this key sequence and action already exists
invalid_argument3
an argument has an invalid value
internal_error4
an internal compositor error occurred
binding error codes

Error codes indicating the reason of a binding failure.

Argument
Value
Description
occupied1
the shortcut manager is already acquired by another client
not_acquired2
the client has not acquired the shortcut manager
invalid_commit3
a commit was sent while a previous commit is pending
invalid_surfacesince 24
the provided surface is not owned by the requesting client

treeland_shortcut_capture_v1

Deprecatedversion 1
one-shot shortcut capture object

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 the capture object

Destroy this capture object.

Destroying the object cancels capture if it is still pending.

captured(key: string)
Argument
Type
Description
keystring
captured shortcut sequence
a shortcut input was captured

The compositor captured one shortcut input for this request.

The key argument uses the same textual format as bind_key.

Argument
Type
Description
reasonuint<treeland_shortcut_capture_v1.failed_reason>
failure reason
the capture failed

The compositor could not complete this capture request.

failed_reason { busy, aborted, not_active, interrupted } 
Argument
Value
Description
busy1
another capture is in progress
aborted2
capture was aborted by compositor policy
not_active3
surface focus or active validation failed
interrupted4
capture was interrupted by a non-shortcut intercepted input
capture failure reason

Reasons why a one-shot capture could not complete.


Compositor Support

treeland_shortcut_manager_v2↓
Compositors
CageCage0.3.0
x
COSMICCOSMIC1.11.0
x
flakewm3.0.5
x
GameScopeGameScope3.17.0
x
HyprlandHyprland0.57.2
x
Jay1.14.0
x
KWinKWin6.7
x
LabwcLabwc0.20.2
x
LouvreLouvre2.14.1
x
MangoMango0.16.3
x
MirMir2.26
x
MuffinMuffin6.7.4
x
MutterMutter51
x
niriniri26.04
x
phocphoc0.55
x
Pila0.5.1
x
QtileQtile0.37.1
x
riverriver0.5.0
x
SwaySway1.11
x
TreelandTreeland0.8.0
1
WayfireWayfire0.9.0
x
WestonWeston15.0.1
x

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