org.plasmazones.WindowDrag

Window drag handling: KWin script calls dragStarted/dragMoved/dragStopped; daemon returns snap geometry. Uses double for window rect (KWin QML) and int for cursor/modifiers.

Well-known name	org.plasmazones.WindowDrag
Source XML	org.plasmazones.WindowDrag.xml
Methods	6
Signals	4
Properties	0

Methods

<tt>beginDrag()</tt>

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. Single source of truth — no effect-side cache to go stale after settings reloads.

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}.

<tt>updateDragCursor()</tt>

Phase 3 drag protocol: hot-path cursor update. Replaces dragMoved. Fire-and-forget; throttled ~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).

Arg	Direction	Type	Description
windowId	in	s *(string)*
cursorX	in	i *(int32)*
cursorY	in	i *(int32)*
modifiers	in	i *(int32)*
mouseButtons	in	i *(int32)*

<tt>endDrag()</tt>

Phase 3 drag protocol: daemon-authoritative end. Returns a DragOutcome the plugin applies verbatim — 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.

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}.

<tt>selectorScrollWheel()</tt>

Forward scroll delta to the zone selector during drag. Reserved for future use when KWin exposes pointer axis events to effects.

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.

<tt>cancelSnap()</tt>

Cancel the current snap operation (e.g. user pressed Escape).

No arguments.

<tt>handleWindowClosed()</tt>

Called when a window is closed during or after a drag operation. Cleans up any drag state associated with this window.

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window ID that was closed.

Signals

<tt>zoneGeometryDuringDragChanged</tt>

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).

<tt>restoreSizeDuringDragChanged</tt>

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).

<tt>dragPolicyChanged</tt>

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))*

<tt>snapAssistReady</tt>

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)>)*