Module  javafx.graphics
软件包  javafx.scene.input

Class DragEvent

  • All Implemented Interfaces:
    Serializable ， Cloneable 

    public final class DragEvent
extends InputEvent
    拖动事件在拖放手势时替换鼠标事件。 压力释放和拖放手势之间的区别描述于MouseEvent 。

    可以通过调用DRAG_DETECTED事件处理程序中的startDragAndDrop() （节点或场景）来启动拖放手势。 此时将要传输的数据放置到dragBoard 。

    拖动输入/退出事件的行为与鼠标输入/退出事件类似，请参阅MouseEvent概述。

    拖动源：启动拖放手势

    当检测到拖动手势时，应用程序可以决定是否启动拖放手势，或者继续按下按钮释放手势。

    默认拖动检测机制使用鼠标移动与按下的按钮结合滞后。 应用程序可以增加此行为。 每个MOUSE_PRESSED和MOUSE_DRAGGED事件都有一个dragDetect标志，用于确定是否检测到拖动手势。 该标志的默认值取决于默认检测机制，可以通过调用事件处理程序中的setDragDetect()进行修改。 当处理其中一个事件以dragDetect标志设置为true结束时，将DRAG_DETECTED MouseEvent发送到潜在的手势源（按下鼠标按钮的对象）。 此事件通知手势检测。

    在DRAG_DETECTED事件处理程序中，如果在节点或场景上调用startDragAndDrop()方法，并将拖动的数据提供给所返回的Dragboard ，则startDragAndDrop()所调用的对象视为手势源，并启动拖放手势。 Dragboard具有系统剪贴板功能，特别用于拖放数据传输。

    startDragAndDrop()方法需要一组由手势源支持的TransferMode 。 例如，只传递TransferMode.COPY表示手势源仅允许复制数据，而不是移动或引用。

    以下示例显示了一个简单的拖放源： 

      Rectangle rect = new Rectangle(100, 100);
rect.setOnDragDetected(new EventHandler<MouseEvent>() {
    @Override public void handle(MouseEvent event) {
        Dragboard db = startDragAndDrop(TransferMode.ANY);
        ClipboardContent content = new ClipboardContent();
        content.putString("Hello!");
        db.setContent(content);
        event.consume();
    }
});

    潜在下降目标

    拖放手势已被启动之后，任何物体（ Node ， Scene在其上拖动鼠标）是一种潜在的放置目标。

    当鼠标拖动到潜在的下降目标的边界时，潜在的目标将获得一个DRAG_ENTERED事件。 当鼠标拖动到潜在目标的边界之外时，它会获得DRAG_EXITED事件。 还有起泡的DRAG_ENTERED_TARGET和DRAG_EXITED_TARGET变种。 他们的行为与鼠标输入/退出事件相似，请参阅MouseEvent概述。

    潜在的投放目标可以决定改变其外观，让用户知道拖放的数据可以丢弃。 这可以在DRAG_OVER事件处理程序中，基于鼠标的位置来完成。 另一个选择是在DRAG_ENTERED和DRAG_EXITED处理程序中更改潜在目标的外观。

    在DRAG_OVER事件处理程序中，潜在的丢弃目标具有使其知道它是实际目标的能力。 这是通过调用acceptTransferModes(TransferMode...)的事件，通过传输模式，它愿意接受。 如果在事件传送期间没有被调用 ，或者如果手势源不支持所传送的传送模式，则潜在的丢弃目标不被认为是实际的丢弃目标 。

    通过致电acceptTransferModes(TransferMode...)决定天气接受事件时，应考虑Dragboard上可用的数据类型。 访问Dragboard由getDragboard()提供。

    当接受一个事件时，潜在的手势目标决定哪一个TransferMode被接受。 要做出决定，可以使用DragBoard.getTransferModes() （由手势源支持的传输模式的集合）和DragEvent.getTransferMode() （由平台发布的默认传输模式，由关键修饰符驱动）。 将更多的传输模式传递到acceptTransferModes(TransferMode...)方法是acceptTransferModes(TransferMode...) 。 在这种情况下，它代表应用程序做出决定（如果手势源支持并由手势目标接受，则选择默认模式，否则选择支持和接受的最常见模式）。 DRAG_DROPPED事件的getTransferMode()稍后报告DRAG_OVER事件处理程序接受的传输模式。

    当鼠标按钮被释放时，拖放手势结束。 如果这种情况发生在通过手势源支持的传输模式接受的DRAG_OVER事件的手势目标上， DRAG_OVER将DRAG_DROPPED事件发送到手势目标。 在其处理程序中，手势目标可以访问拖板上的数据。 数据传输（或决定不传输）后，手势需要通过调用setDropCompleted(Boolean)完成。 Boolean参数表示数据是否已成功传输。 如果没有被调用，手势被认为是不成功的。

    以下示例显示了文本数据的简单拖放目标： 

      Rectangle rect = new Rectangle(100, 100);

rect.setOnDragOver(new EventHandler<DragEvent>() {
    @Override public void handle(DragEvent event) {
        Dragboard db = event.getDragboard();
        if (db.hasString()) {
            event.acceptTransferModes(TransferMode.COPY_OR_MOVE);
        }
        event.consume();
    }
});

rect.setOnDragDropped(new EventHandler<DragEvent>() {
    @Override public void handle(DragEvent event) {
        Dragboard db = event.getDragboard();
        boolean success = false;
        if (db.hasString()) {
            System.out.println("Dropped: " + db.getString());
            success = true;
        }
        event.setDropCompleted(success);
        event.consume();
    }
});

    拖动源：完成拖放手势

    手势完成后，无论成功或不成功的数据传输或被取消， DRAG_DONE事件都将发送到手势源。 事件的getTransferMode()方法向手势源指示数据传输是如何完成的。 如果传输模式具有值MOVE ，则允许源清除其数据。 清除源的数据给用户通过拖放手势移动了数据的适当外观。 如果它的值为null ，则拖放手势将结束，而不会传输任何数据。 这可能是因为不是放置目标的节点上的鼠标释放事件，或者用户按ESC键取消拖放手势，或者通过手势目标报告不成功的数据传输。

    从以下版本开始：
    JavaFX 2.0
    另请参见：
    Serialized Form

    • 构造方法详细信息

      • DragEvent

        public DragEvent​(Object source,
                 EventTarget target,
                 EventType<DragEvent> eventType,
                 Dragboard dragboard,
                 double x,
                 double y,
                 double screenX,
                 double screenY,
                 TransferMode transferMode,
                 Object gestureSource,
                 Object gestureTarget,
                 PickResult pickResult)
        构造新的DragEvent事件。 对于DRAG_DROPPED和DRAG_DONE事件类型， accepted状态和acceptedTransferMode根据通过的transferMode进行设置。
        参数
        source - 事件的来源。 可以为null。
        target - 事件的目标。 可以为null。
        eventType - 事件的类型。
        dragboard - 事件的拖板。
        x - 相对于场景的x。
        y - 相对于场景的y。
        screenX - 相对于屏幕的x坐标。
        screenY - 相对于屏幕的y坐标。
        transferMode - 事件的传输模式。
        gestureSource - 事件的DnD手势的来源。
        gestureTarget - 事件的DnD手势的目标。
        pickResult - 选择结果。 可以为null，在这种情况下，基于场景坐标和目标构建没有任何进一步值的2D选取结果
        从以下版本开始：
        JavaFX 8.0

      • DragEvent

        public DragEvent​(EventType<DragEvent> eventType,
                 Dragboard dragboard,
                 double x,
                 double y,
                 double screenX,
                 double screenY,
                 TransferMode transferMode,
                 Object gestureSource,
                 Object gestureTarget,
                 PickResult pickResult)
        构造具有空源和目标的新的DragEvent事件。
        参数
        eventType - 事件的类型。
        dragboard - 事件的拖板。
        x - 相对于场景的x。
        y - 相对于现场的y。
        screenX - 相对于屏幕的x坐标。
        screenY - 相对于屏幕的y坐标。
        transferMode - 事件的传输模式。
        gestureSource - 事件的DnD手势的来源。
        gestureTarget - 事件的DnD手势的目标。
        pickResult - 选择结果。 可以为null，在这种情况下，基于场景坐标构建没有任何进一步值的2D选取结果
        从以下版本开始：
        JavaFX 8.0

    • 方法详细信息

      • copyFor

        public DragEvent copyFor​(Object source,
                         EventTarget target,
                         Object gestureSource,
                         Object gestureTarget,
                         EventType<DragEvent> eventType)
        创建给定字段替换的给定拖动事件的副本。
        参数
        source - 复制事件的新来源
        target - 复制事件的新目标
        gestureSource - 新的手势源。
        gestureTarget - 新的手势目标。
        eventType - 新的eventType
        结果
        事件副本与字段
        从以下版本开始：
        JavaFX 8.0

      • copyFor

        public DragEvent copyFor​(Object newSource,
                         EventTarget newTarget)
        描述从类复制： Event
        使用指定的事件源和目标创建并返回此事件的副本。 如果源或目标设置为null ，它将被替换为NULL_SOURCE_TARGET值。
        重写：
        copyFor Event
        参数
        newSource - 复制事件的新来源
        newTarget - 复制事件的新目标
        结果
        事件副本与新的源和目标

      • copyFor

        public DragEvent copyFor​(Object source,
                         EventTarget target,
                         EventType<DragEvent> type)
        创建给定字段替换的给定拖动事件的副本。
        参数
        source - 复制事件的来源
        target - 复制事件的目标
        type - 事件类型
        结果
        事件副本与字段
        从以下版本开始：
        JavaFX 8.0

      • getEventType

        public EventType<DragEvent> getEventType​()
        描述从类复制： Event
        获取此事件的事件类型。 同一个Event类的对象可以有不同的事件类型。 这些事件类型进一步指定发生什么样的事件。
        重写：
        getEventType在 InputEvent
        结果
        事件类型

      • getX

        public final double getX​()
        事件相对于DragEvent源的原点的水平位置。
        结果
        事件的水平位置相对于DragEvent的来源的起点

      • getY

        public final double getY​()
        事件相对于DragEvent源的原点的垂直位置。
        结果
        事件相对于DragEvent源的起点的垂直位置

      • getZ

        public final double getZ​()
        事件的相对于MouseEvent源的来源的深度位置。
        结果
        事件的相对于MouseEvent源的起点的深度位置
        从以下版本开始：
        JavaFX 8.0

      • getScreenX

        public final double getScreenX​()
        返回事件的绝对水平位置。
        结果
        绝对水平位置的事件

      • getScreenY

        public final double getScreenY​()
        返回事件的绝对垂直位置。
        结果
        事件的绝对垂直位置

      • getSceneX

        public final double getSceneX​()
        返回事件相对于包含DragEvent源的Scene的原点的水平位置。 如果节点不在一个Scene ，那么该值相对于DragEvent节点最根的父节点的boundsInParent。 请注意，在3D场景中，这表示应用投影变换后的平面坐标。
        结果
        事件的水平位置相对于包含DragEvent源的 Scene的原点

      • getSceneY

        public final double getSceneY​()
        返回事件相对于包含DragEvent源的Scene的原点的垂直位置。 如果节点不在一个Scene ，则该值相对于DragEvent节点最根本父级的boundsInParent。 请注意，在3D场景中，这表示应用投影变换后的平面坐标。
        结果
        事件的垂直位置相对于包含DragEvent源的 Scene的原点

      • getPickResult

        public final PickResult getPickResult​()
        返回有关选择的信息。
        结果
        新的PickResult对象包含有关选择的信息
        从以下版本开始：
        JavaFX 8.0

      • getGestureSource

        public final Object getGestureSource​()
        拖放手势的源对象。 手势源是开始拖放操作的对象。 在手势来自另一应用的情况下，值null是有效的。
        结果
        源对象的拖放手势

      • getGestureTarget

        public final Object getGestureTarget​()
        拖放手势的目标对象。 手势目标是接受拖动事件的对象。 值null在拖放手势已被取消或完成而没有发生转移或目前没有事件目标接受拖动事件的情况下有效。
        结果
        拖放手势的目标对象

      • getTransferMode

        public final TransferMode getTransferMode​()
        数据传输模式。 在执行数据传输之前，这是系统根据诸如用户持有某些修饰符的输入事件设置的默认传输模式。 在数据传输的时候（在DRAG_DROPPED事件中）它决定了以前的DRAG_OVER处理程序接受的传输模式。 数据传输后（DRAG_DONE事件）确定传输完成的实际模式。
        结果
        数据传输模式

      • getAcceptedTransferMode

        public final TransferMode getAcceptedTransferMode​()
        获得潜在目标接受的传输模式。
        结果
        潜在目标接受的转移模式

      • getAcceptingObject

        public final Object getAcceptingObject​()
        接受拖动的对象。
        结果
        接受拖动的对象
        从以下版本开始：
        JavaFX 8.0

      • getDragboard

        public final Dragboard getDragboard​()
        可用于传输数据的拖板。 数据可以放在DRAG_DETECTED鼠标事件的处理程序的这个DRAG_DETECTED 。 可以从DRAG_DROPPED事件的处理程序中的这个拖板复制数据。
        结果
        可用于传输数据的拖板

      • acceptTransferModes

        public void acceptTransferModes​(TransferMode... transferModes)
        接受这个DragEvent ，选择拖放操作的传输模式。 用于指示从DRAG_OVER事件处理程序接收此事件的潜在丢弃目标是丢弃目标。

        它接受传递到此方法并由手势源支持的传输模式之一。 如果可能，它接受默认传输模式，否则是最常见的可接受模式之一。

        参数
        transferModes - 丢弃操作的传输模式。

      • setDropCompleted

        public void setDropCompleted​(boolean isTransferDone)
        表示在DRAG_DROPPED事件处理程序中， DragEvent传输处理已成功完成。 此电话后可能会发生dragboard访问。
        参数
        isTransferDone - true表示传输成功。
        异常
        IllegalStateException - 如果这不是DRAG_DROPPED事件

      • isDropCompleted

        public boolean isDropCompleted​()
        是否 setDropCompleted(true)已被呼吁这个事件。
        结果
        如果已经调用了 setDropCompleted(true) true