Класс 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`	Представляет действие передачи "копировать".
`static final int`	`COPY_OR_MOVE`	Представляет возможность действия источника, либо "копировать", либо "переместить".
`static final int`	`LINK`	Представляет действие передачи "ссылка".
`static final int`	`MOVE`	Представляет действие передачи "переместить".
`static final int`	`NONE`	Представляет действие передачи "нет".

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

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)`	Вызывает передачу в компонент из буфера обмена или операции опускания перетаскивания.
`boolean`	`importData(TransferHandler.TransferSupport support)`	Вызывает передачу из буфера обмена или операции перетаскивания.
`void`	`setDragImage(Image img)`	Устанавливает параметр изображения перетаскивания.
`void`	`setDragImageOffset(Point p)`	Устанавливает смещение якоря для перетаскиваемого изображения.

Методы, объявленные в классе java.lang.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.

Перенос не обязательно будет завершен к возврату из этого вызова (т.е. вызов не блокирует ожидание завершения переноса). Перенос будет осуществлен через реализацию Swing механизма java.awt.dnd, не требуя дополнительных усилий от разработчика. Метод 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 содержит свежие данные. Поэтому все свойства, установленные на нем, должны быть установлены при каждом вызове. После выгрузки canImport вызывается один раз перед вызовом importData. Любые состояния, установленные на 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 не должна изменять графический буфер обмена или уровень альфа-канала. Реализация иконки не обязана быть прямоугольной или отрисовывать весь прямоугольник, а логика, вызывающая метод paint иконки, не должна предполагать, что отрисовываются все биты. 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://download.java.net/java/early_access/jdk24/docs/api/java.desktop/javax/swing/TransferHandler.html