Package edu.cnu.mdi.transfer

Class PaletteDragSupport

java.lang.Object

edu.cnu.mdi.transfer.PaletteDragSupport

public final class PaletteDragSupport
extends Object

Installs and manages the drag side of a palette drag-and-drop interaction.

Purpose

Every palette panel that lets the user drag items onto a canvas needs the same Swing DnD boilerplate: create a DragSource gesture recogniser, start the drag with an optional drag image, and clean up the selection when the drag ends. PaletteDragSupport encapsulates that ceremony so that palette panels only have to supply two things:

1. A PaletteDragSupport.PaletteDragSource callback that decides, for a given drag origin point, what Transferable to carry — or null to cancel the drag.
2. Optionally, a PaletteDragSupport.DragImageProvider callback that builds a BufferedImage to display under the cursor during the drag.

Usage

 // In a palette panel constructor:
 new PaletteDragSupport(myTable, origin -> {
     int row = myTable.rowAtPoint(origin);
     int col = myTable.columnAtPoint(origin);
     if (row < 0 || col < 1) return null;           // cancel drag
     MyDescriptor d = buildDescriptor(row, col);
     return d != null ? new MyTransferable(d) : null;
 });
 

To supply a drag image in addition to the transferable:

 new PaletteDragSupport(myTable,
     origin -> buildTransferable(origin),
     origin -> buildDragImage(origin),
     32);   // drag image size in pixels
 

Cleanup callback

PaletteDragSupport calls PaletteDragSupport.PaletteDragSource.onDragEnd() on the EDT after every drag attempt — regardless of whether the drop succeeded or was cancelled, and regardless of whether the drag was even started (i.e. the callback returned null). Palette panels use this to clear their selection highlight.

Thread safety

All Swing DnD callbacks arrive on the EDT. PaletteDragSupport does not introduce any additional threading.

Design notes

Only the drag side of DnD is abstracted here. Drop targets are domain-specific: a map canvas and a network-layout canvas need completely different logic to unpack a payload and create the right item type. Keeping drop-target logic in the canvas implementations avoids forcing unrelated domains into a shared type hierarchy.

See Also:

• PaletteDragSupport.PaletteDragSource
• PaletteDragSupport.DragImageProvider

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	PaletteDragSupport.DragImageProvider	Optionally supplies a BufferedImage to display under the cursor during a drag.
static interface	PaletteDragSupport.PaletteDragSource	Supplies the drag payload and receives end-of-drag notification.

Constructor Summary

Constructors

Constructor	Description
PaletteDragSupport(JComponent source, PaletteDragSupport.PaletteDragSource dragSource)	Install drag support on source with no drag image.
PaletteDragSupport(JComponent source, PaletteDragSupport.PaletteDragSource dragSource, PaletteDragSupport.DragImageProvider imageProvider)	Install drag support on source with a custom drag image.

Method Summary

Modifier and Type	Method	Description
static BufferedImage	scaleToDragImage(Image source, int sidePixels)	Scale a Image into a new square BufferedImage suitable for use as a drag image.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PaletteDragSupport

public PaletteDragSupport(JComponent source,
 PaletteDragSupport.PaletteDragSource dragSource)

Install drag support on source with no drag image.

The drag cursor will be the platform default (typically a small arrow with a copy badge). Use PaletteDragSupport(JComponent, PaletteDragSource, DragImageProvider) to supply a custom drag image.

Parameters:

source - the Swing component to install the gesture recogniser on; must not be null

dragSource - callback that creates the payload and handles cleanup; must not be null

Throws:

IllegalArgumentException - if either argument is null

PaletteDragSupport

public PaletteDragSupport(JComponent source,
 PaletteDragSupport.PaletteDragSource dragSource,
 PaletteDragSupport.DragImageProvider imageProvider)

Install drag support on source with a custom drag image.

The image is only used when DragSource.isDragImageSupported() returns true. On platforms that do not support drag images the imageProvider is never called and the drag falls back to the default cursor.

The size of the drag image is entirely the responsibility of the PaletteDragSupport.DragImageProvider — it returns a fully-rendered BufferedImage of whatever dimensions are appropriate for the palette's content. scaleToDragImage(java.awt.Image, int) is provided as a convenience for the common case of scaling an existing icon image.

Parameters:

source - the Swing component to install the gesture recogniser on; must not be null

dragSource - callback that creates the payload and handles cleanup; must not be null

imageProvider - callback that builds the drag image, or null for no custom image

Throws:

IllegalArgumentException - if source or dragSource is null

Method Details

scaleToDragImage

public static BufferedImage scaleToDragImage(Image source,
 int sidePixels)

Scale a Image into a new square BufferedImage suitable for use as a drag image.

This is provided as a convenience for PaletteDragSupport.DragImageProvider implementations that already have a loaded image and only need to scale it. Rendering hints are set for bilinear interpolation, quality rendering, and anti-aliasing.

Parameters:

source - the source image to scale; must not be null

sidePixels - the side length in pixels of the output square image; must be positive

Returns:

a new BufferedImage of size sidePixels × sidePixels

Throws:

IllegalArgumentException - if source is null or sidePixels is not positive