Treeland active notify

seat activity notification for treeland

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.

factory for seat activity notifiers

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 manager

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
idnew_id<treeland_active_notify_v1>
the new activity notifier object
seatobject<wl_seat>
the seat to observe
create a new seat activity notifier

Create a new treeland_active_notify_v1 object that reports activity for the given seat. The seat must be a valid, current wl_seat.


seat activity notifier

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 activity notifier

Destroy the treeland_active_notify_v1 object. The compositor stops reporting activity for the seat bound to this notifier.

Argument
Type
Description
reasonuint<treeland_active_notify_v1.reason>
the activity source
stateuint<treeland_active_notify_v1.activity_state>
the new activity state
an activity source changed 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.

Argument
Type
Description
stateuint<treeland_active_notify_v1.drag_state>
the new drag and drop lifecycle state
a drag and drop operation changed 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.

reason { mouse, wheel } 
Argument
Value
Description
mouse0
left pointer button activity
wheel1
pointer wheel activity
activity source

The input source that triggered an activity event. Used by the activity_changed event. See the interface description for the per-source semantics.

activity_state { inactive, active } 
Argument
Value
Description
inactive0
the activity source is inactive
active1
the activity source is active
activity state

The state reported by the activity_changed event. See the interface description for the per-source semantics.

drag_state { started, dropped, cancelled } 
Argument
Value
Description
started0
a drag and drop operation started
dropped1
a drag and drop operation completed with a drop
cancelled2
a drag and drop operation ended without a drop
drag and drop lifecycle state

The state reported by the drag_changed event.


Compositor Support

No compositor support found

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