Treeland shortcut manager v3

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.

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.

global shortcut manager

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

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

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.

Argument
Type
Description
namestring
unique name for this keybinding
keystring
key sequence in QKeySequence portable text format
flagsuint<treeland_shortcut_manager_v3.keybind_flag>
trigger conditions for this keybinding
actionuint<treeland_shortcut_manager_v3.action>
compositor action to execute on activation
register a key sequence binding

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).

Argument
Type
Description
namestring
unique name for this swipe gesture binding
fingeruint
number of fingers required for the swipe
directionuint<treeland_shortcut_manager_v3.direction>
required swipe direction
actionuint<treeland_shortcut_manager_v3.action>
compositor action to execute on activation
register a swipe gesture binding

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
namestring
unique name for this hold gesture binding
fingeruint
number of fingers required for the hold
actionuint<treeland_shortcut_manager_v3.action>
compositor action to execute on activation
register a hold gesture binding

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

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
surfaceobject<wl_surface>
surface used to validate keyboard focus
seatobject<wl_seat>allow null
seat to capture from, or null to capture from any available seat
capturenew_id<treeland_shortcut_capture_v3>
one-shot capture object
start a one-shot shortcut capture

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.

Argument
Type
Description
namestring
name of the activated binding
flagsuint<treeland_shortcut_manager_v3.keybind_flag>
key event type that triggered activation
a notify-action shortcut was activated

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
namestring
name of the rejected binding
erroruint<treeland_shortcut_manager_v3.bind_error>
reason for the failure
a bind request was rejected

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.

direction { down, left, up, right } 
Argument
Value
Description
down1
swipe towards the bottom of the screen
left2
swipe towards the left of the screen
up3
swipe towards the top of the screen
right4
swipe towards the right of the screen
swipe gesture direction

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.

Argument
Value
Description
notify0
emit an activated event to the client
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
maximize15
maximize the active window
cancel_maximize16
restore the active window from maximized state
minimize17
minimize the active window
move_window18
enter window move mode for the active window
resize_window19
enter window resize mode for the active window
close_window20
close the active window
show_window_menu21
show the window menu for the active window
move_window_to_prev_workspace22
move the active window to the previous workspace
move_window_to_next_workspace23
move the active window to the next workspace
show_desktop24
toggle show-desktop mode
open_multitask_view25
open the multitask overview
close_multitask_view26
close the multitask overview
toggle_multitask_view27
toggle the multitask overview
taskswitch_next28
select the next task in the switcher
taskswitch_prev29
select the previous task in the switcher
taskswitch_sameapp_next30
select the next window of the same application in the switcher
taskswitch_sameapp_prev31
select the previous window of the same application in the switcher
tile_left32
tile the active window to the left half of the screen
tile_right33
tile the active window to the right half of the screen
tile_top34
tile the active window to the top half of the screen
tile_bottom35
tile the active window to the bottom half of the screen
tile_top_left36
tile the active window to the top-left quarter of the screen
tile_top_right37
tile the active window to the top-right quarter of the screen
tile_bottom_left38
tile the active window to the bottom-left quarter of the screen
tile_bottom_right39
tile the active window to the bottom-right quarter of the screen
zoom_in40
zoom in the screen
zoom_out41
zoom out the screen
zoom_reset42
reset the screen zoom level
toggle_fps_display43
toggle the compositor FPS overlay
lockscreen44
lock the screen
shutdown_menu45
show the shutdown/session menu
compositor actions assignable to a shortcut

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_press0x1
trigger on key press
key_release0x2
trigger on key release
repeat0x4
trigger on auto-repeat while the key is held
keybinding trigger flags

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:

Argument
Value
Description
name_conflict1
a binding with this name already exists
duplicate_binding2
an identical trigger-and-action combination already exists
invalid_argument3
an argument has an invalid or out-of-range value
internal_error4
an unrecoverable compositor-internal error occurred
bind request failure codes

Error codes carried by the bind_failure event to describe why a bind request was rejected.

Argument
Value
Description
occupied1
the shortcut manager is already held by another client
not_acquired2
the client sent a bind or unbind request without first acquiring the manager
invalid_surface3
the surface argument is not owned by the requesting client
protocol errors for this interface

Error codes sent as protocol errors via wl_display.error.


one-shot shortcut capture object

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

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
keystring
captured shortcut sequence in QKeySequence portable text format
a shortcut was successfully captured

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.

Argument
Type
Description
reasonuint<treeland_shortcut_capture_v3.failed_reason>
reason the capture failed
the capture could not be completed

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
busy1
a capture is already in progress, or the release of the last captured key is still being consumed
aborted2
the surface lost keyboard focus while the capture was pending
not_active3
the provided surface did not have keyboard focus at the time of the request
interrupted4
the first intercepted input was not a valid shortcut sequence
reasons a one-shot capture could not complete

Describes why the compositor could not deliver a captured shortcut to the client.


Compositor Support

No compositor support found

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