Treeland keyboard state notify
This protocol allows privileged clients to subscribe to global keyboard state changes (e.g. Caps Lock, Num Lock).
Clients create watcher objects through the manager global, each bound to a seat. The client then configures the watcher with set_modifiers to choose which modifiers to monitor, and set_flags to choose which event types (locked, unlocked, or both) to receive. Configuration changes are double-buffered and take effect atomically when the client sends apply. Both set_modifiers and set_flags can be called multiple times before apply; only the values from the most recent calls are committed. This allows changing the configuration at runtime without destroying and recreating the watcher. After apply, the compositor sends a current_state event for each watched modifier containing its current lock state, so the client can synchronize its initial state without waiting for the next physical key press. The compositor then sends state_changed events on the watcher whenever any of the watched modifiers changes lock state globally, regardless of which surface has keyboard focus.
This protocol is observation-only. Keyboard state changes are never consumed or intercepted by this protocol.
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.
The treeland_keyboard_state_notify_manager_v1 interface is a singleton global object used to create watcher objects for monitoring keyboard state changes on a given seat.
A client may create multiple watcher objects for the same seat if needed.
destroy()
Destroy this treeland_keyboard_state_notify_manager_v1 object.
Existing watcher objects created through this interface are not destroyed automatically. Clients should destroy those objects before destroying the manager.
get_keyboard_state_watcher(id: new_id<treeland_keyboard_state_watcher_v1>, seat: object<wl_seat>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_keyboard_state_watcher_v1> | |
| seat | object<wl_seat>allow null | seat to monitor keyboard state on, or null for all seats |
Create a treeland_keyboard_state_watcher_v1 object for monitoring keyboard state changes on the given seat, or on all seats if seat is null.
The watcher is created with no modifiers and no flags set by default. The client should use set_modifiers and set_flags on the watcher to configure what to monitor.
Note: 1. The treeland_keyboard_state_watcher_v1 object must be destroyed before the associated wl_seat is destroyed.
treeland_keyboard_state_watcher_v1
The treeland_keyboard_state_watcher_v1 interface represents a subscription to keyboard state changes on a specific seat.
This object is created via get_keyboard_state_watcher on the treeland_keyboard_state_notify_manager_v1 global. The client configures the watcher with set_modifiers to choose which modifiers to monitor and set_flags to choose which state transitions to receive. Both can be changed at runtime. Configuration changes are double-buffered: set_modifiers and set_flags only update the pending state, which is applied atomically when apply is called.
The compositor sends a current_state event for each modifier in the committed modifier set immediately after apply is called. It then sends state_changed events whenever any of the watched modifiers changes lock state, according to the committed modifiers and flags.
destroy()
Destroy this treeland_keyboard_state_watcher_v1 object and stop receiving keyboard state notifications.
set_modifiers(modifiers: uint<treeland_keyboard_state_watcher_v1.modifier>)
Argument | Type | Description |
|---|---|---|
| modifiers | uint<treeland_keyboard_state_watcher_v1.modifier> | bitfield of modifier enum values to watch |
Set the keyboard modifiers to watch on this watcher.
The modifiers argument is a bitfield of values from the modifier enum (e.g. caps_lock = 1, num_lock = 2). Multiple modifiers can be combined using bitwise OR.
Calling set_modifiers replaces any previously pending modifiers.
This request only updates the pending configuration. The change takes effect when apply is called. If set_modifiers is called multiple times before apply, only the values from the most recent call are used.
set_flags(flags: uint<treeland_keyboard_state_watcher_v1.watch_flag>)
Argument | Type | Description |
|---|---|---|
| flags | uint<treeland_keyboard_state_watcher_v1.watch_flag> | new watch flags |
Change the watch flags for this watcher, selecting which modifier state transitions (locked, unlocked, or both) the client wants to be notified about.
This request only updates the pending configuration. The change takes effect when apply is called. If set_flags is called multiple times before apply, only the values from the most recent call are used.
apply()
Apply the pending configuration state for this watcher atomically.
The compositor will use the modifiers and flags set by the most recent set_modifiers and set_flags calls as the new active configuration for this watcher. If set_modifiers or set_flags have not been called since the last apply (or since the watcher was created), the corresponding pending values remain unchanged.
After this request, the pending configuration is considered consumed. Subsequent calls to set_modifiers or set_flags will begin a new pending configuration.
The compositor will send a current_state event for each modifier in the newly committed modifier set immediately after processing this request.
current_state(modifier: uint<treeland_keyboard_state_watcher_v1.modifier>, state: uint<treeland_keyboard_state_watcher_v1.modifier_state>)
Argument | Type | Description |
|---|---|---|
| modifier | uint<treeland_keyboard_state_watcher_v1.modifier> | the modifier whose lock state is being reported |
| state | uint<treeland_keyboard_state_watcher_v1.modifier_state> | the current lock state of the modifier |
Sent for each modifier in the committed modifier set after each apply call to provide its current lock state. For example, if the client watches caps_lock and num_lock, the compositor will send two current_state events, one for each modifier.
This event is emitted before any subsequent state_changed events for the new configuration. It may be sent again after future apply calls if the client reconfigures the watcher.
state_changed(modifier: uint<treeland_keyboard_state_watcher_v1.modifier>, state: uint<treeland_keyboard_state_watcher_v1.modifier_state>)
Argument | Type | Description |
|---|---|---|
| modifier | uint<treeland_keyboard_state_watcher_v1.modifier> | the modifier that changed lock state |
| state | uint<treeland_keyboard_state_watcher_v1.modifier_state> | the new lock state of the modifier |
This event is sent when one of the watched modifiers changes lock state globally, according to the modifiers and flags currently set on this watcher.
The modifier argument identifies which modifier changed state. The state argument indicates whether the modifier is now locked or unlocked.
Bitfield of keyboard modifiers whose lock state can be monitored. Multiple modifier values can be combined using bitwise OR.
caps_lock: the Caps Lock modifier. num_lock: the Num Lock modifier.
Examples: caps_lock: monitor only Caps Lock. caps_lock | num_lock: monitor both Caps Lock and Num Lock.
Argument | Value | Description |
|---|---|---|
| locked | 1 | notify when modifier is locked |
| unlocked | 2 | notify when modifier is unlocked |
Flags to specify which modifier lock state transitions the client wants to be notified about.
none: do not notify on any state transition. locked: notify when a watched modifier becomes locked. unlocked: notify when a watched modifier becomes unlocked.
Examples: locked: the client receives events only when a modifier is locked. unlocked: the client receives events only when a modifier is unlocked. locked | unlocked: the client receives events on both.
The current lock state of a keyboard modifier.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT