Класс DragSource

public class DragSource
extends Object
implements Serializable

Сущность, ответственная за инициирование операции Перетаскивания и Опускания, может использоваться в нескольких сценариях:

• 1 экземпляр на JVM на протяжении всего её существования.
• 1 экземпляр на каждый потенциальный класс объекта-инициатора перетаскивания (например, TextField). [зависит от реализации]
• 1 экземпляр на конкретный объект или приложение, связанный с экземпляром DragSource в графическом интерфейсе. [зависит от реализации]
• Любое другое произвольное отношение. [зависит от реализации]

После получения экземпляра DragSource необходимо также получить DragGestureRecognizer, чтобы ассоциировать DragSource с конкретным компонентом.

Первоначальная интерпретация жеста пользователя и последующее начало операции перетаскивания являются обязанностью реализующего DragGestureRecognizer, который обычно реализуется классом DragGestureListener.

При возникновении жеста перетаскивания вызывается метод startDrag() DragSource для обработки навигационных жестов пользователя и доставки уведомлений протокола Перетаскивания и Опускания. DragSource разрешает только одну операцию Перетаскивания и Опускания в любой момент времени и отклоняет дальнейшие запросы startDrag(), выбросив исключение DragGestureException, пока текущая операция не будет завершена.

Метод startDrag() вызывает метод createDragSourceContext() для создания соответствующего DragSourceContext и связывает его с DragSource.

Если система Перетаскивания и Опускания по какой-либо причине не может инициировать операцию перетаскивания, метод startDrag() выбросит исключение DragGestureException, сигнализируя об этом условии. Обычно это исключение выбрасывается, когда базовая платформа не находится в состоянии инициировать перетаскивание или указанные параметры недействительны.

Обратите внимание, что набор операций, доступных источнику в начале операции перетаскивания, не может измениться до тех пор, пока операция не будет завершена. Операция(и) неизменна на протяжении всей операции относительно источника.

Поля

DefaultCopyDrop

public static final Cursor DefaultCopyDrop

Значение по умолчанию Cursor для операции копирования, указывающее, что перенос в данный момент разрешен. null если GraphicsEnvironment.isHeadless() возвращает true.

См. также:

GraphicsEnvironment.isHeadless()

DefaultMoveDrop

public static final Cursor DefaultMoveDrop

Значение по умолчанию Cursor для операции перемещения, указывающее, что перенос в данный момент разрешен. null если GraphicsEnvironment.isHeadless() возвращает true.

См. также:

GraphicsEnvironment.isHeadless()

DefaultLinkDrop

public static final Cursor DefaultLinkDrop

Значение по умолчанию Cursor для операции создания ссылки, указывающее, что перенос в данный момент разрешен. null если GraphicsEnvironment.isHeadless() возвращает true.

См. также:

GraphicsEnvironment.isHeadless()

DefaultCopyNoDrop

public static final Cursor DefaultCopyNoDrop

Значение по умолчанию Cursor для операции копирования, указывающее, что перенос в данный момент запрещен. null если GraphicsEnvironment.isHeadless() возвращает true.

См. также:

GraphicsEnvironment.isHeadless()

DefaultMoveNoDrop

public static final Cursor DefaultMoveNoDrop

Значение по умолчанию Cursor для операции перемещения, указывающее, что перенос в данный момент запрещен. null если GraphicsEnvironment.isHeadless() возвращает true.

См. также:

GraphicsEnvironment.isHeadless()

DefaultLinkNoDrop

public static final Cursor DefaultLinkNoDrop

Значение по умолчанию Cursor для операции создания ссылки, указывающее, что перенос в данный момент запрещен. null если GraphicsEnvironment.isHeadless() возвращает true.

См. также:

GraphicsEnvironment.isHeadless()

Конструкторы

DragSource

public DragSource()
           throws HeadlessException

Создает новый DragSource.

Исключения:

HeadlessException - если GraphicsEnvironment.isHeadless() возвращает true

См. также:

GraphicsEnvironment.isHeadless()

Методы

getDefaultDragSource

public static DragSource getDefaultDragSource()

Получает объект DragSource, связанный с базовой платформой.

Возвращает:

объект DragSource платформы

Исключения:

HeadlessException - если GraphicsEnvironment.isHeadless() возвращает true

См. также:

GraphicsEnvironment.isHeadless()

isDragImageSupported

public static boolean isDragImageSupported()

Возвращает:

доступна ли поддержка перетаскивания изображений на этой платформе

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Image dragImage,
                      Point imageOffset,
                      Transferable transferable,
                      DragSourceListener dsl,
                      FlavorMap flavorMap)
               throws InvalidDnDOperationException

Параметры:

trigger - DragGestureEvent, инициировавший перетаскивание

dragCursor - начальный Cursor для этой операции перетаскивания или null для обработки курсора по умолчанию; см. DragSourceContext для получения дополнительной информации о механизме обработки курсора во время перетаскивания

dragImage - перетаскиваемое изображение или null

imageOffset - смещение начала координат Image относительно точки доступа Cursor в момент срабатывания триггера

transferable - данные перетаскиваемого объекта

dsl - DragSourceListener

flavorMap - используемая FlavorMap, или null

Исключения:

InvalidDnDOperationException - если система перетаскивания не может начать операцию перетаскивания, или если пользователь пытается начать перетаскивание, пока выполняется другая операция перетаскивания

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Transferable transferable,
                      DragSourceListener dsl,
                      FlavorMap flavorMap)
               throws InvalidDnDOperationException

Параметры:

trigger - DragGestureEvent, инициировавший перетаскивание

dragCursor - начальный Cursor для этой операции перетаскивания или null для обработки курсора по умолчанию; см. DragSourceContext для получения дополнительной информации о механизме обработки курсора во время перетаскивания

transferable - данные перетаскиваемого объекта

dsl - DragSourceListener

flavorMap - используемая FlavorMap или null

Исключения:

InvalidDnDOperationException - если система перетаскивания не может начать операцию перетаскивания, или если пользователь пытается начать перетаскивание, пока выполняется другая операция перетаскивания

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Image dragImage,
                      Point dragOffset,
                      Transferable transferable,
                      DragSourceListener dsl)
               throws InvalidDnDOperationException

Параметры:

trigger - DragGestureEvent, инициировавший перетаскивание

dragCursor - начальный Cursor для этой операции перетаскивания или null для обработки курсора по умолчанию; см. DragSourceContext для получения дополнительной информации о механизме обработки курсора во время перетаскивания

dragImage - Image для перетаскивания или null

dragOffset - смещение начала координат Image относительно точки доступа Cursor в момент срабатывания триггера

transferable - данные перетаскиваемого объекта

dsl - DragSourceListener

Исключения:

InvalidDnDOperationException - если система перетаскивания не может начать операцию перетаскивания, или если пользователь пытается начать перетаскивание, пока выполняется другая операция перетаскивания

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Transferable transferable,
                      DragSourceListener dsl)
               throws InvalidDnDOperationException

Параметры:

trigger - DragGestureEvent, инициировавший перетаскивание

dragCursor - начальный Cursor для этой операции перетаскивания или null для обработки курсора по умолчанию; см. класс DragSourceContext для получения дополнительной информации о механизме обработки курсора во время перетаскивания

transferable - данные перетаскиваемого объекта

dsl - DragSourceListener

Исключения:

InvalidDnDOperationException - если система перетаскивания не может начать операцию перетаскивания, или если пользователь пытается начать перетаскивание, пока выполняется другая операция перетаскивания

createDragSourceContext

protected DragSourceContext createDragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp,
                                                    DragGestureEvent dgl,
                                                    Cursor dragCursor,
                                                    Image dragImage,
                                                    Point imageOffset,
                                                    Transferable t,
                                                    DragSourceListener dsl)

Параметры:

dscp - Перетаскиваемый DragSourceContextPeer для этого перетаскивания

dgl - DragGestureEvent , вызвавшее перетаскивание

dragCursor - Начальное Cursor для этой операции перетаскивания или null для обработки курсора по умолчанию; см. класс DragSourceContext для получения более подробной информации о механизме обработки курсора во время перетаскивания и перемещения

dragImage - Image для перетаскивания или null

imageOffset - Смещение начала Image от точки привязки курсора в момент срабатывания

t - Данные объекта перетаскивания

dsl - DragSourceListener

Возвращает:

значение DragSourceContext

Исключение:

NullPointerException - если dscp является null

NullPointerException - если dgl является null

NullPointerException - если dragImage не является null и imageOffset является null

NullPointerException - если t является null

IllegalArgumentException - если Component , связанное с событием срабатывания, является null.

IllegalArgumentException - если DragSource для события срабатывания является null.

IllegalArgumentException - если действие перетаскивания для события срабатывания является DnDConstants.ACTION_NONE.

IllegalArgumentException - если действия источника для DragGestureRecognizer , связанного с событием срабатывания, равны DnDConstants.ACTION_NONE.

getFlavorMap

public FlavorMap getFlavorMap()

Возвращает:

значение FlavorMap для этого DragSource

createDragGestureRecognizer

public <T extends DragGestureRecognizer> T createDragGestureRecognizer(Class<T> recognizerAbstractClass,
                                                                       Component c,
                                                                       int actions,
                                                                       DragGestureListener dgl)

Параметры:

recognizerAbstractClass - запрашиваемый абстрактный тип

actions - разрешенные действия перетаскивания источника

c - целевой Component

dgl - DragGestureListener для уведомления

Возвращает:

новый DragGestureRecognizer или null , если метод Toolkit.createDragGestureRecognizer не имеет реализации для запрошенного подкласса DragGestureRecognizer и возвращает null

createDefaultDragGestureRecognizer

public DragGestureRecognizer createDefaultDragGestureRecognizer(Component c,
                                                                int actions,
                                                                DragGestureListener dgl)

Параметры:

c - целевой Component для распознавателя

actions - разрешенные действия источника

dgl - DragGestureListener для уведомления

Возвращает:

новый DragGestureRecognizer или null , если метод Toolkit.createDragGestureRecognizer не имеет реализации для запрошенного подкласса DragGestureRecognizer и возвращает null

addDragSourceListener

public void addDragSourceListener(DragSourceListener dsl)

Добавляет указанного DragSourceListener к этому DragSource для получения событий источника перетаскивания во время операций перетаскивания, инициированных этим DragSource. Если задан слушатель null , никакие действия не выполняются и исключение не выбрасывается.

Параметры:

dsl - DragSourceListener для добавления

Since:

1.4

См. также:

removeDragSourceListener(java.awt.dnd.DragSourceListener), getDragSourceListeners()

removeDragSourceListener

public void removeDragSourceListener(DragSourceListener dsl)

Удаляет указанного DragSourceListener из этого DragSource. Если задан слушатель null , никакие действия не выполняются и исключение не выбрасывается. Если слушатель, указанный в аргументе, ранее не был добавлен к этому DragSource, никакие действия не выполняются и исключение не выбрасывается.

Параметры:

dsl - DragSourceListener для удаления

Since:

1.4

См. также:

addDragSourceListener(java.awt.dnd.DragSourceListener), getDragSourceListeners()

getDragSourceListeners

public DragSourceListener[] getDragSourceListeners()

Возвращает всех DragSourceListener , зарегистрированных с этим DragSource.

Возвращает:

все DragSource этого DragSource или пустой массив, если такие слушатели не зарегистрированы

Since:

1.4

См. также:

addDragSourceListener(java.awt.dnd.DragSourceListener), removeDragSourceListener(java.awt.dnd.DragSourceListener)

addDragSourceMotionListener

public void addDragSourceMotionListener(DragSourceMotionListener dsml)

Добавляет указанного DragSourceMotionListener к этому DragSource для получения событий движения перетаскивания во время операций перетаскивания, инициированных этим DragSource. Если задан слушатель null , никакие действия не выполняются и исключение не выбрасывается.

Параметры:

dsml - DragSourceMotionListener для добавления

Since:

1.4

См. также:

removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener), getDragSourceMotionListeners()

removeDragSourceMotionListener

public void removeDragSourceMotionListener(DragSourceMotionListener dsml)

Удаляет указанного DragSourceMotionListener из этого DragSource. Если задан слушатель null , никакие действия не выполняются и исключение не выбрасывается. Если слушатель, указанный в аргументе, ранее не был добавлен к этому DragSource, никакие действия не выполняются и исключение не выбрасывается.

Параметры:

dsml - DragSourceMotionListener для удаления

Since:

1.4

См. также:

addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener), getDragSourceMotionListeners()

getDragSourceMotionListeners

public DragSourceMotionListener[] getDragSourceMotionListeners()

Возвращает всех DragSourceMotionListener , зарегистрированных с этим DragSource.

Возвращает:

все DragSource этого DragSource или пустой массив, если такие слушатели не зарегистрированы

Since:

1.4

См. также:

addDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener), removeDragSourceMotionListener(java.awt.dnd.DragSourceMotionListener)

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)

Получает все объекты, текущие зарегистрированные как FooListener в этом DragSource. FooListener регистрируются с помощью метода addFooListener.

Параметры:

listenerType - тип запрашиваемых слушателей; этот параметр должен указать интерфейс, наследуемый от java.util.EventListener

Возвращает:

массив всех объектов, зарегистрированных как FooListener в этом DragSource, или пустой массив, если такие слушатели не были добавлены

Исключение:

ClassCastException - если listenerType не указывает класс или интерфейс, реализующий java.util.EventListener

Since:

1.4

См. также:

getDragSourceListeners(), getDragSourceMotionListeners()

getDragThreshold

public static int getDragThreshold()

Возвращает:

порог движения жеста перетаскивания

Since:

1.5

См. также:

MouseDragGestureRecognizer