DragDrop

ceramic.Entityelements.DragDrop (Class)

A component that enables drag-and-drop functionality for visuals.

This component handles the complete drag-and-drop lifecycle:

  • Detecting drag initiation based on pointer movement threshold
  • Creating and managing a dragging visual representation
  • Tracking drag position updates
  • Handling drag completion and visual cleanup

The component can work with custom visual factories to create drag representations and provides observable properties for tracking drag state and position.

Example usage:

var dragDrop = new DragDrop(
    5.0, // threshold
    clickComponent,
    () -> createDragVisual(),
    (visual) -> recycleDragVisual(visual)
);
myVisual.component('dragDrop', dragDrop);

// Listen to drag events
dragDrop.onDraggingChange(this, dragging -> {
    if (dragging) trace('Started dragging');
    else trace('Stopped dragging');
});
See: CellView For usage in draggable cells, Window For draggable window implementation

Instance Members

elements
observedDirty: Bool

Default is false, automatically set to true when any of this instance's observable variables has changed.


elements
dragging: Bool

Whether a drag operation is currently active. Observable property that changes when dragging starts/stops.


elements
dragX: Float

The current horizontal drag offset from the drag start position. Updated continuously during drag operations.


elements
dragY: Float

The current vertical drag offset from the drag start position. Updated continuously during drag operations.


elements
click: ceramic.Click

Optional click component to cancel when drag starts. Prevents click events from firing when the user drags.


elements
threshold: Float

Minimum pointer movement distance to initiate drag. Prevents accidental drags from small movements.


elements
draggingVisual: ceramic.Visual

The visual being displayed during drag operation. Created by getDraggingVisual and cleaned up by releaseDraggingVisual.


elements
entity: ceramic.Visual

The visual entity this component is attached to.


elements
initializerName: String

elements
invalidateDragging(): Void

elements
invalidateDragX(): Void

elements
invalidateDragY(): Void

elements
getDraggingVisual(): ceramic.Visual

Factory function to create the visual shown during dragging. Called when drag operation starts. Should return a Visual that represents the dragged content.

Returns
ceramic.Visual

elements
releaseDraggingVisual(): Void

Function to handle cleanup when dragging ends. Called with the dragging visual to allow recycling or disposal. If null, the dragging visual reference is simply cleared.


elements
drag(?pointerX: Float, ?pointerY: Float): Void

Programmatically starts a drag operation. Can be called to initiate dragging without waiting for threshold.

Name Type Default Description
pointerX Float (optional) X position to start drag from (defaults to current pointer position)
pointerY Float (optional) Y position to start drag from (defaults to current pointer position)

elements
new(?threshold: Float = 4.0, ?click: ceramic.Click, getDraggingVisual: Function, releaseDraggingVisual: Function): Void

Creates a new DragDrop component.

Name Type Default Description
threshold Float 4.0 Minimum pointer movement to start drag (default: 4.0 pixels)
click ceramic.Click (optional) Optional click component to cancel when dragging starts
getDraggingVisual Function Factory function to create the drag visual
releaseDraggingVisual Function Cleanup function for the drag visual

Private Members

elements
unobservedDragging: Bool

elements
unobservedDragX: Float

elements
unobservedDragY: Float

elements
visualDragStartX: Float

Initial X position of the dragging visual.


elements
visualDragStartY: Float

Initial Y position of the dragging visual.


elements
pointerDownX: Float

X position where pointer was initially pressed.


elements
pointerDownY: Float

Y position where pointer was initially pressed.


elements
pointerDragStartX: Float

X position where drag operation started.


elements
pointerDragStartY: Float

Y position where drag operation started.


elements
isPointerDown: Bool

Whether pointer is currently pressed down.


elements
emitObservedDirty(instance: DragDrop, fromSerializedField: Bool): Void

Event when any observable value as changed on this instance.

Name Type
instance DragDrop
fromSerializedField Bool

elements
emitDraggingChange(current: Bool, previous: Bool): Void

Event when dragging field changes.

Name Type
current Bool
previous Bool

elements
emitDragXChange(current: Float, previous: Float): Void

Event when dragX field changes.

Name Type
current Float
previous Float

elements
emitDragYChange(current: Float, previous: Float): Void

Event when dragY field changes.

Name Type
current Float
previous Float

elements
bindAsComponent(): Void

Called when this component is bound to an entity. Sets up pointer down event listener on the target visual.


elements
handlePointerDown(info: ceramic.TouchInfo): Void

Handles pointer down events on the target visual. Initializes tracking for potential drag operation.

Name Type
info ceramic.TouchInfo

elements
handlePointerMove(info: ceramic.TouchInfo): Void

Handles pointer move events during potential or active drag. Checks threshold and updates drag position.

Name Type
info ceramic.TouchInfo

elements
handlePointerUp(info: ceramic.TouchInfo): Void

Handles pointer up events to end drag operation. Cleans up event listeners and releases dragging visual.

Name Type
info ceramic.TouchInfo

elements
updateDrag(pointerX: Float, pointerY: Float): Void

Updates the drag position based on current pointer coordinates. Converts screen coordinates to visual space if dragging visual has a parent.

Name Type Description
pointerX Float Current pointer X position in screen space
pointerY Float Current pointer Y position in screen space

elements
setEntity(entity: ceramic.Entity): Void
Name Type
entity ceramic.Entity

elements
getEntity(): ceramic.Entity
Returns
ceramic.Entity

Metadata

Name Parameters
:build tracker.macros.ObservableMacro.build()
:autoBuild tracker.macros.ObservableMacro.build()
:build ceramic.macros.ComponentMacro.build()
:autoBuild ceramic.macros.ComponentMacro.build()
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()