Module java.desktop
Package java.awt.dnd

# Class DropTarget

java.lang.Object
java.awt.dnd.DropTarget

All Implemented Interfaces:
  `DropTargetListener`, `Serializable`, `EventListener`

public class DropTarget extends Object implements DropTargetListener, Serializable
The `DropTarget` is associated with a `Component` when that `Component` wishes to accept drops during Drag and Drop operations.

Each `DropTarget` is associated with a `FlavorMap`. The default `FlavorMap` hereafter designates the `FlavorMap` returned by `SystemFlavorMap.getDefaultFlavorMap()`.

Since:
  1.2
See Also:
  - Serialized Form

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`protected static class`
`DropTarget.DropTargetAutoScroller`
this protected nested class implements autoscrolling

## Constructor Summary

Constructors
Constructor
Description
`DropTarget()`
Creates a `DropTarget`.
`DropTarget(Component c, int ops, DropTargetListener dtl)`
Creates a `DropTarget` given the `Component` to associate itself with, an `int` representing the default acceptable action(s) to support, and a `DropTargetListener` to handle event processing.
`DropTarget(Component c, int ops, DropTargetListener dtl, boolean act)`
Creates a `DropTarget` given the `Component` to associate itself with, an `int` representing the default acceptable action(s) to support, a `DropTargetListener` to handle event processing, and a `boolean` indicating if the `DropTarget` is currently accepting drops.
`DropTarget(Component c, int ops, DropTargetListener dtl, boolean act, FlavorMap fm)`
Creates a new DropTarget given the `Component` to associate itself with, an `int` representing the default acceptable action(s) to support, a `DropTargetListener` to handle event processing, a `boolean` indicating if the `DropTarget` is currently accepting drops, and a `FlavorMap` to use (or null for the default `FlavorMap`).
`DropTarget(Component c, DropTargetListener dtl)`
Creates a `DropTarget` given the `Component` to associate itself with, and the `DropTargetListener` to handle event processing.

## Method Summary

Modifier and Type
Method
Description
`void`
`addDropTargetListener(DropTargetListener dtl)`
Adds a new `DropTargetListener` (UNICAST SOURCE).
`void`
`addNotify()`
Notify the DropTarget that it has been associated with a Component This method is usually called from java.awt.Component.addNotify() of the Component associated with this DropTarget to notify the DropTarget that a ComponentPeer has been associated with that Component.
`protected void`
`clearAutoscroll()`
clear autoscrolling
`protected DropTarget.DropTargetAutoScroller`
`createDropTargetAutoScroller(Component c, Point p)`
create an embedded autoscroller
`protected DropTargetContext`
`createDropTargetContext()`
Creates the DropTargetContext associated with this DropTarget.
`void`
`dragEnter(DropTargetDragEvent dtde)`
Calls `dragEnter` on the registered `DropTargetListener` and passes it the specified `DropTargetDragEvent`.
`void`
`dragExit(DropTargetEvent dte)`
Calls `dragExit` on the registered `DropTargetListener` and passes it the specified `DropTargetEvent`.
`void`
`dragOver(DropTargetDragEvent dtde)`
Calls `dragOver` on the registered `DropTargetListener` and passes it the specified `DropTargetDragEvent`.
`void`
`drop(DropTargetDropEvent dtde)`
Calls `drop` on the registered `DropTargetListener` and passes it the specified `DropTargetDropEvent` if this `DropTarget` is active.
`void`
`dropActionChanged(DropTargetDragEvent dtde)`
Calls `dropActionChanged` on the registered `DropTargetListener` and passes it the specified `DropTargetDragEvent`.
`Component`
`getComponent()`
Gets the `Component` associated with this `DropTarget`.
`int`
`getDefaultActions()`
Gets an `int` representing the current action(s) supported by this `DropTarget`.
`DropTargetContext`
`getDropTargetContext()`
Gets the `DropTargetContext` associated with this `DropTarget`.
`FlavorMap`
`getFlavorMap()`
Gets the `FlavorMap` associated with this `DropTarget`.
`protected void`
`initializeAutoscrolling(Point p)`
initialize autoscrolling
`boolean`
`isActive()`
Reports whether or not this `DropTarget` is currently active (ready to accept drops).
`void`
`removeDropTargetListener(DropTargetListener dtl)`
Removes the current `DropTargetListener` (UNICAST SOURCE).
`void`
`removeNotify()`
Notify the DropTarget that it has been disassociated from a Component This method is usually called from java.awt.Component.removeNotify() of the Component associated with this DropTarget to notify the DropTarget that a ComponentPeer has been disassociated with that Component.
`void`
`setActive(boolean isActive)`
Sets the DropTarget active if `true`, inactive if `false`.
`void`
`setComponent(Component c)`
Note: this interface is required to permit the safe association of a DropTarget with a Component in one of two ways, either: `component.setDropTarget(droptarget);` or `droptarget.setComponent(component);`
`void`
`setDefaultActions(int ops)`
Sets the default acceptable actions for this `DropTarget`
`void`
`setFlavorMap(FlavorMap fm)`
Sets the `FlavorMap` associated with this `DropTarget`.
`protected void`
`updateAutoscroll(Point dragCursorLocn)`
update autoscrolling with current cursor location

### Methods declared in class java.lang.Object

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

## Constructor Details

### DropTarget

public DropTarget(Component c, int ops, DropTargetListener dtl, boolean act, FlavorMap fm) throws HeadlessException
Creates a new DropTarget given the `Component` to associate itself with, an `int` representing the default acceptable action(s) to support, a `DropTargetListener` to handle event processing, a `boolean` indicating if the `DropTarget` is currently accepting drops, and a `FlavorMap` to use (or null for the default `FlavorMap`).

The Component will receive drops only if it is enabled.

Parameters:
  `c` - The `Component` with which this `DropTarget` is associated
  `ops` - The default acceptable actions for this `DropTarget`
  `dtl` - The `DropTargetListener` for this `DropTarget`
  `act` - Is the `DropTarget` accepting drops.
  `fm` - The `FlavorMap` to use, or null for the default `FlavorMap`
Throws:
  `HeadlessException` - if GraphicsEnvironment.isHeadless() returns true
See Also:
  - `GraphicsEnvironment.isHeadless()`

### DropTarget

public DropTarget(Component c, int ops, DropTargetListener dtl, boolean act) throws HeadlessException
Creates a `DropTarget` given the `Component` to associate itself with, an `int` representing the default acceptable action(s) to support, a `DropTargetListener` to handle event processing, and a `boolean` indicating if the `DropTarget` is currently accepting drops.

The Component will receive drops only if it is enabled.

Parameters:
  `c` - The `Component` with which this `DropTarget` is associated
  `ops` - The default acceptable actions for this `DropTarget`
  `dtl` - The `DropTargetListener` for this `DropTarget`
  `act` - Is the `DropTarget` accepting drops.
Throws:
  `HeadlessException` - if GraphicsEnvironment.isHeadless() returns true
See Also:
  - `GraphicsEnvironment.isHeadless()`

### DropTarget

public DropTarget() throws HeadlessException
Creates a `DropTarget`.

Throws:
  `HeadlessException` - if GraphicsEnvironment.isHeadless() returns true
See Also:
  - `GraphicsEnvironment.isHeadless()`

### DropTarget

public DropTarget(Component c, DropTargetListener dtl) throws HeadlessException
Creates a `DropTarget` given the `Component` to associate itself with, and the `DropTargetListener` to handle event processing.

The Component will receive drops only if it is enabled.

Parameters:
  `c` - The `Component` with which this `DropTarget` is associated
  `dtl` - The `DropTargetListener` for this `DropTarget`
Throws:
  `HeadlessException` - if GraphicsEnvironment.isHeadless() returns true
See Also:
  - `GraphicsEnvironment.isHeadless()`

### DropTarget

public DropTarget(Component c, int ops, DropTargetListener dtl) throws HeadlessException
Creates a `DropTarget` given the `Component` to associate itself with, an `int` representing the default acceptable action(s) to support, and a `DropTargetListener` to handle event processing.

The Component will receive drops only if it is enabled.

Parameters:
  `c` - The `Component` with which this `DropTarget` is associated
  `ops` - The default acceptable actions for this `DropTarget`
  `dtl` - The `DropTargetListener` for this `DropTarget`
Throws:
  `HeadlessException` - if GraphicsEnvironment.isHeadless() returns true
See Also:
  - `GraphicsEnvironment.isHeadless()`

## Method Details

### setComponent

public void setComponent(Component c)
Note: this interface is required to permit the safe association of a DropTarget with a Component in one of two ways, either: `component.setDropTarget(droptarget);` or `droptarget.setComponent(component);`

The Component will receive drops only if it is enabled.

Parameters:
  `c` - The new `Component` this `DropTarget` is to be associated with.

### getComponent

public Component getComponent()
Gets the `Component` associated with this `DropTarget`.

Returns:
  the current `Component`

### setDefaultActions

public void setDefaultActions(int ops)
Sets the default acceptable actions for this `DropTarget`

Parameters:
  `ops` - the default actions
See Also:
  - `DnDConstants`

### getDefaultActions

public int getDefaultActions()
Gets an `int` representing the current action(s) supported by this `DropTarget`.

Returns:
  the current default actions

### setActive

public void setActive(boolean isActive)
Sets the DropTarget active if `true`, inactive if `false`.

Parameters:
  `isActive` - sets the `DropTarget` (in)active.

### isActive

public boolean isActive()
Reports whether or not this `DropTarget` is currently active (ready to accept drops).

Returns:
  `true` if active, `false` if not

### addDropTargetListener

public void addDropTargetListener(DropTargetListener dtl) throws TooManyListenersException
Adds a new `DropTargetListener` (UNICAST SOURCE).

Parameters:
  `dtl` - The new `DropTargetListener`
Throws:
  `TooManyListenersException` - if a `DropTargetListener` is already added to this `DropTarget`.

### removeDropTargetListener

public void removeDropTargetListener(DropTargetListener dtl)
Removes the current `DropTargetListener` (UNICAST SOURCE).

Parameters:
  `dtl` - the DropTargetListener to deregister.

### dragEnter

public void dragEnter(DropTargetDragEvent dtde)
Calls `dragEnter` on the registered `DropTargetListener` and passes it the specified `DropTargetDragEvent`. Has no effect if this `DropTarget` is not active.

Specified by:
  `dragEnter` in interface `DropTargetListener`
Parameters:
  `dtde` - the `DropTargetDragEvent`
Throws:
  `NullPointerException` - if this `DropTarget` is active and `dtde` is `null`
See Also:
  - `isActive()`

### dragOver

public void dragOver(DropTargetDragEvent dtde)
Calls `dragOver` on the registered `DropTargetListener` and passes it the specified `DropTargetDragEvent`. Has no effect if this `DropTarget` is not active.

Specified by:
  `dragOver` in interface `DropTargetListener`
Parameters:
  `dtde` - the `DropTargetDragEvent`
Throws:
  `NullPointerException` - if this `DropTarget` is active and `dtde` is `null`
See Also:
  - `isActive()`

### dropActionChanged

public void dropActionChanged(DropTargetDragEvent dtde)
Calls `dropActionChanged` on the registered `DropTargetListener` and passes it the specified `DropTargetDragEvent`. Has no effect if this `DropTarget` is not active.

Specified by:
  `dropActionChanged` in interface `DropTargetListener`
Parameters:
  `dtde` - the `DropTargetDragEvent`
Throws:
  `NullPointerException` - if this `DropTarget` is active and `dtde` is `null`
See Also:
  - `isActive()`

### dragExit

public void dragExit(DropTargetEvent dte)
Calls `dragExit` on the registered `DropTargetListener` and passes it the specified `DropTargetEvent`. Has no effect if this `DropTarget` is not active.

This method itself does not throw any exception for null parameter but for exceptions thrown by the respective method of the listener.

Specified by:
  `dragExit` in interface `DropTargetListener`
Parameters:
  `dte` - the `DropTargetEvent`
See Also:
  - `isActive()`

### drop

public void drop(DropTargetDropEvent dtde)
Calls `drop` on the registered `DropTargetListener` and passes it the specified `DropTargetDropEvent` if this `DropTarget` is active.

Specified by:
  `drop` in interface `DropTargetListener`
Parameters:
  `dtde` - the `DropTargetDropEvent`
Throws:
  `NullPointerException` - if `dtde` is null and at least one of the following is true: this `DropTarget` is not active, or there is no a `DropTargetListener` registered.
See Also:
  - `isActive()`

### getFlavorMap

public FlavorMap getFlavorMap()
Gets the `FlavorMap` associated with this `DropTarget`. If no `FlavorMap` has been set for this `DropTarget`, it is associated with the default `FlavorMap`.

Returns:
  the FlavorMap for this DropTarget

### setFlavorMap

public void setFlavorMap(FlavorMap fm)
Sets the `FlavorMap` associated with this `DropTarget`.

Parameters:
  `fm` - the new `FlavorMap`, or null to associate the default FlavorMap with this DropTarget.

### addNotify

public void addNotify()
Notify the DropTarget that it has been associated with a Component This method is usually called from java.awt.Component.addNotify() of the Component associated with this DropTarget to notify the DropTarget that a ComponentPeer has been associated with that Component. Calling this method, other than to notify this DropTarget of the association of the ComponentPeer with the Component may result in a malfunction of the DnD system.

### removeNotify

public void removeNotify()
Notify the DropTarget that it has been disassociated from a Component This method is usually called from java.awt.Component.removeNotify() of the Component associated with this DropTarget to notify the DropTarget that a ComponentPeer has been disassociated with that Component. Calling this method, other than to notify this DropTarget of the disassociation of the ComponentPeer from the Component may result in a malfunction of the DnD system.

### getDropTargetContext

public DropTargetContext getDropTargetContext()
Gets the `DropTargetContext` associated with this `DropTarget`.

Returns:
  the `DropTargetContext` associated with this `DropTarget`.

### createDropTargetContext

protected DropTargetContext createDropTargetContext()
Creates the DropTargetContext associated with this DropTarget. Subclasses may override this method to instantiate their own DropTargetContext subclass. This call is typically *only* called by the platform's DropTargetContextPeer as a drag operation encounters this DropTarget. Accessing the Context while no Drag is current has undefined results.

Returns:
  the DropTargetContext associated with this DropTarget

### createDropTargetAutoScroller

protected DropTarget.DropTargetAutoScroller createDropTargetAutoScroller(Component c, Point p)
create an embedded autoscroller

Parameters:
  `c` - the `Component`
  `p` - the `Point`
Returns:
  an embedded autoscroller

### initializeAutoscrolling

protected void initializeAutoscrolling(Point p)
initialize autoscrolling

Parameters:
  `p` - the `Point`

### updateAutoscroll

protected void updateAutoscroll(Point dragCursorLocn)
update autoscrolling with current cursor location

Parameters:
  `dragCursorLocn` - the `Point`

### clearAutoscroll

protected void clearAutoscroll()
clear autoscrolling