Treeland active notify
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 a privileged DDE client such as the dock or shell to observe seat activity that the compositor detects: pointer button and wheel activity, and drag and drop lifecycle events, scoped to a given seat.
The compositor must reject bind attempts from non-privileged clients.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
treeland_active_notify_manager_v1
A global that creates treeland_active_notify_v1 objects for privileged DDE clients. Each notifier reports activity for one seat; clients observing several seats create several notifiers.
The compositor must reject bind attempts from non-privileged clients.
destroy()
Destroy the treeland_active_notify_manager_v1 object. Notifiers created through this manager are not affected.
get_active_notify(id: new_id<treeland_active_notify_v1>, seat: object<wl_seat>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_active_notify_v1> | the new activity notifier object |
| seat | object<wl_seat> | the seat to observe |
Create a new treeland_active_notify_v1 object that reports activity for the given seat. The seat must be a valid, current wl_seat.
treeland_active_notify_v1
A notifier object reports seat activity that the compositor detects. Activity is reported as activity_changed events tagged with the source that triggered them and the new activity state. Drag and drop lifecycle changes are reported as drag_changed events tagged with the new drag state.
The mouse and wheel sources have different semantics:
For mouse, activity_changed reports the aggregate state of the left pointer button only. It is sent with state active when the left button is pressed and state inactive when it is released. Other pointer buttons do not generate these events. The compositor sends these events as matched pairs: it must not send a state active event before the matching state inactive event, nor a state inactive event when the left button is not pressed.
For wheel, activity_changed is a discrete per-event pulse, not a persistent state. It is sent with state active for each wheel event whose angle delta is positive, and state inactive for each whose angle delta is negative; the compositor may send several active (or several inactive) events in a row without an intervening opposite state. Clients must treat each wheel event independently and must not infer a lasting state from a single event.
The drag_changed event reports the lifecycle of a drag and drop operation on the seat. It is sent with state started when the operation begins. Exactly one terminal event follows each started event: one with state dropped when the operation completes with a successful drop, or one with state cancelled when the operation ends without a drop (for example because the drag was cancelled or the source destroyed). No further drag events are sent after the terminal event until the next started event.
destroy()
Destroy the treeland_active_notify_v1 object. The compositor stops reporting activity for the seat bound to this notifier.
activity_changed(reason: uint<treeland_active_notify_v1.reason>, state: uint<treeland_active_notify_v1.activity_state>)
Argument | Type | Description |
|---|---|---|
| reason | uint<treeland_active_notify_v1.reason> | the activity source |
| state | uint<treeland_active_notify_v1.activity_state> | the new activity state |
For mouse, sent when the left pointer button is pressed (state active) or released (state inactive). The compositor sends these events as matched pairs.
For wheel, sent for each wheel event: state active when the angle delta is positive, state inactive when it is negative; the compositor may send several active (or several inactive) events in a row without an intervening opposite state.
See the interface description for the per-source semantics.
drag_changed(state: uint<treeland_active_notify_v1.drag_state>)
Argument | Type | Description |
|---|---|---|
| state | uint<treeland_active_notify_v1.drag_state> | the new drag and drop lifecycle state |
Sent when the state of a drag and drop operation on the seat bound to this notifier changes.
A started event is followed by exactly one terminal event: dropped when the operation completes with a successful drop, or cancelled when the operation ends without a drop (for example because the drag was cancelled or the drag source destroyed). No further drag events are sent after the terminal event until the next started event.
The input source that triggered an activity event. Used by the activity_changed event. See the interface description for the per-source semantics.
Argument | Value | Description |
|---|---|---|
| inactive | 0 | the activity source is inactive |
| active | 1 | the activity source is active |
The state reported by the activity_changed event. See the interface description for the per-source semantics.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT