Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
org.phosphor_works.Placement.WindowDrag

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

Methods

beginDrag()

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

updateDragCursor()

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)

endDrag()

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

registerDropProxy()

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.

unregisterDropProxy()

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.

selectorScrollWheel()

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.

cancelSnap()

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.

Signals

zoneGeometryDuringDragChanged

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

restoreSizeDuringDragChanged

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

dragPolicyChanged

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

snapAssistReady

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