DragDrop
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');
});
Instance Members
Default is false
, automatically set to true
when any of this instance's observable variables has changed.
Whether a drag operation is currently active. Observable property that changes when dragging starts/stops.
The current horizontal drag offset from the drag start position. Updated continuously during drag operations.
The current vertical drag offset from the drag start position. Updated continuously during drag operations.
Optional click component to cancel when drag starts. Prevents click events from firing when the user drags.
Minimum pointer movement distance to initiate drag. Prevents accidental drags from small movements.
The visual being displayed during drag operation. Created by getDraggingVisual and cleaned up by releaseDraggingVisual.
The visual entity this component is attached to.
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 |
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.
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) |
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
Initial X position of the dragging visual.
Initial Y position of the dragging visual.
X position where pointer was initially pressed.
Y position where pointer was initially pressed.
X position where drag operation started.
Y position where drag operation started.
Whether pointer is currently pressed down.
Event when any observable value as changed on this instance.
Name | Type |
---|---|
instance |
DragDrop |
fromSerializedField |
Bool |
Event when dragging field changes.
Name | Type |
---|---|
current |
Bool |
previous |
Bool |
Event when dragX field changes.
Name | Type |
---|---|
current |
Float |
previous |
Float |
Event when dragY field changes.
Name | Type |
---|---|
current |
Float |
previous |
Float |
Called when this component is bound to an entity. Sets up pointer down event listener on the target visual.
Handles pointer down events on the target visual. Initializes tracking for potential drag operation.
Name | Type |
---|---|
info |
ceramic.TouchInfo |
Handles pointer move events during potential or active drag. Checks threshold and updates drag position.
Name | Type |
---|---|
info |
ceramic.TouchInfo |
Handles pointer up events to end drag operation. Cleans up event listeners and releases dragging visual.
Name | Type |
---|---|
info |
ceramic.TouchInfo |
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 |
Name | Type |
---|---|
entity |
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() |