Treeland input manager
This protocol allows a privileged client to discover seat capabilities and configure compositor-managed mouse, touchpad, and keyboard devices.
A treeland_input_manager_v1 object is a global manager. It creates settings objects that represent configuration state for existing input devices; those settings objects are not the device objects themselves.
For mouse and touchpad devices, pointer device settings such as acceleration speed, acceleration profile, natural scrolling, scroll factor, handed mode, double-click interval, send events mode, disable-while-typing and tap-to-click are managed through a treeland_pointer_device_configuration_v1 object created from the device-specific settings interface.
Keyboard settings include repeat behavior, num lock state, and XKB layout, model, variant, and option strings for the target seat.
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_input_manager_v1
The treeland_input_manager_v1 interface is a global object used to create per-device settings objects for input devices exposed by the compositor.
The compositor advertises device capability changes with the capability_available and capability_unavailable events.
For each target device or seat-level settings scope, the compositor may allow at most one live settings object of a given interface created from one manager object.
virtual-pointer and virtual-keyboard are not included in the list.
destroy()
This informs the compositor that the treeland input manager object will no longer be used.
Existing objects created through this interface are not destroyed automatically. Clients should destroy those objects before destroying the manager.
get_mouse_settings(id: new_id<treeland_mouse_settings_v1>, seat: object<wl_seat>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_mouse_settings_v1> | |
| seat | object<wl_seat> | seat whose mouse-specific settings are being managed |
Create a treeland_mouse_settings_v1 object bound to the specified wl_seat.
The created object acts as a factory for treeland_pointer_device_configuration_v1 objects that manage mouse device settings on the target seat.
The seat must currently expose mouse capability. If the seat does not identify a valid mouse-capable target, the compositor raises the protocol error.
Note: 1. The treeland_mouse_settings_v1 object must be destroyed before the associated wl_seat is destroyed.
get_touchpad_settings(id: new_id<treeland_touchpad_settings_v1>, seat: object<wl_seat>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_touchpad_settings_v1> | |
| seat | object<wl_seat> | seat whose touchpad-specific settings are being managed |
Create a treeland_touchpad_settings_v1 object bound to the specified wl_seat.
The created object acts as a factory for treeland_pointer_device_configuration_v1 objects that manage touchpad device settings on the target seat.
The seat must currently expose touchpad capability. If the seat does not identify a valid touchpad-capable target, the compositor raises the protocol error.
Note: 1. The treeland_touchpad_settings_v1 object must be destroyed before the associated wl_seat is destroyed.
get_keyboard_settings(id: new_id<treeland_keyboard_settings_v1>, seat: object<wl_seat>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_keyboard_settings_v1> | |
| seat | object<wl_seat> | seat whose keyboard-specific settings are being managed |
Create a treeland_keyboard_settings_v1 object bound to the specified wl_seat.
The seat must currently expose keyboard capability. If the seat does not identify a valid keyboard-capable target, the compositor raises the protocol error.
Note: 1. The treeland_keyboard_settings_v1 object must be destroyed before the associated wl_seat is destroyed.
capability_available(type: uint<treeland_input_manager_v1.device_type>, seat: object<wl_seat>)
Argument | Type | Description |
|---|---|---|
| type | uint<treeland_input_manager_v1.device_type> | type of the device capability |
| seat | object<wl_seat> | seat associated with the capability |
This event is emitted when the compositor detects that a seat now exposes the specified device capability.
The compositor sends this event immediately after the treeland_input_manager_v1 object is created to report capabilities currently available on a seat.
The compositor may also send this event later when input devices are hot-plugged and a seat gains the specified capability.
A client may create a treeland_mouse_settings_v1 object for a given seat only if the compositor has advertised device_type mouse capability for that seat. Likewise, a client may create a treeland_touchpad_settings_v1 or treeland_keyboard_settings_v1 object for a given seat only if the compositor has advertised device_type touchpad or keyboard capability for that seat.
capability_unavailable(type: uint<treeland_input_manager_v1.device_type>, seat: object<wl_seat>)
Argument | Type | Description |
|---|---|---|
| type | uint<treeland_input_manager_v1.device_type> | type of the device capability |
| seat | object<wl_seat> | seat associated with the capability |
This event is emitted when the compositor detects that a seat no longer exposes the specified device capability.
The compositor may also send this event later when input devices are hot-unplugged and a seat loses the specified capability.
If type includes mouse capability, the client must destroy any treeland_mouse_settings_v1 objects targeting the seat. This also destroys any treeland_pointer_device_configuration_v1 objects created from those mouse settings objects.
If type includes touchpad capability, the client must destroy any treeland_touchpad_settings_v1 objects targeting the seat. This also destroys any treeland_pointer_device_configuration_v1 objects created from those touchpad settings objects.
If type includes keyboard capability, the client must destroy any treeland_keyboard_settings_v1 objects targeting the seat.
The treeland_pointer_device_configuration_v1 interface represents pending configuration for pointer devices associated with the parent device settings object.
This object is created via get_pointer_configuration on a treeland_mouse_settings_v1 or treeland_touchpad_settings_v1 object. It collects configuration that applies to the associated device type.
Requests on this object update pending state. The compositor applies the accumulated settings when the client sends apply. Destroying the object before apply discards any pending state that has not yet been applied.
The compositor sends configuration events after object creation to report the current effective settings. It may later send additional state batches when those effective settings change for compositor-defined reasons. A done event terminates each event batch.
destroy()
Destroy this treeland_pointer_device_configuration_v1 object.
Destroying the object discards any pending state that has not yet been applied.
set_scroll_factor(factor: fixed)
Argument | Type | Description |
|---|---|---|
| factor | fixed | scaling factor applied to scroll axis delta, The factor must be greater than 0. |
Set a scaling factor applied to scroll axis delta generated by wheel and other continuous scrolling input sources. This request requires the scroll_factor feature to be advertised via the feature event.
The compositor multiplies scroll axis values by the specified factor before forwarding them to clients. This affects continuous scroll delta only and does not modify discrete scroll step events.
This request updates only the pending state associated with this object. The change takes effect after the next apply request.
Sending this request or the corresponding apply request does not by itself cause a scroll_factor event to be emitted.
delta = factor * _delta
set_handed_mode(mode: uint<treeland_pointer_device_configuration_v1.handed_mode>)
Argument | Type | Description |
|---|---|---|
| mode | uint<treeland_pointer_device_configuration_v1.handed_mode> | desired handedness mode |
Set whether primary and secondary buttons use left-handed or right-handed ordering. This request requires the handed_mode feature to be advertised via the feature event. The change takes effect on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause a handed_mode event to be emitted.
set_accel_speed(accel_speed: fixed)
Argument | Type | Description |
|---|---|---|
| accel_speed | fixed | desired pointer acceleration speed, The valid range is -1.0 to 1.0, where 0.0 is the neutral default meaning no acceleration adjustment. Negative values reduce acceleration (cursor moves more slowly at higher speeds), positive values increase acceleration (cursor moves faster at higher speeds). |
Set the pointer acceleration speed. This request requires the accel_speed feature to be advertised via the feature event. The change takes effect on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause an accel_speed event to be emitted.
set_acceleration_profile(profile: uint<treeland_pointer_device_configuration_v1.acceleration_profile>)
Argument | Type | Description |
|---|---|---|
| profile | uint<treeland_pointer_device_configuration_v1.acceleration_profile> | desired acceleration profile |
Set the acceleration profile. This request requires the acceleration_profile feature to be advertised via the feature event. The change takes effect on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause an acceleration_profile event to be emitted.
set_send_events_mode(mode: uint<treeland_pointer_device_configuration_v1.send_events_mode>)
Argument | Type | Description |
|---|---|---|
| mode | uint<treeland_pointer_device_configuration_v1.send_events_mode> | desired pointer event delivery mode |
Set how events from the target pointer device are delivered. This request requires the send_events_mode feature to be advertised via the feature event. The change takes effect on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause a send_events_mode event to be emitted.
set_natural_scroll(state: uint<treeland_input_manager_v1.state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_input_manager_v1.state> | desired natural scrolling state |
Enable or disable natural scrolling. This request requires the natural_scroll feature to be advertised via the feature event. The change takes effect on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause a natural_scroll event to be emitted.
set_disable_while_typing(state: uint<treeland_input_manager_v1.state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_input_manager_v1.state> | desired disable-while-typing state |
Enable or disable temporarily disabling pointer devices while the user is typing. This request requires the disable_while_typing feature to be advertised via the feature event. The change takes effect on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause a disable_while_typing event to be emitted.
set_tap_to_click(state: uint<treeland_input_manager_v1.state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_input_manager_v1.state> | desired tap-to-click state |
Enable or disable tap-to-click. This request requires the tap_to_click feature to be advertised via the feature event. The change takes effect on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause a tap_to_click event to be emitted.
apply()
Ask the compositor to apply the pending pointer device configuration carried by this object.
feature(feature: uint<treeland_pointer_device_configuration_v1.feature>)
Argument | Type | Description |
|---|---|---|
| feature | uint<treeland_pointer_device_configuration_v1.feature> | supported pointer device features |
This event reports which optional features are supported by at least one device associated with the parent settings object.
The compositor sends this event as part of the initial state batch after the treeland_pointer_device_configuration_v1 object is created.
The compositor may also send this event again when devices are added to or removed from the target seat and the set of supported features changes.
scroll_factor(factor: fixed)
Argument | Type | Description |
|---|---|---|
| factor | fixed | current scroll factor |
This event reports the current scroll factor used for wheel and similar scroll input.
The compositor sends this event immediately after the treeland_pointer_device_configuration_v1 object is created as part of the initial state batch.
Changes requested through set_scroll_factor do not cause this event to be emitted automatically.
handed_mode(mode: uint<treeland_pointer_device_configuration_v1.handed_mode>)
Argument | Type | Description |
|---|---|---|
| mode | uint<treeland_pointer_device_configuration_v1.handed_mode> | current handedness mode |
This event reports whether left-handed or right-handed button ordering is currently used.
The compositor sends this event immediately after the treeland_pointer_device_configuration_v1 object is created as part of the initial state batch.
Changes requested through set_handed_mode do not cause this event to be emitted automatically.
accel_speed(accel_speed: fixed)
Argument | Type | Description |
|---|---|---|
| accel_speed | fixed | current pointer acceleration speed |
This event reports the current pointer acceleration speed.
The compositor sends this event immediately after the treeland_pointer_device_configuration_v1 object is created as part of the initial state batch.
Changes requested through set_accel_speed do not cause this event to be emitted automatically.
acceleration_profile(profile: uint<treeland_pointer_device_configuration_v1.acceleration_profile>)
Argument | Type | Description |
|---|---|---|
| profile | uint<treeland_pointer_device_configuration_v1.acceleration_profile> | current acceleration profile |
This event reports the current acceleration profile.
The compositor sends this event immediately after the treeland_pointer_device_configuration_v1 object is created as part of the initial state batch.
Changes requested through set_acceleration_profile do not cause this event to be emitted automatically.
send_events_mode(mode: uint<treeland_pointer_device_configuration_v1.send_events_mode>)
Argument | Type | Description |
|---|---|---|
| mode | uint<treeland_pointer_device_configuration_v1.send_events_mode> | current pointer event delivery mode |
This event reports the current event delivery mode used for the target pointer device.
The compositor sends this event immediately after the treeland_pointer_device_configuration_v1 object is created as part of the initial state batch.
Changes requested through set_send_events_mode do not cause this event to be emitted automatically.
natural_scroll(state: uint<treeland_input_manager_v1.state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_input_manager_v1.state> | current natural scrolling state |
This event reports whether natural scrolling is enabled.
The compositor sends this event immediately after the treeland_pointer_device_configuration_v1 object is created as part of the initial state batch.
Changes requested through set_natural_scroll do not cause this event to be emitted automatically.
disable_while_typing(state: uint<treeland_input_manager_v1.state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_input_manager_v1.state> | current disable-while-typing state |
This event reports whether pointer devices are temporarily disabled while the user is typing.
The compositor sends this event as part of the initial state batch if the disable_while_typing feature has been advertised.
Changes requested through set_disable_while_typing do not cause this event to be emitted automatically.
tap_to_click(state: uint<treeland_input_manager_v1.state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_input_manager_v1.state> | current tap-to-click state |
This event reports whether tap-to-click is enabled.
The compositor sends this event as part of the initial state batch if the tap_to_click feature has been advertised.
Changes requested through set_tap_to_click do not cause this event to be emitted automatically.
failed()
This event indicates that the compositor failed to apply one or more pending pointer device configuration changes carried by this object.
This event does not destroy the object. The client may continue using the object and send further requests.
done(serial: uint)
Argument | Type | Description |
|---|---|---|
| serial | uint | current configuration serial |
This event is sent once when all pointer device configuration state events in the current batch have been sent.
The compositor must always end a batch of pointer device configuration state events with this event, regardless of whether it sends the initial state or a later update.
The serial is used in a future get_pointer_configuration request to ensure the client's configuration is based on up-to-date state.
feature { scroll_factor, handed_mode, accel_speed, acceleration_profile, send_events_mode, natural_scroll, disable_while_typing, tap_to_click }
Argument | Value | Description |
|---|---|---|
| scroll_factor | 1 | device supports configuring scroll factor |
| handed_mode | 2 | device supports configuring handed mode |
| accel_speed | 4 | device supports configuring acceleration speed |
| acceleration_profile | 8 | device supports configuring acceleration profile |
| send_events_mode | 16 | device supports configuring event delivery mode |
| natural_scroll | 32 | device supports configuring natural scrolling |
| disable_while_typing | 64 | device supports disable-while-typing |
| tap_to_click | 128 | device supports tap-to-click |
Optional features supported by pointer devices. The compositor sends a feature event to indicate which features are supported by at least one device associated with the parent settings object. A client must only send a set request if the corresponding feature has been advertised. It is a protocol error to send a set request for a feature that has not been advertised.
Argument | Value | Description |
|---|---|---|
| none | 0 | device does not have a configurable acceleration profile |
| flat | 1 | use a flat acceleration profile |
| adaptive | 2 | use an adaptive acceleration profile |
| custom | 4 | use a custom acceleration profile |
Pointer acceleration profiles. The semantics correspond to libinput acceleration profiles.
send_events_mode { enabled, disabled, disabled_on_external_mouse }
Argument | Value | Description |
|---|---|---|
| enabled | 0 | send events from this device normally |
| disabled | 1 | do not send events from this device |
| disabled_on_external_mouse | 2 | if an external pointer device is plugged in, do not send events from this device; may be available on built-in pointer devices |
Modes controlling whether the target pointer device should send events and whether those events depend on the presence of an external pointer device on the same seat.
treeland_mouse_settings_v1
The treeland_mouse_settings_v1 interface acts as a factory for treeland_pointer_device_configuration_v1 objects that manage mouse device settings on the target seat.
A treeland_pointer_device_configuration_v1 object is created via get_pointer_configuration on this object.
destroy()
Destroy this treeland_mouse_settings_v1 object.
Existing treeland_pointer_device_configuration_v1 objects created from this object are also destroyed.
get_pointer_configuration(id: new_id<treeland_pointer_device_configuration_v1>, serial: uint)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_pointer_device_configuration_v1> | |
| serial | uint | serial from the last done event |
Create a treeland_pointer_device_configuration_v1 object for this mouse settings scope.
The created object manages mouse device configuration on the target seat. The serial argument must match the serial from the most recent done event sent on the previous treeland_pointer_device_configuration_v1 object for this treeland_mouse_settings_v1 object. For the first creation, the serial should be 0.
Only one treeland_pointer_device_configuration_v1 object may exist for this treeland_mouse_settings_v1 object at a time. Creating a second one without destroying the first is a protocol error.
If the serial does not match the current state, the compositor may immediately send a failed event on the new treeland_pointer_device_configuration_v1 object.
treeland_touchpad_settings_v1
The treeland_touchpad_settings_v1 interface acts as a factory for treeland_pointer_device_configuration_v1 objects that manage touchpad device settings on the target seat.
A treeland_pointer_device_configuration_v1 object is created via get_pointer_configuration on this object.
destroy()
Destroy this treeland_touchpad_settings_v1 object.
Existing treeland_pointer_device_configuration_v1 objects created from this object are also destroyed.
get_pointer_configuration(id: new_id<treeland_pointer_device_configuration_v1>, serial: uint)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_pointer_device_configuration_v1> | |
| serial | uint | serial from the last done event |
Create a treeland_pointer_device_configuration_v1 object for this touchpad settings scope.
The created object manages touchpad device configuration on the target seat. The serial argument must match the serial from the most recent done event sent on the previous treeland_pointer_device_configuration_v1 object for this treeland_touchpad_settings_v1 object. For the first creation, the serial should be 0.
Only one treeland_pointer_device_configuration_v1 object may exist for this treeland_touchpad_settings_v1 object at a time. Creating a second one without destroying the first is a protocol error.
If the serial does not match the current state, the compositor may immediately send a failed event on the new treeland_pointer_device_configuration_v1 object.
treeland_keyboard_settings_v1
The treeland_keyboard_settings_v1 interface represents pending settings for all keyboards associated with the target seat.
Requests on this object update pending keyboard state. The compositor applies the accumulated settings when the client sends apply.
The compositor sends keyboard-specific state events after object creation to report the current effective settings for the target seat. It may later send additional state batches when those effective settings change for compositor-defined reasons. A done event terminates each event batch.
destroy()
Destroy this treeland_keyboard_settings_v1 object.
Destroying the object discards any pending state that has not yet been applied.
Argument | Type | Description |
|---|---|---|
| rate | int | repeat rate in characters per second |
| delay | int | delay in milliseconds before repeating starts |
Set the keyboard repeat rate and delay to apply on the next apply request.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause a repeat event to be emitted.
set_num_lock(state: uint<treeland_keyboard_settings_v1.toggle_state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_keyboard_settings_v1.toggle_state> | desired num lock state |
Set the num lock state to apply on the next apply request. This request requires the num_lock feature to be advertised via the feature event.
This request updates only the pending state tracked by this object. Sending this request, or the following apply request, does not by itself cause a num_lock event to be emitted.
apply()
Ask the compositor to apply the pending keyboard settings carried by this object.
Argument | Type | Description |
|---|---|---|
| layout | stringallow null | comma-separated XKB layout names, or empty for the default |
| model | stringallow null | XKB keyboard model, or empty for the default |
| variant | stringallow null | comma-separated XKB variants, or empty for none |
| options | stringallow null | comma-separated XKB options, or empty for none |
Set the XKB layout, model, variant, and options to apply on the next apply request. These four values form one configuration snapshot and replace the complete pending XKB rules state.
Layout contains one or more comma-separated layout names, for example "us" or "cz,us". An empty layout selects the XKB default layout, which is "us".
Model identifies the keyboard model, for example "pc104" or "pc105". An empty model selects the XKB default model.
Variant contains a comma-separated list whose entries correspond to the layouts, for example "" or ",dvorak". Empty entries select no variant for the corresponding layout.
Options contains a comma-separated list of XKB options, for example "grp:win_space_toggle". An empty options string selects no extra options.
This request updates only the pending state tracked by this object. Multiple calls before apply replace the complete pending XKB rules configuration; only the last configuration is applied. Sending this request, or the following apply request, does not by itself cause an xkb_rules event to be emitted.
feature(feature: uint<treeland_keyboard_settings_v1.feature>)
Argument | Type | Description |
|---|---|---|
| feature | uint<treeland_keyboard_settings_v1.feature> | supported keyboard features |
This event reports which optional features are supported by at least one keyboard device associated with the target seat.
The compositor sends this event as part of the initial state batch after the treeland_keyboard_settings_v1 object is created.
The compositor may also send this event again when keyboard devices are added to or removed from the target seat and the set of supported features changes.
Argument | Type | Description |
|---|---|---|
| rate | int | repeat rate in characters per second |
| delay | int | delay in milliseconds before repeating starts |
This event reports the current keyboard repeat configuration.
The compositor sends this event immediately after the treeland_keyboard_settings_v1 object is created as part of the initial keyboard state batch.
Changes requested through set_repeat do not cause this event to be emitted automatically.
num_lock(state: uint<treeland_keyboard_settings_v1.toggle_state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_keyboard_settings_v1.toggle_state> | current num lock state |
This event reports the current num lock state.
The compositor sends this event immediately after the treeland_keyboard_settings_v1 object is created as part of the initial keyboard state batch.
Changes requested through set_num_lock do not cause this event to be emitted automatically.
failed()
This event indicates that the compositor failed to apply one or more pending keyboard settings carried by this object.
This event does not destroy the object. The client may continue using the object and send further requests.
done()
This event is sent once when all keyboard state events in the current batch have been sent.
The compositor must always end a batch of keyboard state events with this event, regardless of whether it sends the initial state or a later update.
Argument | Type | Description |
|---|---|---|
| layout | string | comma-separated XKB layout names, or empty for the default |
| model | string | XKB keyboard model, or empty for the default |
| variant | string | comma-separated XKB variants, or empty for none |
| options | string | comma-separated XKB options, or empty for none |
This event reports the current XKB layout, model, variant, and options as one consistent configuration snapshot. The string formats and empty-value semantics match set_xkb_rules.
The compositor sends this event after object creation as part of the initial keyboard state batch. It may send the event again in a later batch when any effective XKB rules value changes.
feature { num_lock }
Argument | Value | Description |
|---|---|---|
| num_lock | 1 | device supports configuring num lock state |
Optional features supported by keyboard devices. The compositor sends a feature event to indicate which features are supported by at least one keyboard device associated with the target seat. A client must only send a set request if the corresponding feature has been advertised. It is a protocol error to send a set request for a feature that has not been advertised.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT