Класс 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 установлено для компонента. Может быть вызвано пользовательскими реализациями 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 - если буфер обмена в настоящее время недоступен

См. также:

importData

public boolean importData(TransferHandler.TransferSupport support)

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

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

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

Parameters:

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

Returns:

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

Throws:

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

Since:

1.6

See Also:

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:

canImport

public boolean canImport(TransferHandler.TransferSupport support)

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

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

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

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

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

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:

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, 2023, 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/21/docs/api/java.desktop/javax/swing/TransferHandler.html