dnd

Documentation

Overview

Package dnd is the backend-agnostic drag-and-drop state machine that every native windowing backend shares. The toolkit defines the DnD primitives — the DragSource / DropTarget interfaces and the EventDragStart / EventDragMove / EventDragLeave / EventDrop lifecycle — but deliberately runs no pointer loop of its own, so it cannot originate a drag. Each backend's raw pointer stream carries only presses, drags and releases (EventClick / EventMouseDrag / EventMouseUp); until now only the wasmbox compositor host synthesized the lifecycle from them, so a real drag in an X11, Wayland, Cocoa or Win32 window did nothing.

A Controller closes that gap ONCE, in a place all backends call: it watches the raw pointer events flowing to the root widget, hit-tests the widget tree for a DragSource under the press, and — once the pointer crosses a small threshold — begins a drag carrying that source's DragData, hit-testing for a DropTarget on each move to deliver EventDragStart / EventDragMove / EventDragLeave for feedback and, on release over an accepting target, EventDrop with the payload. When no DragSource is under the press it is inert: the raw events pass through untouched, so plain mouse behaviour is preserved.

The controller depends only on the toolkit's public interfaces, so it holds no reference to any backend and every backend embeds the same instance.

Index

• Constants
• type Controller
  • func New() *Controller
  • func (c *Controller) Bind(root toolkit.Widget)
  • func (c *Controller) Dragging() bool
  • func (c *Controller) Process(ev toolkit.Event) []toolkit.Event

Constants

const Threshold = 4

Threshold is the pointer travel, in pixels, a press must exceed before a candidate drag becomes a live drag. Below it a press+move+release is a plain click, so a slightly shaky click never starts a drag. Manhattan distance on each axis (not Euclidean) — cheap and indistinguishable at this scale.

Types

type Controller

type Controller struct {
	// contains filtered or unexported fields
}

Controller is the shared drag-and-drop state machine. The zero value is not usable; construct one with New and bind the root widget with Bind before feeding it events. It is single-goroutine (driven from the backend's event loop) and keeps no locks.

func New

func New() *Controller

New returns an unbound Controller. Call Bind with the root widget before feeding it events.

func (*Controller) Bind

func (c *Controller) Bind(root toolkit.Widget)

Bind sets (or replaces) the root widget the controller hit-tests against. A backend calls it when it binds its root, mirroring where it stores root itself.

func (*Controller) Dragging

func (c *Controller) Dragging() bool

Dragging reports whether a live drag is in progress (past the threshold). A backend may consult it to, e.g., suppress a hover cue or change the cursor.

func (*Controller) Process

func (c *Controller) Process(ev toolkit.Event) []toolkit.Event

Process consumes one raw toolkit event and returns the events the backend should actually deliver to the root widget, in order. Presses, drags and releases are interpreted against the DnD state machine; every other kind (and every pointer event while no DragSource is involved) passes through unchanged, so a controller in the event path is transparent to all non-drag input.