Класс 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. Вызывается различными реализациями UI в пакете javax.swing.plaf.basic, если свойство dragEnabled установлено для компонента. Может быть вызвано пользовательскими реализациями UI для использования поддержки перетаскивания 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 - если буфер обмена недоступен в данный момент

См. также:

Clipboard.setContents(Transferable, ClipboardOwner)

importData

public boolean importData(TransferHandler.TransferSupport support)

Вызывает перенос из буфера обмена или операции перетаскивания. Данные для импорта и компонент для переноса содержатся в TransferSupport.

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

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

Параметры:

support - объект, содержащий детали переноса, не null.

Возвращает:

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

Исключения:

NullPointerException - если support равно null

С:

1.6

См. также:

canImport(TransferHandler.TransferSupport)

importData

public boolean importData(JComponent comp, Transferable t)

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

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

Parameters:

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

t - данные для импорта

Returns:

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

See Also:

importData(TransferHandler.TransferSupport)

canImport

public boolean canImport(TransferHandler.TransferSupport support)

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

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

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

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

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

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

Parameters:

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

Returns:

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

Throws:

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

Since:

1.6

See Also:

canImport

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

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

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

Parameters:

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

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

Returns:

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

See Also:

canImport(TransferHandler.TransferSupport)

getSourceActions

public int getSourceActions(JComponent c)

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

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

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

getVisualRepresentation

public Icon getVisualRepresentation(Transferable t)

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

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

Parameters:: t - данные, подлежащие передаче; ожидается, что это значение было создано методом createTransferable
Returns:: null, что указывает на отсутствие стандартного визуального представления

createTransferable

protected Transferable createTransferable(JComponent c)

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

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

exportDone

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

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

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

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

© 1993, 2021, 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/17/docs/api/java.desktop/javax/swing/TransferHandler.html