Класс 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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Показывает, равен ли этот объект другому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API подлежит удалению в будущей версии. Финализация признана устаревшей и подлежит удалению в одном из следующих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.

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

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.

Этот метод не вызывается автоматически при выполнении операций вставки. Поэтому рекомендуется, чтобы реализации 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).

Параметры:

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

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.