Hotkey

Destroy the manager object. Hotkey objects created through this manager are unaffected and remain valid.

Identify the application, for use in compositor policy and user-facing audit interfaces. It applies to every hotkey created by this manager.

Optional; if sent, it must not be empty, must be sent at most once, and must be sent before the first commit, so that every policy decision sees the same identity.

Where the application has a desktop entry, app_id should be its desktop file ID as defined by the freedesktop.org Desktop Entry specification, matching the convention used by xdg_toplevel.set_app_id.

It is advisory and may be spoofed; a compositor that needs a trustworthy identity should obtain it through the security-context mechanism.

Create a new hotkey object. No binding exists and no input events are sent before the first successful commit.

Fatal protocol errors.

A bitmask of the modifiers that must be held for the trigger to fire. The match is exact: a trigger does not fire while a modifier outside its mask is held, so Super+Space does not fire on Super+Shift+Space. Bits outside this enum raise the "invalid_trigger" error.

These are fixed, keymap-independent semantic bits. A compositor matches each bit against the corresponding modifier in its keyboard state as the keymap defines it; for the xkb_v1 keymap format that is shift -> XKB_MOD_NAME_SHIFT, ctrl -> XKB_MOD_NAME_CTRL, alt -> XKB_MOD_NAME_ALT ("Mod1"), super -> XKB_MOD_NAME_LOGO ("Mod4").

A client needs neither a wl_keyboard nor a keymap to describe a trigger.

Lock modifiers (Caps Lock, Num Lock, Scroll Lock) are never part of a binding and are ignored when matching.

Release the binding and destroy the object. Destroying the object with a commit still in flight cancels it.

Set a human-readable, localized description of what the hotkey does (e.g. "Toggle the launcher"), for display in compositor user interface. Optional.

Restrict the hotkey to the given seat, or pass null for all of the client's seats, virtual ones included. Optional; the default is null. If the given seat is removed, the compositor sends "revoked".

Describe the trigger as a key pressed while the given modifiers are held. Replaces any trigger previously described. Takes effect on the next commit.

The keysym uses the numbering shared with the keymap delivered over wl_keyboard (for the xkb_v1 keymap format, an XKB_KEY_* value), in its unshifted form (XKB_KEY_b, not XKB_KEY_B). The compositor matches it against the keysym each key produces at its first shift level in any of the user's layout groups, ignoring the effect Shift has on the key, so that Shift is handled through the modifier mask like every other modifier and a binding keeps firing after a layout group switch. A binding whose keysym no group of the current keymap produces stays bound and simply does not fire until the keymap changes again.

The trigger fires on key press; the compositor does not wait to see whether another key follows. The press and the matching release are consumed and must not be delivered to the focused surface.

The keysym may be one that contributes to modifier state, such as XKB_KEY_Super_L; whether it does is decided by the seat's keymap. Such a trigger is a tap: it fires when the key is released, and only if no other key, button or axis event occurred while it was held. A compositor may additionally require that it was held no longer than some interval. The modifier mask is evaluated as the state before the key was pressed, so a lone left Super key is (XKB_KEY_Super_L, 0) and (XKB_KEY_Shift_L, ctrl) is a tap on Shift while Control is held.

A tap is never consumed: the key must still update modifier state and reach the focused surface, so binding it does not stop it composing other shortcuts. "triggered" and "released" are sent together on release, so a tap cannot drive press-and-hold.

A null keysym raises the "invalid_trigger" error.

Describe the trigger as a pointer button pressed while the given modifiers are held. Replaces any trigger previously described. Takes effect on the next commit.

The button is a button code in the same space as wl_pointer.button.

The press and the matching release are consumed and must not be delivered to the surface under the pointer.

Apply the state built up on this object. The compositor replies with exactly one "bound" or "denied" event per commit, in order.

Sending commit before a trigger has been described raises the "no_trigger" error.

Commit may be sent again to apply a changed trigger, description or seat, keeping the binding's identity. Values set with set_* requests are retained across commits, accepted or denied, and each commit applies all of them; committing with nothing changed is accepted with "bound". An established binding survives a rejected commit: the previous state stays active, so a denied reconfiguration never leaves the user with no hotkey.

The commit was accepted and the binding is active with the trigger that was committed. "triggered" and "released" events may follow.

The committed trigger was not bound. Any previously established binding remains active with its previous trigger.

message is an optional, advisory, human-readable explanation in the compositor's locale, intended for verbatim display. It may be empty. Clients must not parse it; all programmatic behavior keys off reason.

A binding that was previously "bound" is no longer active. No further input events will be sent for it. The client should destroy this object and must not silently commit the same trigger again; whether to retry is the user's decision.

message has the same meaning as in the "denied" event.

The bound trigger fired. This event is sent once each time it fires; the compositor does not auto-repeat the hotkey.

serial is an input serial that counts as a recent user interaction. A client may pass it to xdg_activation_token_v1.set_serial to raise or focus a surface, and a compositor should honor activation carried by it.

time is the event timestamp, on the same millisecond clock as wl_pointer and wl_keyboard input events.

The key or button of a previously triggered hotkey was released, regardless of modifier state. This enables press-and-hold uses such as push-to-talk; clients that only act on the initial firing may ignore it.

serial and time have the same meaning as in the "triggered" event.

Fatal protocol errors. A trigger that is merely unacceptable to the compositor is reported through "denied" and is not an error.

A reason code describing why the commit got denied. The object remains valid, any previously established binding is unaffected, and the client may describe a different trigger and commit again.

A compositor is not obliged to distinguish "already_bound" from "not_permitted" and may report the latter for both.