diff --git a/CMakeLists.txt b/CMakeLists.txt index 3d4291b..53ddf82 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -13,6 +13,7 @@ include(CMakePackageConfigHelpers) # Public protocol XML files (for general application developers) set(TREELAND_PROTOCOL_XML_FILES + public/treeland-snap-target-unstable-v1.xml public/treeland-window-transition-unstable-v1.xml public/treeland-appearance-unstable-v1.xml public/treeland-decoration-unstable-v1.xml diff --git a/public/README.md b/public/README.md index aa4f850..7801488 100644 --- a/public/README.md +++ b/public/README.md @@ -5,6 +5,7 @@ For general application developers. Installed via `TREELAND_PROTOCOL_XML_FILES`. | File | Protocol | Interfaces | Purpose | |------|----------|-----------|---------| | `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | Window open/close transition relative to a rectangle, with optional source image | +| `treeland-snap-target-unstable-v1.xml` | `treeland_snap_target_unstable_v1` | `treeland_snap_target_v1` | Compositor-side snap region hints; an optional pidfd event for window targets can be enabled via the `event_type.pidfd` bit of `start` | | `treeland-appearance-unstable-v1.xml` | `treeland_appearance_unstable_v1` | `treeland_appearance_v1` | Query and observe user-level appearance settings: cursor theme/size, fonts, icon theme, accent color, window opacity, color scheme, titlebar height, corner radius | | `treeland-decoration-unstable-v1.xml` | `treeland_decoration_unstable_v1` | `treeland_decoration_manager_v1`, `treeland_decoration_context_v1` | Per-window server-side decoration (SSD) customization by applications: corner radius, shadow, border, titlebar visibility; requires xdg-decoration SSD | ## Breaking changes diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 1640345..2e4c976 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -5,6 +5,7 @@ | 文件 | 协议 | 接口 | 用途 | |------|----------|-----------|---------| | `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | 相对某个矩形的窗口打开/关闭转场，可附带源图像 | +| `treeland-snap-target-unstable-v1.xml` | `treeland_snap_target_unstable_v1` | `treeland_snap_target_v1` | 合成器侧吸附区域提示；窗口目标的 pidfd 事件为可选项，需在 `start` 中置 `event_type.pidfd` 位启用 | | `treeland-appearance-unstable-v1.xml` | `treeland_appearance_unstable_v1` | `treeland_appearance_v1` | 查询与订阅用户级外观设置：光标主题/大小、字体、图标主题、强调色、窗口不透明度、配色方案、标题栏高度、圆角 | | `treeland-decoration-unstable-v1.xml` | `treeland_decoration_unstable_v1` | `treeland_decoration_manager_v1`, `treeland_decoration_context_v1` | 逐窗口服务端装饰（SSD）定制：圆角、阴影、边框、标题栏可见性；需先经 xdg-decoration 申请 SSD | diff --git a/public/treeland-snap-target-unstable-v1.xml b/public/treeland-snap-target-unstable-v1.xml new file mode 100644 index 0000000..63d234d --- /dev/null +++ b/public/treeland-snap-target-unstable-v1.xml @@ -0,0 +1,219 @@ + + + + + + This protocol allows a client to request snap region hints from the + compositor. While snapping is active, the compositor tracks the cursor + position and notifies the client of the rectangle currently hovered by + the cursor (e.g., a window boundary or a full output). The client uses + these hints to draw its own snap preview UI. + + Snap targets are computed against the window layout captured when the + snap session starts: the compositor records the position and stacking + order of every window at that moment and keeps them unchanged for the + whole session. Windows that move, are mapped or unmapped, change + stacking order, or are destroyed after start are not reflected in the + snap targets. + + A client may identify an overlay surface by setting the xdg-toplevel-tag + "org.deepin.treeland.snap-mask" on that toplevel. When the compositor + detects this tag, it applies the following configuration to the surface: + + 1. Raises the surface above normal windows and their popup panels. + 2. Disables window open/close animations. + 3. Excludes the surface from the multitask view and window switcher. + 4. Disables automatic positioning by the compositor's layout engine. + + Such a surface does not affect the snapping protocol; snapping + behaves the same whether or not the surface exists. Surfaces + carrying the snap-mask tag are excluded from snapping, i.e., they + are never reported as snap targets. + + 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 interface is a global singleton for requesting snap region hints + from the compositor. Each client binds at most one instance of this + global. The compositor tracks the cursor position and notifies the + client of the rectangle currently hovered by the cursor. + + The snap object is created in an idle state. The client starts + snapping by calling start, which causes the compositor to capture the + current window positions and stacking order and begin tracking the + cursor position, providing snap region hints based on the captured + layout. + + While snapping is active, the compositor sends a snap_region event + each time the snap target changes (i.e., when the cursor moves to a + different window or output). A client that also needs to know which + process owns a window snap target can enable the optional pidfd event + by setting the event_type.pidfd bit in the events argument of start; + without that bit the compositor sends no pidfd events. When enabled, + and when the new snap target is a window with a determinable owning + process, a pidfd event reporting that process is sent before the + snap_region event it applies to. The client can use these events to + update its snap preview UI. + + When the client is done (e.g., the user has clicked or dragged to + confirm a selection in the client's UI), the client calls stop to + stop snap notifications. A stopped snap object may be restarted by + calling start again. + + Only one snap session may be active across all clients at any time. + If another client's snap session is active, start fails with the + snap_busy reason. + + + + + + + + + + Bitfield of optional events the client may request when starting a + snap session. Bits not listed here are reserved for future events + and are ignored by the compositor. + + + + + + + Destroy the treeland_snap_target_v1 object. If snapping is in + progress, the compositor automatically stops it (stops cursor + tracking). No further events are emitted on this object. + + + + + + Request the compositor to capture the current window positions and + stacking order and begin tracking the cursor, sending snap region + hints based on the captured layout. + + The seat argument associates this snap session with a seat. How the + compositor uses the seat is compositor policy. + + This request may be called again after stop to restart snapping; a + fresh capture of the window layout is taken on every start. start + must not be called on an already active snap object; the compositor + ignores such a request. + + The events argument selects which optional events the compositor may + send for this session. It is a bitfield of event_type values: only + the events whose bits are set are enabled, and passing 0 enables no + optional events. Bits that do not correspond to a known event_type + value are ignored. The selection applies to this session only; a + start after stop establishes a new selection. + + If snapping cannot be started because another client's snap session + is already active, the compositor sends a failed event with the + snap_busy reason instead. + + + + + + + + Signal that the client is done with snapping. The compositor stops + tracking the cursor and stops sending snap_region events. + + This request is a no-op if snapping is not in progress (e.g., if + failed was already emitted or stop was already called). + + The client should call destroy afterwards to free the snap object. + + + + + + Reports the process owning the window that corresponds to the snap + target reported by the next snap_region event. This event is sent + only if the client enabled the event_type.pidfd bit in the events + argument of start; otherwise it is never sent. When enabled, the + compositor sends this event before the snap_region event it applies + to, and only when the snap target is a window whose owning process + can be determined. If the snap target is not a window (for example an + output or empty desktop space), or the owning process cannot be + determined, this event is omitted and snap_region is sent on its own. + + No pidfd event is ever sent for a snap target whose window was + destroyed after start: the captured region remains a snap target, + but its owning process no longer exists. + + The client owns the received file descriptor and is responsible for + closing it. The descriptor stays valid independently of the snap + session. + + + + + + + Notifies the client of the current snap target rectangle. The snap + target set is captured at start and is fixed for the whole session: + a window that moves, is mapped or unmapped, changes stacking order, + or is destroyed after start does not add, remove, move, resize, or + reorder the targets captured at start. In particular, a window + destroyed after start keeps its captured region as a snap target. + This event is sent each time the snap target changes due to cursor + movement. + + This event commits the snap target. A pidfd event, when sent for + this target, precedes it and reports the process owning the target. + When processing this event, the client should associate the most + recent preceding pidfd event, if any, with this target; if no pidfd + event precedes it, the target has no associated process. + + The region is in global logical coordinates (i.e., the + xdg_output logical coordinate space). The client is responsible for + any coordinate transformation needed for its UI. + + If width and height are both zero, there is no current snap target + (e.g., the cursor is over empty desktop space). The client should + hide its snap preview in this case. + + + + + + + + + + Snapping could not be started. The compositor + will not send any more snap_region events. The client should call + destroy to free the snap object. + + This event is sent when another client's snap session is already + active (reason snap_busy). + + + + +