DragSession

Live state and controller of an active drag gesture, managing pointer coordinates, active drop target, ghost positioning, insertion indicators, and autoscrolling.

Overview

DragSession represents an active drag-and-drop interaction.

Session Responsibilities

• Pointer Tracking: Manages root coordinates (pointerX, pointerY), press coordinates, and delta displacements (deltaX, deltaY).
• Drop Target Coordination: Tracks the current accepting dropTarget() widget.
• Overlay Rendering: Coordinates DragGhost rendering and insertion indicator rectangles (showIndicator, clearIndicator).
• Autoscroll Integration: Coordinates container autoscrolling when the pointer hovers near scrollable container edges.

Displaying a Drop Indicator

session.showIndicator(x, y, width, 2.0f, MutableColor.rgba(0.2f, 0.6f, 1.0f, 1.0f));

Related links

• DragController: Drag gesture controller attachable to any widget via composition to initiate drag-and-drop operations with ghost previews, threshold handling, and autoscrolling.
• DropController: Drop target controller attachable to any widget via composition to filter payloads and handle drag enter, over, leave, and drop events.

API

DragSession::active()

Returns true while the drag session is actively ongoing.

Returns boolean: True if the drag session is active and not cancelled..

DragSession::cancel()

Cancels the active drag gesture.

DragSession::clearIndicator()

Hides the drop insertion indicator.

DragSession::deltaX()

Returns the pointer movement delta along the X axis.

Returns float: Horizontal displacement from the start coordinate in pixels..

DragSession::deltaY()

Returns the pointer movement delta along the Y axis.

Returns float: Vertical displacement from the start coordinate in pixels..

DragSession::dragged()

Returns the widget that is logically moved.

Returns Widget: The logical widget being dragged..

DragSession::dropTarget()

Returns the currently hovered drop zone that accepted the payload, or null.

Returns Widget: The current candidate drop target widget, or null..

DragSession::ghost()

Returns the visual drag ghost used in this session.

Returns DragGhost: The DragGhost renderer used for overlay preview..

DragSession::ghostOffsetX()

Returns the ghost X offset accounting for axis locking and container scroll compensation.

Returns float: Horizontal offset for ghost placement..

DragSession::ghostOffsetX(Widget, float)

Calculates the ghost X offset for a specific widget with initial coordinate compensation.

Parameter	Type	Description
widget	Widget	Reference widget for coordinate calculation.
initialX	float	Initial X coordinate before drag.

Returns float: Horizontal offset for ghost placement..

DragSession::ghostOffsetY()

Returns the ghost Y offset accounting for axis locking and container scroll compensation.

Returns float: Vertical offset for ghost placement..

DragSession::ghostOffsetY(Widget, float)

Calculates the ghost Y offset for a specific widget with initial coordinate compensation.

Parameter	Type	Description
widget	Widget	Reference widget for coordinate calculation.
initialY	float	Initial Y coordinate before drag.

Returns float: Vertical offset for ghost placement..

DragSession::handle()

Returns the handle widget initiating the drag.

Returns Widget: The handle widget that initiated the drag..

DragSession::indicatorColor()

Returns the insertion indicator color.

Returns ColorView: Color of the active indicator rectangle..

DragSession::indicatorHeight()

Returns the insertion indicator height.

Returns float: Height of the active indicator rectangle..

DragSession::indicatorVisible()

Returns true if the insertion indicator is currently visible.

Returns boolean: True if the drop indicator is currently shown..

DragSession::indicatorWidth()

Returns the insertion indicator width.

Returns float: Width of the active indicator rectangle..

DragSession::indicatorX()

Returns the insertion indicator X coordinate.

Returns float: X coordinate of the active indicator rectangle..

DragSession::indicatorY()

Returns the insertion indicator Y coordinate.

Returns float: Y coordinate of the active indicator rectangle..

DragSession::payload()

Returns the payload associated with this drag session.

Returns DragPayload: The transfer payload..

DragSession::pointerX()

Returns the current pointer X coordinate in root space.

Returns float: Current root pointer X coordinate..

DragSession::pointerY()

Returns the current pointer Y coordinate in root space.

Returns float: Current root pointer Y coordinate..

DragSession::pressX()

Returns the initial press X coordinate.

Returns float: Initial root pointer X coordinate at press time..

DragSession::pressY()

Returns the initial press Y coordinate.

Returns float: Initial root pointer Y coordinate at press time..

DragSession::root()

Returns the topmost root widget of the hierarchy.

Returns Widget: The root widget hosting the drag overlay..

DragSession::showIndicator(float, float, float, float, ColorView)

Displays a drop insertion indicator rectangle in the overlay layer.

Parameter	Type	Description
x	float	X coordinate of the indicator rectangle.
y	float	Y coordinate of the indicator rectangle.
width	float	Width of the indicator rectangle.
height	float	Height of the indicator rectangle.
color	ColorView	Color of the indicator rectangle.

DragSession::uiContext()

Returns the UI context for this session.

Returns UIContext: The UI context associated with this session..