Класс 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 для отмены жеста перетаскивания и отпускания, или целевая точка сообщает об неудачной передаче данных.