Using the Drag Directive

The Drag directive allows you to make display objects draggable with the mouse or touch. This is useful for creating interactive elements that users can move around the canvas.

Basic Usage

To make an element draggable, simply add the drag attribute to it:

<Sprite image="path/to/image.png" drag />

Configuration Options

You can configure the drag behavior by passing an object with options:

<script>
import { signal } from "canvasengine";

const drag = {
  direction: 'all', // 'all', 'x', or 'y'
  snap: 10, // Optional: snap to grid with specified interval
  start() {
    console.log("Drag started");
  },
  move(event) {
    console.log("Dragging", event.global.x, event.global.y);
  },
  end() {
    console.log("Drag ended");
  }
};
</script>

<Sprite image="path/to/image.png" drag={drag} />

Available Options

• direction: Controls the axis of movement ('all', 'x', or 'y')
• snap: Optional number that determines grid snapping
• start(): Callback function triggered when dragging starts
• move(event): Callback function called continuously during dragging
• end(): Callback function triggered when dragging ends

Disabling Drag

To disable drag functionality on an element that previously had it, you can pass an empty object:

<script>
// Enable drag
const dragEnabled = signal({
  direction: 'all'
});

// Later, to disable drag:
dragEnabled.set({});
</script>

<Sprite image="path/to/image.png" drag={dragEnabled} />

Viewport Integration

When used within a Viewport, the Drag directive can automatically scroll the viewport when dragging elements near the edges. This is particularly useful for large game maps or workspaces.

To enable viewport scrolling, add the viewport property to your drag configuration:

<script>
const drag = {
  // Basic drag options
  direction: 'all',
  
  // Viewport scrolling options
  viewport: {
    edgeThreshold: 100, // Distance from edge to trigger scrolling (pixels)
    maxSpeed: 10        // Maximum scrolling speed
  }
};
</script>

<Viewport worldWidth={2000} worldHeight={2000}>
  <Sprite image="path/to/image.png" drag />
</Viewport>

Viewport Options

• edgeThreshold: Distance in pixels from the viewport edge that triggers scrolling
• maxSpeed: Maximum speed of viewport scrolling when an element is dragged to the edge

WARNING

The drag directive is incompatible with elements that have viewportFollow enabled. If you want to make an element draggable that previously had viewport following enabled, you must set viewportFollow to false first:

<script>
import { signal } from "canvasengine";

const viewportFollow = signal(false); // Must be false for drag to work properly
const drag = signal({
  direction: 'all'
});
</script>

<Sprite 
  image="path/to/image.png" 
  viewportFollow
  drag
/>