/******************************************************************************* * Copyright (c) 2000, 2011 IBM Corporation and others. * * This program and the accompanying materials * are made available under the terms of the Eclipse Public License 2.0 * which accompanies this distribution, and is available at * https://www.eclipse.org/legal/epl-2.0/ * * SPDX-License-Identifier: EPL-2.0 * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package org.eclipse.swt.dnd; import org.eclipse.swt.internal.*; /** * The DropTargetListener class provides event notification to the application * for DropTarget events. * *

As the user moves the cursor into, over and out of a Control that has been designated * as a DropTarget, events indicate what operation can be performed and what data can be * transferred if a drop where to occur at that point. * The application can respond to these events and change the type of data that will * be dropped by modifying event.currentDataType, or change the operation that will be performed * by modifying the event.detail field or stop any drop from happening on the current target * by setting the event.detail field to DND_DROP_NONE.

* *

When the user causes a drop to happen by releasing the mouse over a valid drop target, * the application has one last chance to change the data type of the drop through the * DropAccept event. If the drop is still allowed, the DropAccept event is immediately * followed by the Drop event. In the Drop event, the application can still change the * operation that is performed but the data type is fixed.

* * @see DropTargetEvent * */ public interface DropTargetListener extends SWTEventListener { /** * The cursor has entered the drop target boundaries. * *

The following fields in the DropTargetEvent apply:

* * *

The operations value is determined by the modifier keys pressed by the user. * If no keys are pressed the event.detail field is set to DND.DROP_DEFAULT. * If the application does not set the event.detail to something other * than DND.DROP_DEFAULT the operation will be set to the platform defined standard * default.

* *

The currentDataType is determined by the first transfer agent specified in * setTransfer() that matches a data type provided by the drag source.

* *

It is possible to get a DragEnter event when the drag source does not provide any matching data. * In this case, the default operation is DND.DROP_NONE and the currentDataType is null.

* *

The application can change the operation that will be performed by modifying the * detail field but the choice must be one of the values in the operations * field or DND.DROP_NONE.

* *

The application can also change the type of data being requested by * modifying the currentDataTypes field but the value must be one of the values * in the dataTypes list.

* * @param event the information associated with the drag enter event * * @see DropTargetEvent */ public void dragEnter(DropTargetEvent event); /** * The cursor has left the drop target boundaries OR the drop has been cancelled OR the data * is about to be dropped. * *

The following fields in the DropTargetEvent apply:

* * * @param event the information associated with the drag leave event * * @see DropTargetEvent */ public void dragLeave(DropTargetEvent event); /** * The operation being performed has changed (usually due to the user changing the selected modifier key(s) * while dragging). * *

The following fields in the DropTargetEvent apply:

* * *

The operations value is determined by the modifier keys pressed by the user. * If no keys are pressed the event.detail field is set to DND.DROP_DEFAULT. * If the application does not set the event.detail to something other than * DND.DROP_DEFAULT the operation will be set to the platform defined standard default.

* *

The currentDataType value is determined by the value assigned to * currentDataType in previous dragEnter and dragOver calls.

* *

The application can change the operation that will be performed by modifying the * detail field but the choice must be one of the values in the operations * field.

* *

The application can also change the type of data being requested by modifying * the currentDataTypes field but the value must be one of the values in the * dataTypes list.

* * @param event the information associated with the drag operation changed event * * @see DropTargetEvent */ public void dragOperationChanged(DropTargetEvent event); /** * The cursor is moving over the drop target. * *

The following fields in the DropTargetEvent apply:

* * *

The operations value is determined by the value assigned to * currentDataType in previous dragEnter and dragOver calls.

* *

The currentDataType value is determined by the value assigned to * currentDataType in previous dragEnter and dragOver calls.

* *

The application can change the operation that will be performed by modifying the * detail field but the choice must be one of the values in the operations * field.

* *

The application can also change the type of data being requested by modifying the * currentDataTypes field but the value must be one of the values in the * dataTypes list.

* *

NOTE: At this point the data field is null. On some platforms, it is possible * to obtain the data being transferred before the transfer occurs but in most platforms this is * not possible. On those platforms where the data is available, the application can access the * data as follows:

* * 

 * public void dragOver(DropTargetEvent event) {
 *       TextTransfer textTransfer = TextTransfer.getInstance();
 *       String data = (String)textTransfer.nativeToJava(event.currentDataType);
 *       if (data != null) {
 *           System.out.println("Data to be dropped is (Text)"+data);
 *       }
 * };
 *
* * @param event the information associated with the drag over event * * @see DropTargetEvent */ public void dragOver(DropTargetEvent event); /** * The data is being dropped. The data field contains java format of the data being dropped. * To determine the type of the data object, refer to the documentation for the Transfer subclass * specified in event.currentDataType. * *

The following fields in DropTargetEvent apply:

* * *

The application can refuse to perform the drop operation by setting the detail * field to DND.DROP_NONE.

* * @param event the information associated with the drop event * * @see DropTargetEvent */ public void drop(DropTargetEvent event); /** * The drop is about to be performed. * The drop target is given a last chance to change the nature of the drop. * *

The following fields in the DropTargetEvent apply:

* * *

The application can veto the drop by setting the event.detail field to * DND.DROP_NONE.

* *

The application can change the operation that will be performed by modifying the * detail field but the choice must be one of the values in the * operations field.

* *

The application can also change the type of data being requested by modifying the * currentDataTypes field but the value must be one of the values in the * dataTypes list.

* * @param event the information associated with the drop accept event * * @see DropTargetEvent */ public void dropAccept(DropTargetEvent event); }