Standard Widget Toolkit for GTK 3.125.0 · org.eclipse.swt.dnd.DropTarget

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

Important Note

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

Field Summary

Modifier and Type	Field and Description
pack-priv Control	control
pack-priv Listener	controlListener
pack-priv static final String	DEFAULT_DROP_TARGET_EFFECT
pack-priv static Callback	Drag_Data_Received
pack-priv int	drag_data_received_handler
pack-priv static Callback	Drag_Drop
pack-priv int	drag_drop_handler
pack-priv static Callback	Drag_Leave
pack-priv int	drag_leave_handler
pack-priv static Callback	Drag_Motion
pack-priv int	drag_motion_handler
pack-priv static final int	DRAGOVER_HYSTERESIS
pack-priv DNDEvent	dragOverEvent
pack-priv Runnable	dragOverHeartbeat
pack-priv long	dragOverStart
pack-priv long	dropController
pack-priv DropTargetEffect	dropEffect
pack-priv static final String	IS_ACTIVE Hides org.eclipse.swt.widgets.Widget.IS_ACTIVE.
pack-priv int	keyOperation
pack-priv TransferData	selectedDataType
pack-priv int	selectedOperation
pack-priv Transfer[]	transferAgents

Inherited from org.eclipse.swt.widgets.Widget:: handle

Constructor Summary

Access	Constructor and Description
public	DropTarget(Control the `Control` over which the user positions the cursor to drop the data control, int 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 style) Creates a new `DropTarget` to allow data to be dropped on the specified `Control`.

Method Summary

Modifier and Type	Method and Description
public void	addDropListener(DropTargetListener the listener which should be notified 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.
pack-priv static int	checkStyle(int style)
protected void	checkSubclass() Overrides org.eclipse.swt.widgets.Widget.checkSubclass. Checks that this class can be subclassed.
pack-priv static long	Drag_Data_Received(long widget, long context, long x, long y, long data, long info, long time)
pack-priv void	drag_data_received(long widget, long context, int x, int y, long selection_data, int info, int time)
pack-priv static long	Drag_Drop(long widget, long context, long x, long y, long time)
pack-priv boolean	drag_drop(long widget, long context, int x, int y, int time)
pack-priv static long	Drag_Leave(long widget, long context, long time)
pack-priv void	drag_leave(long widget, long context, int time)
pack-priv static long	Drag_Motion(long widget, long context, long x, long y, long time)
pack-priv boolean	drag_motion(long widget, long context, int x, int y, int time)
pack-priv static DropTarget	FindDropTarget(long handle)
public Control	Returns: the Control which is registered for this DropTarget getControl() Returns the Control which is registered for this DropTarget.
public DropTargetListener[]	Returns: the listeners who will be notified when a drag and drop operation is in progress 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.
public DropTargetEffect	Returns: the drop effect that is registered for this DropTarget getDropTargetEffect() Returns the drop effect for this DropTarget.
pack-priv int	getOperationFromKeyState()
public Transfer[]	Returns: a list of the data types that can be transferred to this DropTarget getTransfer() Returns a list of the data types that can be transferred to this DropTarget.
pack-priv void	onDispose()
pack-priv int	opToOsOp(int operation)
pack-priv int	osOpToOp(int osOperation)
public void	removeDropListener(DropTargetListener the listener which should no longer be notified listener) Removes the listener from the collection of listeners who will be notified when a drag and drop operation is in progress.
public void	setDropTargetEffect(DropTargetEffect the drop effect that is registered for this DropTarget effect) Specifies the drop effect for this DropTarget.
pack-priv boolean	setEventData(long context, int x, int y, int time, DNDEvent event)
public void	setTransfer(Transfer... a list of Transfer objects which define the types of data that can be dropped on this target transferAgents) Specifies the data types that can be transferred to this DropTarget.
pack-priv void	updateDragOverHover(long delay, DNDEvent event)

Field Detail

control	back to summary
pack-priv Control control

controlListener	back to summary
pack-priv Listener controlListener

DEFAULT_DROP_TARGET_EFFECT	back to summary
pack-priv static final String DEFAULT_DROP_TARGET_EFFECT

Drag_Data_Received	back to summary
pack-priv static Callback Drag_Data_Received

drag_data_received_handler	back to summary
pack-priv int drag_data_received_handler

Drag_Drop	back to summary
pack-priv static Callback Drag_Drop

drag_drop_handler	back to summary
pack-priv int drag_drop_handler

Drag_Leave	back to summary
pack-priv static Callback Drag_Leave

drag_leave_handler	back to summary
pack-priv int drag_leave_handler

Drag_Motion	back to summary
pack-priv static Callback Drag_Motion

drag_motion_handler	back to summary
pack-priv int drag_motion_handler

DRAGOVER_HYSTERESIS	back to summary
pack-priv static final int DRAGOVER_HYSTERESIS

dragOverEvent	back to summary
pack-priv DNDEvent dragOverEvent

dragOverHeartbeat	back to summary
pack-priv Runnable dragOverHeartbeat

dragOverStart	back to summary
pack-priv long dragOverStart

dropController	back to summary
pack-priv long dropController

dropEffect	back to summary
pack-priv DropTargetEffect dropEffect

IS_ACTIVE	back to summary
pack-priv static final String IS_ACTIVE Hides org.eclipse.swt.widgets.Widget.IS_ACTIVE.

keyOperation	back to summary
pack-priv int keyOperation

selectedDataType	back to summary
pack-priv TransferData selectedDataType

selectedOperation	back to summary
pack-priv int selectedOperation

transferAgents	back to summary
pack-priv Transfer[] transferAgents

Constructor Detail

DropTarget back to summary

DropTarget	back to summary
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:Control the `Control` over which the user positions the cursor to drop the data style:int 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 Exceptions 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`, `DropTarget#checkSubclass`, `DND#DROP_NONE`, `DND#DROP_COPY`, `DND#DROP_MOVE`, `DND#DROP_LINK`

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:Control: the Control over which the user positions the cursor to drop the data
style:int: 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

Exceptions

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.

Method Detail

addDropListener back to summary

addDropListener	back to summary
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:DropTargetListener the listener which should be notified Exceptions 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`, `DropTargetEvent`

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:DropTargetListener: the listener which should be notified

Exceptions

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

checkStyle	back to summary
pack-priv static int checkStyle(int style)

checkSubclass back to summary

checkSubclass	back to summary
protected void checkSubclass() Overrides org.eclipse.swt.widgets.Widget.checkSubclass. Doc from org.eclipse.swt.widgets.Widget.checkSubclass. 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 Note 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. Annotations @Override

protected void checkSubclass()

Overrides org.eclipse.swt.widgets.Widget.checkSubclass.

Doc from org.eclipse.swt.widgets.Widget.checkSubclass.

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 Note

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.

Annotations

@Override

Drag_Data_Received	back to summary
pack-priv static long Drag_Data_Received(long widget, long context, long x, long y, long data, long info, long time)

drag_data_received	back to summary
pack-priv void drag_data_received(long widget, long context, int x, int y, long selection_data, int info, int time)

Drag_Drop	back to summary
pack-priv static long Drag_Drop(long widget, long context, long x, long y, long time)

drag_drop	back to summary
pack-priv boolean drag_drop(long widget, long context, int x, int y, int time)

Drag_Leave	back to summary
pack-priv static long Drag_Leave(long widget, long context, long time)

drag_leave	back to summary
pack-priv void drag_leave(long widget, long context, int time)

Drag_Motion	back to summary
pack-priv static long Drag_Motion(long widget, long context, long x, long y, long time)

drag_motion	back to summary
pack-priv boolean drag_motion(long widget, long context, int x, int y, int time)

FindDropTarget	back to summary
pack-priv static DropTarget FindDropTarget(long handle)

getControl	back to summary
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:Control the Control which is registered for this DropTarget

getControl

back to summary

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:Control: the Control which is registered for this DropTarget

getDropListeners back to summary

getDropListeners	back to summary
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:DropTargetListener[] the listeners who will be notified when a drag and drop operation is in progress Exceptions SWTException: ERROR_WIDGET_DISPOSED - if the receiver has been disposed ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver Since 3.4 See Also `DropTargetListener`, `addDropListener`, `removeDropListener`, `DropTargetEvent`

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:DropTargetListener[]

the listeners who will be notified when a drag and drop operation is in progress

Exceptions

SWTException:

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

Since

3.4

getDropTargetEffect	back to summary
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:DropTargetEffect the drop effect that is registered for this DropTarget Since 3.3

getDropTargetEffect

back to summary

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:DropTargetEffect: the drop effect that is registered for this DropTarget
Since: 3.3

getOperationFromKeyState	back to summary
pack-priv int getOperationFromKeyState()

getTransfer	back to summary
public Transfer[] getTransfer() Returns a list of the data types that can be transferred to this DropTarget. Returns:Transfer[] a list of the data types that can be transferred to this DropTarget

getTransfer

back to summary

public Transfer[] getTransfer()

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

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

onDispose	back to summary
pack-priv void onDispose()

opToOsOp	back to summary
pack-priv int opToOsOp(int operation)

osOpToOp	back to summary
pack-priv int osOpToOp(int osOperation)

removeDropListener back to summary

removeDropListener	back to summary
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:DropTargetListener the listener which should no longer be notified Exceptions 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`, `getDropListeners`

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:DropTargetListener: the listener which should no longer be notified

Exceptions

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

setDropTargetEffect	back to summary
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:DropTargetEffect the drop effect that is registered for this DropTarget Since 3.3

setDropTargetEffect

back to summary

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:DropTargetEffect: the drop effect that is registered for this DropTarget

Since

3.3

setEventData	back to summary
pack-priv boolean setEventData(long context, int x, int y, int time, DNDEvent event)

setTransfer	back to summary
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:Transfer[] a list of Transfer objects which define the types of data that can be dropped on this target Exceptions IllegalArgumentException: ERROR_NULL_ARGUMENT - if transferAgents is null

setTransfer

back to summary

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:Transfer[]: a list of Transfer objects which define the types of data that can be dropped on this target

Exceptions

IllegalArgumentException:

ERROR_NULL_ARGUMENT - if transferAgents is null

updateDragOverHover	back to summary
pack-priv void updateDragOverHover(long delay, DNDEvent event)

public Class DropTarget

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail