org.eclipse.swt.dnd

## Class DropTarget

- java.lang.Object
- - org.eclipse.swt.widgets.Widget
  - - org.eclipse.swt.dnd.DropTarget

All Implemented Interfaces:
  Adaptable

    public class DropTarget
    extends Widget

Class `DropTarget` defines the target object for a drag and drop transfer.

IMPORTANT: This class is not intended to be subclassed.

This class identifies the `Control` over which the user must position the cursor in order to drop the data being transferred. It also specifies what data types can be dropped on this control and what operations can be performed. You may have several DropTragets in an application but there can only be a one to one mapping between a `Control` and a `DropTarget`. The DropTarget can receive data from within the same application or from other applications (such as text dragged from a text editor like Word).

`

            int operations = DND.DROP_MOVE | DND.DROP_COPY | DND.DROP_LINK;
            Transfer[] types = new Transfer[] {TextTransfer.getInstance()};
            DropTarget target = new DropTarget(label, operations);
            target.setTransfer(types);

`

The application is notified of data being dragged over this control and of when a drop occurs by implementing the interface `DropTargetListener` which uses the class `DropTargetEvent`. The application can modify the type of drag being performed on this Control at any stage of the drag by modifying the `event.detail` field or the `event.currentDataType` field. When the data is dropped, it is the responsibility of the application to copy this data for its own purposes. ``

            target.addDropListener (new DropTargetListener() {
                    public void dragEnter(DropTargetEvent event) {};
                    public void dragOver(DropTargetEvent event) {};
                    public void dragLeave(DropTargetEvent event) {};
                    public void dragOperationChanged(DropTargetEvent event) {};
                    public void dropAccept(DropTargetEvent event) {}
                    public void drop(DropTargetEvent event) {
                            // A drop has occurred, copy over the data
                            if (event.data == null) { // no data to copy, indicate failure in event.detail
                                    event.detail = DND.DROP_NONE;
                                    return;
                            }
                            label.setText ((String) event.data); // data copied to label text
                    }
            });

Styles
  DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK
Events
  DND.DragEnter, DND.DragLeave, DND.DragOver, DND.DragOperationChanged, DND.DropAccept, DND.Drop

Since:
  1.3

### Constructor Summary

Constructors
Constructor and Description
`DropTarget(Control control, int style)` Creates a new `DropTarget` to allow data to be dropped on the specified `Control`.

### Method Summary

Methods
`void` `addDropListener(DropTargetListener listener)` Adds the listener to the collection of listeners who will be notified when a drag and drop operation is in progress, by sending it one of the messages defined in the `DropTargetListener` interface.
`protected void` `checkSubclass()` Checks that this class can be subclassed.
`<T> T` `getAdapter(java.lang.Class<T> adapter)` Implementation of the `Adaptable` interface.
`Control` `getControl()` Returns the Control which is registered for this DropTarget.
`DropTargetListener[]` `getDropListeners()` Returns an array of listeners who will be notified when a drag and drop operation is in progress, by sending it one of the messages defined in the `DropTargetListener` interface.
`DropTargetEffect` `getDropTargetEffect()` Returns the drop effect for this DropTarget.
`Transfer[]` `getTransfer()` Returns a list of the data types that can be transferred to this DropTarget.
`void` `removeDropListener(DropTargetListener listener)` Removes the listener from the collection of listeners who will be notified when a drag and drop operation is in progress.
`void` `setDropTargetEffect(DropTargetEffect effect)` Specifies the drop effect for this DropTarget.
`void` `setTransfer(Transfer[] transferAgents)` Specifies the data types that can be transferred to this DropTarget.

### Methods inherited from class org.eclipse.swt.widgets.Widget

`addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getListeners, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, reskin, setData, setData, toString`

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### DropTarget

    public DropTarget(Control control,
              int style)

Creates a new `DropTarget` to allow data to be dropped on the specified `Control`. Creating an instance of a DropTarget may cause system resources to be allocated depending on the platform. It is therefore mandatory that the DropTarget instance be disposed when no longer required.

Parameters:
  `control` - the `Control` over which the user positions the cursor to drop the data
  `style` - the bitwise OR'ing of allowed operations; this may be a combination of any of DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK
Throws:
  `SWTException` -
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
  - ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
  `SWTError` -
  - ERROR_CANNOT_INIT_DROP - unable to initiate drop target; this will occur if more than one drop target is created for a control or if the operating system will not allow the creation of the drop target

  NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a recoverable error, but can not be changed due to backward compatibility.

See Also:
  `Widget.dispose()`, `checkSubclass()`, `DND.DROP_NONE`, `DND.DROP_COPY`, `DND.DROP_MOVE`, `DND.DROP_LINK`

### Method Detail

#### addDropListener

    public void addDropListener(DropTargetListener listener)

Adds the listener to the collection of listeners who will be notified when a drag and drop operation is in progress, by sending it one of the messages defined in the `DropTargetListener` interface.

- `dragEnter` is called when the cursor has entered the drop target boundaries
- `dragLeave` is called when the cursor has left the drop target boundaries and just before the drop occurs or is cancelled.
- `dragOperationChanged` is called when the operation being performed has changed (usually due to the user changing the selected modifier key(s) while dragging)
- `dragOver` is called when the cursor is moving over the drop target
- `dropAccept` is called just before the drop is performed. The drop target is given the chance to change the nature of the drop or veto the drop by setting the `event.detail` field
- `drop` is called when the data is being dropped

Parameters:
  `listener` - the listener which should be notified
Throws:
  `java.lang.IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the listener is null
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
See Also:
  `DropTargetListener`, `getDropListeners()`, `removeDropListener(org.eclipse.swt.dnd.DropTargetListener)`, `DropTargetEvent`

#### checkSubclass

    protected void checkSubclass()

Description copied from class: `Widget`
Checks that this class can be subclassed.

The SWT class library is intended to be subclassed only at specific, controlled points (most notably, `Composite` and `Canvas` when implementing new widgets). This method enforces this rule unless it is overridden.

IMPORTANT: By providing an implementation of this method that allows a subclass of a class which does not normally allow subclassing to be created, the implementer agrees to be fully responsible for the fact that any such subclass will likely fail between SWT releases and will be strongly platform specific. No support is provided for user-written classes which are implemented in this fashion.

The ability to subclass outside of the allowed SWT classes is intended purely to enable those not on the SWT development team to implement patches in order to get around specific limitations in advance of when those limitations can be addressed by the team. Subclassing should not be attempted without an intimate and detailed understanding of the hierarchy.

Overrides:
  `checkSubclass` in class `Widget`

#### getControl

    public Control getControl()

Returns the Control which is registered for this DropTarget. This is the control over which the user positions the cursor to drop the data.

Returns:
  the Control which is registered for this DropTarget

#### getDropListeners

    public DropTargetListener[] getDropListeners()

Returns an array of listeners who will be notified when a drag and drop operation is in progress, by sending it one of the messages defined in the `DropTargetListener` interface.

Returns:
  the listeners who will be notified when a drag and drop operation is in progress
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
See Also:
  `DropTargetListener`, `addDropListener(org.eclipse.swt.dnd.DropTargetListener)`, `removeDropListener(org.eclipse.swt.dnd.DropTargetListener)`, `DropTargetEvent`

#### getDropTargetEffect

    public DropTargetEffect getDropTargetEffect()

Returns the drop effect for this DropTarget. This drop effect will be used during a drag and drop to display the drag under effect on the target widget.

Returns:
  the drop effect that is registered for this DropTarget

#### getTransfer

    public Transfer[] getTransfer()

Returns a list of the data types that can be transferred to this DropTarget.

Returns:
  a list of the data types that can be transferred to this DropTarget

#### removeDropListener

    public void removeDropListener(DropTargetListener listener)

Removes the listener from the collection of listeners who will be notified when a drag and drop operation is in progress.

Parameters:
  `listener` - the listener which should no longer be notified
Throws:
  `java.lang.IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the listener is null
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
See Also:
  `DropTargetListener`, `addDropListener(org.eclipse.swt.dnd.DropTargetListener)`, `getDropListeners()`

#### setDropTargetEffect

    public void setDropTargetEffect(DropTargetEffect effect)

Specifies the drop effect for this DropTarget. This drop effect will be used during a drag and drop to display the drag under effect on the target widget.

Parameters:
  `effect` - the drop effect that is registered for this DropTarget

#### setTransfer

    public void setTransfer(Transfer[] transferAgents)

Specifies the data types that can be transferred to this DropTarget. If data is being dragged that does not match one of these types, the drop target will be notified of the drag and drop operation but the currentDataType will be null and the operation will be DND.NONE.

Parameters:
  `transferAgents` - a list of Transfer objects which define the types of data that can be dropped on this target
Throws:
  `java.lang.IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if transferAgents is null

#### getAdapter

    public <T> T getAdapter(java.lang.Class<T> adapter)

Description copied from class: `Widget`
Implementation of the `Adaptable` interface.

IMPORTANT: This method is not part of the RWT public API. It is marked public only so that it can be shared within the packages provided by RWT. It should never be accessed from application code.

Specified by:
  `getAdapter` in interface `Adaptable`
Overrides:
  `getAdapter` in class `Widget`
Parameters:
  `adapter` - the lookup class
Returns:
  an object that can be cast to the given class or `null` if there is no adapter associated with the given class.

Copyright (c) EclipseSource and others 2002, 2018. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0