Treeland input manager

configure input devices managed by treeland

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.

global input device manager

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()
destroy the input manager

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
idnew_id<treeland_mouse_settings_v1>
seatobject<wl_seat>
seat whose mouse-specific settings are being managed
create a mouse-specific settings object

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
idnew_id<treeland_touchpad_settings_v1>
seatobject<wl_seat>
seat whose touchpad-specific settings are being managed
create a touchpad-specific settings object

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
idnew_id<treeland_keyboard_settings_v1>
seatobject<wl_seat>
seat whose keyboard-specific settings are being managed
create a keyboard settings object

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
typeuint<treeland_input_manager_v1.device_type>
type of the device capability
seatobject<wl_seat>
seat associated with the capability
report an available device 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
typeuint<treeland_input_manager_v1.device_type>
type of the device capability
seatobject<wl_seat>
seat associated with the capability
report an unavailable device 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.

device_type { mouse, touchpad, keyboard } 
Argument
Value
Description
mouse1
mouse input device
touchpad2
touchpad input device
keyboard4
keyboard input device
state { disabled, enabled } 
Argument
Value
Description
disabled0
disabled state
enabled1
enabled state

pointer device configuration object

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 the pointer device configuration object

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
factorfixed
scaling factor applied to scroll axis delta, The factor must be greater than 0.
set the scroll delta scaling factor

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

Argument
Type
Description
modeuint<treeland_pointer_device_configuration_v1.handed_mode>
desired handedness mode
set the 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_speedfixed
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

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.

Argument
Type
Description
profileuint<treeland_pointer_device_configuration_v1.acceleration_profile>
desired acceleration profile
set the 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.

Argument
Type
Description
modeuint<treeland_pointer_device_configuration_v1.send_events_mode>
desired pointer event delivery mode
set the 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
stateuint<treeland_input_manager_v1.state>
desired natural scrolling state
enable or disable natural scrolling

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
stateuint<treeland_input_manager_v1.state>
desired disable-while-typing state
set disable-while-typing

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
stateuint<treeland_input_manager_v1.state>
desired tap-to-click state
set tap-to-click

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()
apply pending pointer device configuration changes

Ask the compositor to apply the pending pointer device configuration carried by this object.

Argument
Type
Description
featureuint<treeland_pointer_device_configuration_v1.feature>
supported pointer device features
report 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
factorfixed
current scroll factor
report the 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.

Argument
Type
Description
modeuint<treeland_pointer_device_configuration_v1.handed_mode>
current handedness mode
report the 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_speedfixed
current pointer acceleration speed
report the 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.

Argument
Type
Description
profileuint<treeland_pointer_device_configuration_v1.acceleration_profile>
current acceleration profile
report the 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.

Argument
Type
Description
modeuint<treeland_pointer_device_configuration_v1.send_events_mode>
current pointer event delivery mode
report the 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
stateuint<treeland_input_manager_v1.state>
current natural scrolling state
report 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
stateuint<treeland_input_manager_v1.state>
current disable-while-typing state
report 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.

Argument
Type
Description
stateuint<treeland_input_manager_v1.state>
current tap-to-click state
report 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()
apply 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
serialuint
current configuration serial
end of a pointer device state batch

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.

Argument
Value
Description
scroll_factor1
device supports configuring scroll factor
handed_mode2
device supports configuring handed mode
accel_speed4
device supports configuring acceleration speed
acceleration_profile8
device supports configuring acceleration profile
send_events_mode16
device supports configuring event delivery mode
natural_scroll32
device supports configuring natural scrolling
disable_while_typing64
device supports disable-while-typing
tap_to_click128
device supports tap-to-click
pointer device features

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.

handed_mode { right, left } 
Argument
Value
Description
right0
right-handed mode
left1
left-handed mode
acceleration_profile { none, flat, adaptive, custom } 
Argument
Value
Description
none0
device does not have a configurable acceleration profile
flat1
use a flat acceleration profile
adaptive2
use an adaptive acceleration profile
custom4
use a custom acceleration profile
pointer acceleration profiles

Pointer acceleration profiles. The semantics correspond to libinput acceleration profiles.

Argument
Value
Description
enabled0
send events from this device normally
disabled1
do not send events from this device
disabled_on_external_mouse2
if an external pointer device is plugged in, do not send events from this device; may be available on built-in pointer devices
pointer event delivery mode

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.


mouse settings factory object

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 the mouse settings object

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
idnew_id<treeland_pointer_device_configuration_v1>
serialuint
serial from the last done event
create a pointer device configuration object

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.


touchpad settings factory object

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 the touchpad settings object

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
idnew_id<treeland_pointer_device_configuration_v1>
serialuint
serial from the last done event
create a pointer device configuration object

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.


keyboard settings object

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 the keyboard settings object

Destroy this treeland_keyboard_settings_v1 object.

Destroying the object discards any pending state that has not yet been applied.

set_repeat(rate: int, delay: int)
Argument
Type
Description
rateint
repeat rate in characters per second
delayint
delay in milliseconds before repeating starts
set keyboard repeat rate and delay

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.

Argument
Type
Description
stateuint<treeland_keyboard_settings_v1.toggle_state>
desired num lock state
set 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()
apply pending keyboard changes

Ask the compositor to apply the pending keyboard settings carried by this object.

set_xkb_rules(layout: string, model: string, variant: string, options: string)
Argument
Type
Description
layoutstringallow null
comma-separated XKB layout names, or empty for the default
modelstringallow null
XKB keyboard model, or empty for the default
variantstringallow null
comma-separated XKB variants, or empty for none
optionsstringallow null
comma-separated XKB options, or empty for none
set the pending XKB rules configuration

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.

Argument
Type
Description
featureuint<treeland_keyboard_settings_v1.feature>
supported keyboard features
report 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.

repeat(rate: int, delay: int)
Argument
Type
Description
rateint
repeat rate in characters per second
delayint
delay in milliseconds before repeating starts
report the current repeat configuration

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.

Argument
Type
Description
stateuint<treeland_keyboard_settings_v1.toggle_state>
current num lock state
report the 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()
apply 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()
end of a keyboard state batch

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.

xkb_rules(layout: string, model: string, variant: string, options: string)
Argument
Type
Description
layoutstring
comma-separated XKB layout names, or empty for the default
modelstring
XKB keyboard model, or empty for the default
variantstring
comma-separated XKB variants, or empty for none
optionsstring
comma-separated XKB options, or empty for none
report the current XKB rules configuration

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.

toggle_state { off, on } 
Argument
Value
Description
off0
off state
on1
on state
feature { num_lock } 
Argument
Value
Description
num_lock1
device supports configuring num lock state
keyboard features

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

No compositor support found

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