Класс TransferHandler

java.lang.Object

javax.swing.TransferHandler

Все реализованные интерфейсы:: Serializable

public class TransferHandler extends Object implements Serializable

Этот класс используется для обработки передачи Transferable в компоненты Swing и из них. Transferable используется для представления данных, которыми обмениваются при вырезании, копировании или вставке из буфера обмена или в него. Он также используется в операциях перетаскивания для представления перетаскивания из компонента и сброса в компонент. Swing предоставляет функциональность, которая автоматически поддерживает привязки клавиш для вырезания, копирования и вставки, используя возможности реализации этого класса. Swing также предоставляет функциональность, которая автоматически поддерживает перетаскивание, используя возможности реализации этого класса. Разработчик Swing может сосредоточиться на определении семантики передачи, главным образом задавая свойство transferHandler компонента Swing.

Этот класс реализован таким образом, чтобы обеспечивать поведение по умолчанию для передачи свойства компонента простым указанием имени свойства в конструкторе. Например, для передачи цвета переднего плана от одного компонента к другому через буфер обмена или посредством перетаскивания можно создать TransferHandler со строкой "foreground". Встроенная поддержка будет использовать цвет, возвращаемый getForeground, в качестве источника передачи, а setForeground — в качестве цели передачи.

Дополнительные сведения см. в разделе «Как использовать перетаскивание и передачу данных» в учебнике Java.

Начиная с:: 1.4

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static class`	`TransferHandler.DropLocation`	Представляет место, куда следует вставить сброшенные данные.
`static final class`	`TransferHandler.TransferSupport`	Этот класс содержит все необходимые сведения о передаче через буфер обмена или посредством перетаскивания, а также позволяет настраивать параметры перетаскивания.

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final int`	`COPY`	`int`, представляющее действие передачи «копирование».
`static final int`	`COPY_OR_MOVE`	`int`, представляющее возможность выполнения исходного действия «копирование» или «перемещение».
`static final int`	`LINK`	`int`, представляющее действие передачи «ссылка».
`static final int`	`MOVE`	`int`, представляющее действие передачи «перемещение».
`static final int`	`NONE`	`int`, представляющее отсутствие действия передачи.

Краткое описание конструкторов

TransferHandler()

TransferHandler(String property)

Модификатор	Конструктор	Описание
`protected`	Вспомогательный конструктор для подклассов.
	Создает обработчик передачи, который может передавать свойство Java Bean из одного компонента в другой через буфер обмена или посредством перетаскивания.

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`canImport(JComponent comp, DataFlavor[] transferFlavors)`	Показывает, примет ли компонент импорт указанного набора форматов данных до фактической попытки импорта.
`boolean`	`canImport(TransferHandler.TransferSupport support)`	Этот метод многократно вызывается во время операции перетаскивания, чтобы разработчик мог настроить свойства передачи и определить, допустима ли она; возвращаемое значение `true` означает, что передача, представленная заданным `TransferSupport` (содержащим все сведения о передаче), допустима в данный момент, а значение `false` — что передача отклонена.
`protected Transferable`	`createTransferable(JComponent c)`	Создает `Transferable` для использования в качестве источника передачи данных.
`void`	`exportAsDrag(JComponent comp, InputEvent e, int action)`	Инициирует поддержку перетаскивания в Swing.
`protected void`	`exportDone(JComponent source, Transferable data, int action)`	Вызывается после экспорта данных.
`void`	`exportToClipboard(JComponent comp, Clipboard clip, int action)`	Выполняет передачу данных из указанного компонента в указанный буфер обмена.
`static Action`	`getCopyAction()`	Возвращает `Action`, выполняющий копирование в буфер обмена.
`static Action`	`getCutAction()`	Возвращает `Action`, выполняющий вырезание в буфер обмена.
`Image`	`getDragImage()`	Возвращает изображение для перетаскивания.
`Point`	`getDragImageOffset()`	Возвращает смещение точки привязки изображения для перетаскивания.
`static Action`	`getPasteAction()`	Возвращает `Action`, выполняющий вставку из буфера обмена.
`int`	`getSourceActions(JComponent c)`	Возвращает тип действий передачи, поддерживаемых источником: любую комбинацию побитового ИЛИ из `COPY`, `MOVE` и `LINK`.
`Icon`	`getVisualRepresentation(Transferable t)`	Возвращает объект, задающий внешний вид передачи.
`boolean`	`importData(JComponent comp, Transferable t)`	Выполняет передачу данных из буфера обмена или операции сброса DND в компонент.
`boolean`	`importData(TransferHandler.TransferSupport support)`	Выполняет передачу данных из буфера обмена или посредством перетаскивания.
`void`	`setDragImage(Image img)`	Задает параметр изображения для перетаскивания.
`void`	`setDragImageOffset(Point p)`	Задает смещение точки привязки изображения для перетаскивания.

Методы, объявленные в классе Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание полей

NONE

public static final int NONE

int, представляющее отсутствие действия передачи.

См. также:

COPY

public static final int COPY

int, представляющее действие передачи «копирование». Это значение используется, когда данные копируются в буфер обмена или в другое место посредством перетаскивания.

См. также:

MOVE

public static final int MOVE

int, представляющее действие передачи «перемещение». Это значение используется, когда данные перемещаются в буфер обмена (то есть вырезаются) или в другое место посредством перетаскивания.

См. также:

COPY_OR_MOVE

public static final int COPY_OR_MOVE

int, представляющее возможность выполнения исходного действия «копирование» или «перемещение».

См. также:

LINK

public static final int LINK

int, представляющее действие передачи «ссылка». Это значение используется, чтобы указать, что данные следует связать в операции перетаскивания.

Начиная с:

1.6

См. также:

Подробное описание конструкторов

TransferHandler

public TransferHandler(String property)

Создает обработчик передачи, который может передавать свойство Java Bean из одного компонента в другой через буфер обмена или посредством перетаскивания.

Параметры:: property — имя передаваемого свойства; может быть null, если с обработчиком передачи не связано никакое свойство (например, для подкласса, выполняющего передачу другого типа)

TransferHandler

protected TransferHandler()

Вспомогательный конструктор для подклассов.

Подробное описание методов

getCutAction

public static Action getCutAction()

Возвращает Action, выполняющий вырезание в буфер обмена. При выполнении это действие работает с источником JComponent в ActionEvent, вызывая exportToClipboard с действием MOVE для TransferHandler компонента.

Возвращает:: Action для вырезания в буфер обмена

getCopyAction

public static Action getCopyAction()

Возвращает Action, выполняющий копирование в буфер обмена. При выполнении это действие работает с источником JComponent в ActionEvent, вызывая exportToClipboard с действием COPY для TransferHandler компонента.

Возвращает:: Action для копирования в буфер обмена

getPasteAction

public static Action getPasteAction()

Возвращает Action, выполняющий вставку из буфера обмена. При выполнении это действие работает с источником JComponent в ActionEvent, вызывая importData с содержимым буфера обмена для TransferHandler компонента.

Возвращает:: Action для вставки из буфера обмена

setDragImage

public void setDragImage(Image img)

Задает параметр изображения для перетаскивания. Изображение должно быть подготовлено к отображению к моменту вызова. По соображениям производительности изображение хранится по ссылке.

Параметры:: img — изображение для перетаскивания

getDragImage

public Image getDragImage()

Возвращает изображение для перетаскивания. Если изображение для перетаскивания отсутствует, возвращается null.

Возвращает:: ссылку на изображение для перетаскивания

setDragImageOffset

public void setDragImageOffset(Point p)

Задает смещение точки привязки изображения для перетаскивания. Значение не может быть null.

Параметры:: p — объект Point, задающий координаты смещения точки привязки изображения относительно его верхнего левого угла

getDragImageOffset

public Point getDragImageOffset()

Возвращает смещение точки привязки изображения для перетаскивания.

Возвращает:: объект Point, задающий координаты смещения точки привязки изображения относительно его верхнего левого угла. По умолчанию возвращается точка (0,0).

exportAsDrag

public void exportAsDrag(JComponent comp, InputEvent e, int action)

Инициирует поддержку перетаскивания в Swing. Этот метод вызывается различными реализациями пользовательского интерфейса из пакета javax.swing.plaf.basic, если для компонента задано свойство dragEnabled. Пользовательские реализации пользовательского интерфейса могут вызывать этот метод для использования поддержки перетаскивания в Swing. Этот метод также может вызываться расширением Swing, написанным как подкласс JComponent, чтобы использовать поддержку перетаскивания в Swing.

Передача не обязательно будет завершена к моменту возврата этого вызова (то есть вызов не блокируется в ожидании сброса). Передача выполняется механизмом java.awt.dnd Swing и не требует от разработчика дополнительных действий. После завершения передачи будет вызван метод exportDone.

Параметры:: comp — компонент, содержащий передаваемые данные; передается для обеспечения совместного использования TransferHandler; e — событие, инициировавшее передачу; action — первоначально запрошенное действие передачи: COPY, MOVE или LINK; система DnD может изменить используемое действие в ходе операции перетаскивания

exportToClipboard

public void exportToClipboard(JComponent comp, Clipboard clip, int action) throws IllegalStateException

Выполняет передачу данных из указанного компонента в указанный буфер обмена. Этот метод вызывается действиями вырезания и копирования по умолчанию, зарегистрированными в карте действий компонента.

Передача выполняется с помощью механизма java.awt.datatransfer и не требует от разработчика дополнительных действий. Передача данных будет завершена, а метод exportDone будет вызван с выполненным действием до возврата из этого метода. Если при попытке поместить данные в буфер обмена он окажется недоступен, исключение IllegalStateException, выбрасываемое методом Clipboard.setContents(Transferable, ClipboardOwner), будет передано вызывающему коду через этот метод. Однако для согласованности сначала будет вызван exportDone с действием NONE.

Параметры:

comp — компонент, содержащий передаваемые данные; передается для обеспечения совместного использования TransferHandler

clip — буфер обмена, в который следует передать данные

action — запрошенное действие передачи; должно иметь значение COPY или MOVE; выполняемая операция представляет собой пересечение возможностей передачи, заданных методом getSourceActions, и запрошенного действия; если запрошенное действие не поддерживается, результатом пересечения может быть действие NONE

Исключения:

IllegalStateException — если буфер обмена в данный момент недоступен

См. также:

importData

public boolean importData(TransferHandler.TransferSupport support)

Выполняет передачу данных из буфера обмена или посредством перетаскивания. Импортируемые Transferable и компонент, в который выполняется передача, содержатся в TransferSupport.

Хотя реализация перетаскивания вызывает canImport, чтобы определить допустимость передачи перед вызовом этого метода, реализация вставки этого не делает. Поэтому при вызове этого метода для вставки нельзя считать, что передача допустима. Для обработки этого случая рекомендуется явно вызывать canImport.

Примечание. Объект TransferSupport, переданный этому методу, действителен только во время вызова метода. Не определено, какие значения он может содержать после возврата этого метода.

Параметры:

support — объект, содержащий сведения о передаче; не null.

Возвращает:

true, если данные были вставлены в компонент; в противном случае false

Исключения:

NullPointerException — если support имеет значение null

Начиная с:

1.6

См. также:

importData

public boolean importData(JComponent comp, Transferable t)

Выполняет передачу данных из буфера обмена или посредством операции сброса DND в компонент. Transferable представляет данные, которые следует импортировать в компонент.

Примечание. Теперь Swing вызывает более новую версию importData, принимающую TransferSupport, которая, в свою очередь, вызывает этот метод (если компонент в TransferSupport является JComponent). Разработчикам рекомендуется вызывать и переопределять более новую версию, поскольку она предоставляет больше сведений (и является единственной версией, поддерживающей использование с TransferHandler, заданным непосредственно для JFrame или другого объекта, не являющегося JComponent).

Параметры:

comp — компонент, принимающий передаваемые данные; передается для обеспечения совместного использования TransferHandler

t — импортируемые данные

Возвращает:

true, если данные были вставлены в компонент; в противном случае false

См. также:

canImport

public boolean canImport(TransferHandler.TransferSupport support)

Этот метод многократно вызывается во время операции перетаскивания, чтобы разработчик мог настроить свойства передачи и определить, допустима ли она; возвращаемое значение true означает, что передача, представленная заданным TransferSupport (содержащим все сведения о передаче), допустима в данный момент, а значение false — что передача отклонена.

Для компонентов, автоматически отображающих место сброса во время перетаскивания, принятие передачи по умолчанию означает, что это место следует показать. Это поведение можно изменить, вызвав setShowDropLocation для TransferSupport.

По умолчанию при принятии передачи выбранным действием сброса становится действие, выбранное пользователем жестом перетаскивания. Разработчик может переопределить его и выбрать другое действие из числа поддерживаемых исходных действий, вызвав setDropAction для TransferSupport.

При каждом вызове canImport объект TransferSupport содержит актуальное состояние. Поэтому все его свойства необходимо задавать при каждом вызове. При сбросе перед вызовом importData в последний раз вызывается canImport. Любое состояние, заданное для TransferSupport во время этого последнего вызова, будет доступно в importData.

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

Параметры:

support — объект, содержащий сведения о передаче; не null.

Возвращает:

true, если импорт возможен; в противном случае false

Исключения:

NullPointerException — если support имеет значение null

Начиная с:

1.6

См. также:

canImport

public boolean canImport(JComponent comp, DataFlavor[] transferFlavors)

Показывает, примет ли компонент импорт указанного набора форматов данных до фактической попытки импорта.

Примечание. Теперь Swing вызывает более новую версию canImport, принимающую TransferSupport, которая, в свою очередь, вызывает этот метод (только если компонент в TransferSupport является JComponent). Разработчикам рекомендуется вызывать и переопределять более новую версию, поскольку она предоставляет больше сведений (и является единственной версией, поддерживающей использование с TransferHandler, заданным непосредственно для JFrame или другого объекта, не являющегося JComponent).

Параметры:

transferFlavors — доступные форматы данных

Возвращает:

true, если данные можно вставить в компонент; в противном случае false

См. также:

getSourceActions

public int getSourceActions(JComponent c)

Возвращает тип действий передачи, поддерживаемых источником: любую комбинацию побитового ИЛИ из COPY, MOVE и LINK.

Некоторые модели не поддерживают изменение, поэтому в таких случаях не следует объявлять действие передачи MOVE. Возврат NONE отключает передачу данных из компонента.

Параметры:: c — компонент, содержащий передаваемые данные; передается для обеспечения совместного использования TransferHandler
Возвращает:: COPY, если свойство передачи найдено; в противном случае возвращает NONE

getVisualRepresentation

public Icon getVisualRepresentation(Transferable t)

Возвращает объект, задающий внешний вид передачи. Он полезен как для отображения обратной связи во время перетаскивания, так и для представления передачи в реализации буфера обмена с визуальным интерфейсом. Реализация интерфейса Icon не должна изменять графическую область отсечения или уровень альфа-канала. Значок не обязан быть прямоугольным или закрашивать весь ограничивающий прямоугольник; код, вызывающий метод отрисовки значка, не должен предполагать, что закрашены все пиксели. null является допустимым возвращаемым значением этого метода и указывает на отсутствие визуального представления. В этом случае вызывающий код может представить передаваемый объект любым способом.

Логика Swing по умолчанию не будет выполнять анимацию перетаскивания со смешением альфа-канала, если возвращается null.

Параметры:: t — передаваемые данные; предполагается, что это значение было создано методом createTransferable
Возвращает:: null, указывая на отсутствие визуального представления по умолчанию

createTransferable

protected Transferable createTransferable(JComponent c)

Создает Transferable для использования в качестве источника передачи данных. Возвращает представление передаваемых данных или null, если свойство компонента имеет значение null

Параметры:: c — компонент, содержащий передаваемые данные; передается для обеспечения совместного использования TransferHandler
Возвращает:: представление передаваемых данных или null, если свойство, связанное с c, имеет значение null

exportDone

protected void exportDone(JComponent source, Transferable data, int action)

Вызывается после экспорта данных. Если действием было MOVE, этот метод должен удалить переданные данные.

Реализация этого метода ничего не делает, поскольку MOVE не поддерживается этой реализацией как действие (getSourceActions не включает MOVE).

Параметры:: source — компонент, являвшийся источником данных; data — переданные данные или null, если действием было NONE.; action — фактически выполненное действие

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.desktop/javax/swing/TransferHandler.html