0
# Drag and Drop Support
1

2
JNA Platform provides enhanced drag and drop functionality that extends Java's built-in support with cross-platform ghosted drag images and simplified APIs. This is particularly useful when native drag image support is unavailable or inconsistent across platforms.
3

4
## Capabilities
5

6
### Drag Handler
7

8
Abstract class that provides simplified drag handling for components with ghosted drag images and enhanced visual feedback.
9

10
```java { .api }
11
/**
12
 * Provides simplified drag handling for components with ghosted drag images
13
 * Abstract class requiring implementation of drag gesture handling
14
 */
15
public abstract class DragHandler {
16
    /** Maximum size for ghosted drag images */
17
    public static final Dimension MAX_GHOST_SIZE = new Dimension(250, 250);
18
    /** Default alpha transparency for ghosted images */
19
    public static final float DEFAULT_GHOST_ALPHA = 0.5f;
20
    /** Constant indicating unknown modifier keys */
21
    public static final int UNKNOWN_MODIFIERS = -1;
22
    /** Constant for unknown transferable data */
23
    public static final Object UNKNOWN_TRANSFERABLE = null;
24
    
25
    /**
26
     * Create drag handler for component
27
     * @param dragSource Component that can be dragged
28
     * @param actions Supported drag actions (DnDConstants.ACTION_*)
29
     */
30
    protected DragHandler(Component dragSource, int actions);
31
    
32
    /**
33
     * Utility method to extract transferable data from drop target events
34
     * @param e Drop target event
35
     * @return Transferable data from the event
36
     */
37
    public static Transferable getTransferable(DropTargetEvent e);
38
}
39
```
40

41
### Drop Handler
42

43
Abstract class that provides simplified drop handling for components with optional visual feedback through custom painters.
44

45
```java { .api }
46
/**
47
 * Provides simplified drop handling for components
48
 * Abstract class that implements DropTargetListener
49
 */
50
public abstract class DropHandler implements DropTargetListener {
51
    /**
52
     * Create drop handler for component
53
     * @param dropTarget Component that can receive drops
54
     * @param actions Supported drop actions (DnDConstants.ACTION_*)
55
     */
56
    public DropHandler(Component dropTarget, int actions);
57
    
58
    /**
59
     * Create drop handler with data flavor restrictions
60
     * @param dropTarget Component that can receive drops
61
     * @param actions Supported drop actions
62
     * @param flavors Accepted data flavors
63
     */
64
    public DropHandler(Component dropTarget, int actions, DataFlavor[] flavors);
65
    
66
    /**
67
     * Create drop handler with custom painter for visual feedback
68
     * @param dropTarget Component that can receive drops
69
     * @param actions Supported drop actions
70
     * @param flavors Accepted data flavors
71
     * @param painter Custom painter for drop feedback
72
     */
73
    public DropHandler(Component dropTarget, int actions, DataFlavor[] flavors, DropTargetPainter painter);
74
    
75
    /**
76
     * Check if drop handling is currently active
77
     * @return true if drop handling is active
78
     */
79
    public boolean isActive();
80
    
81
    /**
82
     * Enable or disable drop handling
83
     * @param active true to enable, false to disable
84
     */
85
    public void setActive(boolean active);
86
}
87
```
88

89
### Drop Target Painter
90

91
Interface for providing custom visual feedback during drop operations.
92

93
```java { .api }
94
/**
95
 * Callback interface for customizing drop target visual feedback
96
 * Allows painting custom indicators when items are dragged over drop targets
97
 */
98
public interface DropTargetPainter {
99
    /**
100
     * Paint custom drop target feedback
101
     * @param e Drop target event providing context
102
     * @param action Current drop action being performed
103
     * @param location Current cursor location relative to component
104
     */
105
    void paintDropTarget(DropTargetEvent e, int action, Point location);
106
}
107
```
108

109
### Ghosted Drag Image
110

111
Utility class that provides translucent drag images when native platform support is unavailable, using window transparency effects from WindowUtils.
112

113
```java { .api }
114
/**
115
 * Provides ghosted drag images when native drag image support is unavailable
116
 * Uses WindowUtils for transparency effects
117
 */
118
public class GhostedDragImage {
119
    /**
120
     * Create ghosted drag image with icon
121
     * @param dragSource Source component for the drag operation
122
     * @param icon Icon to use for the drag image
123
     * @param initialScreenLoc Initial screen location for the image
124
     * @param cursorOffset Offset from cursor to image corner
125
     */
126
    public GhostedDragImage(Component dragSource, Icon icon, Point initialScreenLoc, Point cursorOffset);
127
    
128
    /**
129
     * Set transparency level of the ghosted image
130
     * @param alpha Alpha transparency (0.0f = transparent, 1.0f = opaque)
131
     */
132
    public void setAlpha(float alpha);
133
    
134
    /**
135
     * Clean up resources and dispose of the ghosted image
136
     */
137
    public void dispose();
138
    
139
    /**
140
     * Move the ghosted image to new screen location
141
     * @param screenLocation New screen coordinates for the image
142
     */
143
    public void move(Point screenLocation);
144
    
145
    /**
146
     * Animate the ghosted image returning to its original position
147
     */
148
    public void returnToOrigin();
149
}
150
```
151

152
## Usage Examples
153

154
### Basic Drag Handler Implementation
155

156
```java
157
import com.sun.jna.platform.dnd.DragHandler;
158
import java.awt.dnd.DnDConstants;
159
import java.awt.dnd.DragGestureEvent;
160

161
// Create custom drag handler for a JLabel with an image
162
DragHandler dragHandler = new DragHandler(imageLabel, DnDConstants.ACTION_COPY) {
163
    @Override
164
    public void dragGestureRecognized(DragGestureEvent e) {
165
        // Start drag operation with transferable data
166
        ImageIcon icon = (ImageIcon) imageLabel.getIcon();
167
        Transferable transferable = new ImageTransferable(icon.getImage());
168
        e.startDrag(null, transferable, this);
169
    }
170
    
171
    @Override
172
    public void dragEnter(DragSourceDragEvent e) {
173
        // Handle drag enter
174
    }
175
    
176
    // Implement other DragSourceListener methods...
177
};
178
```
179

180
### Basic Drop Handler Implementation
181

182
```java
183
import com.sun.jna.platform.dnd.DropHandler;
184
import com.sun.jna.platform.dnd.DropTargetPainter;
185
import java.awt.dnd.DnDConstants;
186
import java.awt.dnd.DropTargetDropEvent;
187

188
// Create drop handler with custom visual feedback
189
DropHandler dropHandler = new DropHandler(
190
    targetPanel, 
191
    DnDConstants.ACTION_COPY, 
192
    new DataFlavor[]{DataFlavor.imageFlavor},
193
    new DropTargetPainter() {
194
        @Override
195
        public void paintDropTarget(DropTargetEvent e, int action, Point location) {
196
            // Paint custom drop indicator
197
            Graphics2D g2 = (Graphics2D) e.getDropTargetContext().getComponent().getGraphics();
198
            g2.setColor(Color.BLUE);
199
            g2.drawRect(location.x - 10, location.y - 10, 20, 20);
200
        }
201
    }
202
) {
203
    @Override
204
    public void drop(DropTargetDropEvent e) {
205
        try {
206
            // Accept the drop
207
            e.acceptDrop(DnDConstants.ACTION_COPY);
208
            
209
            // Get the transferred data
210
            Image image = (Image) e.getTransferable().getTransferData(DataFlavor.imageFlavor);
211
            
212
            // Process the dropped image
213
            processDroppedImage(image);
214
            
215
            // Mark drop as complete
216
            e.dropComplete(true);
217
        } catch (Exception ex) {
218
            e.dropComplete(false);
219
        }
220
    }
221
};
222
```
223

224
### Using Ghosted Drag Images
225

226
```java
227
import com.sun.jna.platform.dnd.GhostedDragImage;
228

229
// Create ghosted image during drag operation
230
Point initialLocation = e.getDragOrigin();
231
SwingUtilities.convertPointToScreen(initialLocation, dragSource);
232

233
GhostedDragImage ghostImage = new GhostedDragImage(
234
    dragSource,
235
    dragIcon,
236
    initialLocation,
237
    new Point(16, 16) // Offset from cursor
238
);
239

240
// Set custom transparency
241
ghostImage.setAlpha(0.7f);
242

243
// Move image during drag (typically in dragOver event)
244
Point newLocation = getCurrentScreenLocation();
245
ghostImage.move(newLocation);
246

247
// Clean up when drag ends
248
ghostImage.dispose();
249
```
250

251
## Platform Notes
252

253
- **Cross-Platform**: Drag and drop enhancements work on all platforms supported by JNA
254
- **Native Fallback**: When native drag image support is available, the system may use it instead of ghosted images  
255
- **WindowUtils Integration**: Ghosted images depend on WindowUtils transparency support
256
- **Demo Available**: See `/contrib/dnddemo/` in the JNA source for a complete working example
257

258
## Dependencies
259

260
The drag and drop support requires:
261
- Core JNA library for native platform access
262
- WindowUtils for transparency and masking effects
263
- Standard Java AWT/Swing drag and drop infrastructure
264
- Component heavyweight peers for proper integration