Класс DragEvent

Жест перетаскивания и падения может быть начат вызовом startDragAndDrop() (на узле или сцене) внутри обработчика события DRAG_DETECTED. Данные, которые нужно передать целевому элементу падения, помещаются в 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...). В этом случае он принимает решение от имени приложения (выбирает режим по умолчанию, если он поддерживается источником жеста и принимается целевым элементом жеста, в противном случае выбирает наиболее распространенный режим из поддерживаемых и принятых). Событие DRAG_DROPPED позже сообщает о режиме передачи, принятом обработчиком события 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 для отмены жеста перетаскивания и падения, или целевой элемент жеста сообщил об неудачной передаче данных.