DragDrop

View source
ceramic.Entity → elements.DragDrop (Class)
Implements: tracker.Observable, ceramic.Component

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

Events

@event observedDirty(instance: DragDrop, fromSerializedField: Bool)

Event when any observable value as changed on this instance.

Name Type
instance DragDrop
fromSerializedField Bool
onObservedDirty(owner, handler) onceObservedDirty(owner, handler) offObservedDirty(?handler) listensObservedDirty()
@event draggingChange(current: Bool, previous: Bool)

Event when dragging field changes.

Name Type
current Bool
previous Bool
onDraggingChange(owner, handler) onceDraggingChange(owner, handler) offDraggingChange(?handler) listensDraggingChange()
@event dragXChange(current: Float, previous: Float)

Event when dragX field changes.

Name Type
current Float
previous Float
onDragXChange(owner, handler) onceDragXChange(owner, handler) offDragXChange(?handler) listensDragXChange()
@event dragYChange(current: Float, previous: Float)

Event when dragY field changes.

Name Type
current Float
previous Float
onDragYChange(owner, handler) onceDragYChange(owner, handler) offDragYChange(?handler) listensDragYChange()

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