Класс 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. В его обработчике целевая точка жеста может получить доступ к данным на dragboard. После передачи данных (или принятия решения о том, что передачу не выполнять), жест необходимо завершить, вызвав метод 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 для отмены жеста перетаскивания и перемещения, или целевая точка жеста сообщила об неудачной передаче данных.