Window drag handling: KWin effect calls beginDrag / updateDragCursor / endDrag; daemon returns a DragPolicy and a DragOutcome that drive the compositor's drag streaming, keyboard grab, snap geometry, and snap-assist follow-on. A shell registers a drop proxy (registerDropProxy / unregisterDropProxy) so a drag dropped on its miniature of a snapping screen lands in the real zone. Uses int for cursor / modifier flags and the typed DragPolicy / DragOutcome structs for the typed payloads.
| Well-known name | org.phosphor_works.Placement.WindowDrag |
| Source XML | org.phosphor_works.Placement.WindowDrag.xml |
| Methods | 7 |
| Signals | 4 |
| Properties | 0 |
Phase 3 drag protocol: daemon-authoritative begin. Returns a DragPolicy that the compositor plugin uses to decide streaming, keyboard grab, and immediate-float behavior. Replaces dragStarted as the canonical drag-begin entry point. The daemon is the single source of truth, so no effect-side cache goes stale after settings reloads. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| frameX | in | i (int32) | |
| frameY | in | i (int32) | |
| frameWidth | in | i (int32) | |
| frameHeight | in | i (int32) | |
| startScreenId | in | s (string) | Virtual-screen-aware screen identifier at drag start. |
| mouseButtons | in | i (int32) | Qt::MouseButtons flags. |
| policy | out | (bbbbbss) (struct(bool,bool,bool,bool,bool,string,string)) | DragPolicy struct: {streamDragMoved, showOverlay, grabKeyboard, captureGeometry, immediateFloatOnStart, screenId, bypassReason}. |
Phase 3 drag protocol: hot-path cursor update. Replaces dragMoved. Fire-and-forget, and throttled to about 30Hz by the plugin. For snap-path drags the daemon runs overlay/zone detection. For bypass drags it watches for cursor crossing a virtual-screen boundary and emits dragPolicyChanged when the policy flips (autotile↔snap). Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | |
| cursorX | in | i (int32) | |
| cursorY | in | i (int32) | |
| modifiers | in | i (int32) | |
| mouseButtons | in | i (int32) |
Phase 3 drag protocol: daemon-authoritative end. Returns a DragOutcome the plugin applies verbatim, with no further decisions on the plugin side. Handles autotile float, snap, drag-out unsnap, snap assist, and cancelled-drag paths through a single dispatch. Replaces dragStopped as the canonical drag-end entry point. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier (must match the windowId from beginDrag). |
| cursorX | in | i (int32) | |
| cursorY | in | i (int32) | |
| modifiers | in | i (int32) | Qt::KeyboardModifiers at release. |
| mouseButtons | in | i (int32) | Qt::MouseButtons at release. |
| cancelled | in | b (bool) | True if the drag was cancelled (Escape, external cancel). False for normal button release. |
| outcome | out | (issiiiisbba(siiiiiibsssdd)) (struct(int32,string,string,int32,int32,int32,int32,string,bool,bool,array<struct(string,int32,int32,int32,int32,int32,int32,bool,string,string,string,double,double)>)) | DragOutcome struct: {action, windowId, targetScreenId, x, y, width, height, zoneId, skipAnimation, requestSnapAssist, emptyZones}. |
Register, or replace, a screen's drop proxy: a miniature of that screen's snapping zones that a real compositor drag can be dropped on. The Phosphor shell registers its placement map here. During a snap-path drag with the activation trigger held (the same condition under which the real zones light up), a cursor inside the proxy's rect is treated as being over the real zone of the cell under it: the daemon highlights that zone through the overlay, emits its geometry through zoneGeometryDuringDragChanged, and endDrag inside the cell snaps the dragged window to it, all through the path a real zone takes. Inside the rect but over no cell, or over a cell whose zone the screen's current layout no longer has, is no target. Zone-span painting ignores the proxy. There is one proxy per screen. Registering again replaces it, and the registration outlives any drag until unregisterDropProxy. Snapping screens only: on a tiling or scrolling screen the proxy is accepted and ignored, because the snap path never runs there. A malformed proxy is refused silently and any earlier registration stands. A proxy another peer registered on the screen can be replaced only by that peer. Any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Physical screen the miniature is drawn on. A virtual screen on that output resolves to it. An empty string is ignored. |
| proxyJson | in | s (string) | JSON object {rect, cells}: rect is the miniature's [x, y, w, h] and cells an array of {id, rect}, where id is the snapping zone id (braces included) and rect the cell's [x, y, w, h]. Every rect is in the screen's logical coordinates with its top-left corner as origin and must have a positive size, and every cell needs a non-empty id. |
Drop the proxy registered for a screen. A screen with no proxy is a silent no-op. Only the peer that registered the proxy may drop it. Any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Screen whose proxy to drop. |
Forward scroll delta to the zone selector during drag. Reserved for future use when KWin exposes pointer axis events to effects. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| angleDeltaY | in | i (int32) | Vertical scroll delta in 1/8 degree units (positive=up, negative=down). Standard wheel tick is ±120. |
Cancel the current snap operation (e.g. user pressed Escape). Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
No arguments.
Emitted when the zone geometry under the cursor changes during drag. KWin effect applies the geometry immediately for snap-on-hover behavior.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window identifier. |
| x | out | i (int32) | Zone X position (pixels). |
| y | out | i (int32) | Zone Y position (pixels). |
| width | out | i (int32) | Zone width (pixels). |
| height | out | i (int32) | Zone height (pixels). |
Emitted when the cursor leaves all zones during drag and the window was snapped. KWin effect applies pre-snap size immediately (restore-size-only at current position).
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window identifier. |
| width | out | i (int32) | Pre-snap width (pixels). |
| height | out | i (int32) | Pre-snap height (pixels). |
Phase 3 drag protocol: daemon detected a policy flip mid-drag (typically because the cursor crossed a virtual-screen boundary that changes autotile↔snap routing). Plugin reacts by applying the transition: entering/exiting autotile bypass, canceling snap overlay, calling handleDragToFloat, etc. Replaces the effect-side cross-VS flip loop that used a stale local cache.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | |
| newPolicy | out | (bbbbbss) (struct(bool,bool,bool,bool,bool,string,string)) |
Emitted asynchronously after endDrag returns, when the drop requested snap assist (outcome.requestSnapAssist=true). Carries the list of empty zones on the release screen. The effect subscribes and shows the window picker from its slot, discarding the signal if a new drag has already started. Deferring the empty-zone-list computation here keeps the endDrag D-Bus reply fast — the compositor is unblocked before buildEmptyZoneList walks the zone list.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | |
| releaseScreenId | out | s (string) | |
| emptyZones | out | a(siiiiiibsssdd) (array<struct(string,int32,int32,int32,int32,int32,int32,bool,string,string,string,double,double)>) |