Общие сведения о перетаскиванииDrag and Drop Overview

В этой статье приведены общие сведения о поддержке перетаскивания в приложениях Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).This topic provides an overview of drag-and-drop support in Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) applications. Перетаскиванием обычно называют метод передачи данных, который реализуется с помощью мыши (или другого указывающего устройства) для выбора одного или нескольких объектов и перетаскивания их в цель перетаскивания в пользовательский интерфейсuser interface (UI).Drag-and-drop commonly refers to a method of data transfer that involves using a mouse (or some other pointing device) to select one or more objects, dragging these objects over some desired drop target in the пользовательский интерфейсuser interface (UI), and dropping them.

Поддержка перетаскивания в WPFDrag-and-Drop Support in WPF

В операциях перетаскивания обычно участвуют две стороны: источник перетаскивания, из которого происходит перетаскиваемый объект, и цель перетаскивания, которая получает перетаскиваемый объект.Drag-and-drop operations typically involve two parties: a drag source from which the dragged object originates and a drop target which receives the dropped object. Источник перетаскивания и цель перетаскивания могут быть элементами пользовательского интерфейса в одном приложении или в разных приложениях.The drag source and drop target may be UI elements in the same application or a different application.

Можно перетаскивать совершенно произвольные типы и количества объектов.The type and number of objects that can be manipulated with drag-and-drop is completely arbitrary. Например, в качестве наиболее распространенных объектов перетаскивания можно назвать файлы, папки, выбранное содержимое.For example, files, folders, and selections of content are some of the more common objects manipulated through drag-and-drop operations.

Конкретные действия, выполняемые во время операции перетаскивания, зависят от приложения и часто определяются контекстом.The particular actions performed during a drag-and-drop operation are application specific, and often determined by context. Например, перетаскивание выбранных файлов из одной папки в другую на одном устройстве хранения перемещает файлы по умолчанию, тогда как при перетаскивании файлов из общего ресурса UNC в локальную папку файлы копируются по умолчанию.For example, dragging a selection of files from one folder to another on the same storage device moves the files by default, whereas dragging files from a Universal Naming Convention (UNC) share to a local folder copies the files by default.

В средствах перетаскивания, предоставляемых WPFWPF, предусмотрена высокая гибкость и возможность настройки с целью поддержки различных сценариев перетаскивания.The drag-and-drop facilities provided by WPFWPF are designed to be highly flexible and customizable to support a wide variety of drag-and-drop scenarios. Перетаскивание поддерживает управление объектами в рамках одного приложения или в разных приложениях.Drag-and-drop supports manipulating objects within a single application, or between different applications. WPFWPFТакже полностью поддерживаются перетаскивание между приложениями и другими приложениями Windows.Dragging-and-dropping between WPFWPF applications and other Windows applications is also fully supported.

В WPFWPF любые элементы UIElement или ContentElement могут участвовать в операциях перетаскивания.In WPFWPF, any UIElement or ContentElement can participate in drag-and-drop. События и методы, необходимые для операций перетаскивания, определяются в классе DragDrop.The events and methods required for drag-and-drop operations are defined in the DragDrop class. Классы UIElement и ContentElement содержат псевдонимы для вложенных событий DragDrop, чтобы эти события отображались в списке членов класса, когда UIElement или ContentElement наследуется как базовый элемент.The UIElement and ContentElement classes contain aliases for the DragDrop attached events so that the events appear in the class members list when a UIElement or ContentElement is inherited as a base element. Обработчики событий, связанные с этими событиями, присоединяются к основному вложенному событию DragDrop и получают один и тот же экземпляр данных события.Event handlers that are attached to these events are attached to the underlying DragDrop attached event and receive the same event data instance. Дополнительные сведения см. в описании события UIElement.Drop.For more information, see the UIElement.Drop event.

Важно!

Перетаскивание OLE не работает в зоне Интернета.OLE drag-and-drop does not work while in the Internet zone.

Передача данныхData Transfer

Перетаскивание является частью более общей сферы передачи данных.Drag-and-drop is part of the more general area of data transfer. Передача данных включает операции перетаскивания и операции копирования и вставки.Data transfer includes drag-and-drop and copy-and-paste operations. Операция перетаскивания аналогична операции копирования и вставки или вырезания и вставки, которая используется для передачи данных из одного объекта или приложения в другое с использованием буфера обмена.A drag-and-drop operation is analogous to a copy-and-paste or cut-and-paste operation that is used to transfer data from one object or application to another by using the system clipboard. В обоих типах операций требуется:Both types of operations require:

  • исходный объект, предоставляющий данные;A source object that provides the data.

  • способ временного хранения передаваемых данных;A way to temporarily store the transferred data.

  • целевой объект, который получает данные.A target object that receives the data.

В операции копирования и вставки для временного хранения передаваемых данных используется системный буфер обмена; в операции перетаскивания для хранения данных используется DataObject.In a copy-and-paste operation, the system clipboard is used to temporarily store the transferred data; in a drag-and-drop operation, a DataObject is used to store the data. Концептуально объект данных состоит из одной или нескольких пар Object, содержащих фактические данные и соответствующий идентификатор формата данных.Conceptually, a data object consists of one or more pairs of an Object that contains the actual data, and a corresponding data format identifier.

Источник перетаскивания инициирует операцию перетаскивания путем вызова статического метода DragDrop.DoDragDrop и передачи в него передаваемых данных.The drag source initiates a drag-and-drop operation by calling the static DragDrop.DoDragDrop method and passing the transferred data to it. Метод DoDragDrop будет автоматически включать данные в DataObject при необходимости.The DoDragDrop method will automatically wrap the data in a DataObject if necessary. Для большего контроля над форматом данных можно включать данные в DataObject перед их передачей в метод DoDragDrop.For greater control over the data format, you can wrap the data in a DataObject before passing it to the DoDragDrop method. Цель перетаскивания отвечает за извлечение данных из DataObject.The drop target is responsible for extracting the data from the DataObject. Дополнительные сведения о работе с объектами данных см. в разделе Данные и объекты данных.For more information about working with data objects, see Data and Data Objects.

Исходный и целевой объекты операции перетаскивания являются элементами пользовательского интерфейса; однако данные, которые в действительности передаются, обычно не имеют визуального представления.The source and target of a drag-and-drop operation are UI elements; however, the data that is actually being transferred typically does not have a visual representation. Вы можете написать код для визуального представления перетаскиваемых данных, например такого, которое происходит при перетаскивании файлов в проводнике.You can write code to provide a visual representation of the data that is dragged, such as occurs when dragging files in Windows Explorer. По умолчанию взаимодействие предоставляется пользователю путем изменения курсора для представления воздействия, которое операция перетаскивания оказывает на данные: например, перемещаются данные или копируются.By default, feedback is provided to the user by changing the cursor to represent the effect that the drag-and-drop operation will have on the data, such as whether the data will be moved or copied.

Эффекты перетаскиванияDrag-and-Drop Effects

Операции перетаскивания могут по-разному воздействовать на передаваемые данные.Drag-and-drop operations can have different effects on the transferred data. Например, данные могут копироваться или перемещаться.For example, you can copy the data or you can move the data. WPFWPF задает перечисление DragDropEffects, которое можно использовать для указания эффекта операции перетаскивания.defines a DragDropEffects enumeration that you can use to specify the effect of a drag-and-drop operation. В источнике перетаскивания можно указать эффекты, которые он разрешает, в методе DoDragDrop.In the drag source, you can specify the effects that the source will allow in the DoDragDrop method. В цели перетаскивания можно определить ожидаемый эффект в свойстве Effects класса DragEventArgs.In the drop target, you can specify the effect that the target intends in the Effects property of the DragEventArgs class. Если в цели перетаскивания ожидаемый эффект задан в событии DragOver, то информация передается обратно в источник перетаскивания в событии GiveFeedback.When the drop target specifies its intended effect in the DragOver event, that information is passed back to the drag source in the GiveFeedback event. Источник перетаскивания использует эти сведения для информирования пользователей, какое воздействие на данные ожидает цель перетаскивания.The drag source uses this information to inform the user what effect the drop target intends to have on the data. Когда данные вставляются, цель перетаскивания указывает фактический эффект в событии Drop.When the data is dropped, the drop target specifies its actual effect in the Drop event. Эти сведения передаются обратно в источник перетаскивания в качестве возвращаемого значения метода DoDragDrop.That information is passed back to the drag source as the return value of the DoDragDrop method. Если цель перетаскивания возвращает эффект, которого нет в списке allowedEffects источников перетаскивания, операция перетаскивания отменяется без фактической передачи данных.If the drop target returns an effect that is not in the drag sources list of allowedEffects, the drag-and-drop operation is cancelled without any data transfer occurring.

Важно помнить, что в WPFWPF значения DragDropEffects используются только для обеспечения взаимодействия между источником перетаскивания и целью перетаскивания относительно эффектов операции перетаскивания.It is important to remember that in WPFWPF, the DragDropEffects values are only used to provide communication between the drag source and the drop target regarding the effects of the drag-and-drop operation. Фактический эффект операции перетаскивания зависит от соответствующего кода, написанного вами в приложении.The actual effect of the drag-and-drop operation depends on you to write the appropriate code in your application.

Например, цель перетаскивания может указывать, что в результате перетаскивания в него данных должно происходить перемещение данных.For example, the drop target might specify that the effect of dropping data on it is to move the data. Однако для перемещения данных они должны добавляться в целевой элемент и удаляться из исходного элемента.However, to move the data, it must be both added to the target element and removed from the source element. Исходный элемент может указывать, что он разрешает перемещение данных, но если вы не предоставите код для удаления данных из исходного элемента, данные в итоге будут копироваться, а не перемещаться.The source element might indicate that it allows moving the data, but if you do not provide the code to remove the data from the source element, the end result will be that the data is copied, and not moved.

События перетаскиванияDrag-and-Drop Events

Операции перетаскивания поддерживают модель управления событиями.Drag-and-drop operations support an event driven model. Источник и цель перетаскивания используют стандартный набор событий для обработки операций перетаскивания.Both the drag source and the drop target use a standard set of events to handle drag-and-drop operations. В следующих таблицах приведены стандартные события перетаскивания.The following tables summarize the standard drag-and-drop events. Это вложенные события в классе DragDrop.These are attached events on the DragDrop class. Дополнительные сведения о вложенных событиях см. в разделе Общие сведения о вложенных событиях.For more information about attached events, see Attached Events Overview.

События источника перетаскиванияDrag Source Events

СобытиеEvent ИтогиSummary
GiveFeedback Это событие возникает постоянно во время операции перетаскивания и позволяет источнику перетаскивания предоставлять пользователю сведения о взаимодействии.This event occurs continuously during a drag-and-drop operation, and enables the drop source to give feedback information to the user. Взаимодействие обычно демонстрируется путем изменения вида курсора мыши, чтобы указать разрешенные целью перетаскивания эффекты операции перетаскивания.This feedback is commonly given by changing the appearance of the mouse pointer to indicate the effects allowed by the drop target. Это событие восходящей маршрутизации.This is a bubbling event.
QueryContinueDrag Это событие возникает при изменении состояния клавиши клавиатуры или кнопки мыши во время операции перетаскивания и позволяет источнику перетаскивания отменить операцию перетаскивания в зависимости от состояния клавиши или кнопки.This event occurs when there is a change in the keyboard or mouse button states during a drag-and-drop operation, and enables the drop source to cancel the drag-and-drop operation depending on the key/button states. Это событие восходящей маршрутизации.This is a bubbling event.
PreviewGiveFeedback Это версия нисходящей маршрутизации события GiveFeedback.Tunneling version of GiveFeedback.
PreviewQueryContinueDrag Это версия нисходящей маршрутизации события QueryContinueDrag.Tunneling version of QueryContinueDrag.

События цели перетаскиванияDrop Target Events

СобытиеEvent ИтогиSummary
DragEnter Это событие происходит, когда объект перетаскивается в границы цели перетаскивания.This event occurs when an object is dragged into the drop target's boundary. Это событие восходящей маршрутизации.This is a bubbling event.
DragLeave Это событие происходит, когда объект перетаскивается за пределы цели перетаскивания.This event occurs when an object is dragged out of the drop target's boundary. Это событие восходящей маршрутизации.This is a bubbling event.
DragOver Это событие происходит постоянно, когда объект перетаскивается (перемещается) в границы цели перетаскивания.This event occurs continuously while an object is dragged (moved) within the drop target's boundary. Это событие восходящей маршрутизации.This is a bubbling event.
Drop Это событие происходит, когда объект вставляется в цель перетаскивания.This event occurs when an object is dropped on the drop target. Это событие восходящей маршрутизации.This is a bubbling event.
PreviewDragEnter Это версия нисходящей маршрутизации события DragEnter.Tunneling version of DragEnter.
PreviewDragLeave Это версия нисходящей маршрутизации события DragLeave.Tunneling version of DragLeave.
PreviewDragOver Это версия нисходящей маршрутизации события DragOver.Tunneling version of DragOver.
PreviewDrop Это версия нисходящей маршрутизации события Drop.Tunneling version of Drop.

Для обработки событий перетаскивания для экземпляров объекта добавьте обработчики событий, перечисленных в таблицах выше.To handle drag-and-drop events for instances of an object, add handlers for the events listed in the preceding tables. Для обработки событий перетаскивания на уровне класса переопределите соответствующие виртуальные методы On*Event и On*PreviewEvent.To handle drag-and-drop events at the class level, override the corresponding virtual On*Event and On*PreviewEvent methods. Дополнительные сведения см. в разделе Маркировка перенаправленных событий как обработанных и обработка классов.For more information, see Class Handling of Routed Events by Control Base Classes.

Реализация перетаскиванияImplementing Drag-and-Drop

Элемент пользовательского интерфейса может быть источником перетаскивания, целью перетаскивания или и тем, и другим.A UI element can be a drag source, a drop target, or both. Чтобы реализовать базовое перетаскивание, необходимо написать код для инициирования операции перетаскивания и обработки перетаскиваемых данных.To implement basic drag-and-drop, you write code to initiate the drag-and-drop operation and to process the dropped data. Вы можете улучшить взаимодействие перетаскивания путем обработки дополнительных событий перетаскивания.You can enhance the drag-and-drop experience by handling optional drag-and-drop events.

Для реализации базового перетаскивания вы будете выполнять следующие задачи.To implement basic drag-and-drop, you will complete the following tasks:

  • Определение элемента, который будет источником перетаскивания.Identify the element that will be a drag source. Источник перетаскивания может быть UIElement или ContentElement.A drag source can be a UIElement or a ContentElement.

  • Создание обработчика событий в источнике перетаскивания, который будет инициировать операцию перетаскивания.Create an event handler on the drag source that will initiate the drag-and-drop operation. Это событие обычно является событием MouseMove.The event is typically the MouseMove event.

  • Вызов метода DoDragDrop в обработчике событий источника перетаскивания для инициации операции перетаскивания.In the drag source event handler, call the DoDragDrop method to initiate the drag-and-drop operation. Указание источника перетаскивания, передаваемых данных и разрешенные эффекты в вызове метода DoDragDrop.In the DoDragDrop call, specify the drag source, the data to be transferred, and the allowed effects.

  • Определение элемента, который будет целью перетаскивания.Identify the element that will be a drop target. Целью перетаскивания может быть UIElement или ContentElement.A drop target can be UIElement or a ContentElement.

  • В цели перетаскивания установите свойство AllowDrop в значение true.On the drop target, set the AllowDrop property to true.

  • В цели перетаскивания создайте обработчик событий Drop для обработки перетаскиваемых данных.In the drop target, create a Drop event handler to process the dropped data.

  • В обработчике событий Drop извлеките данные из DragEventArgs с помощью методов GetDataPresent и GetData.In the Drop event handler, extract the data from the DragEventArgs by using the GetDataPresent and GetData methods.

  • В обработчике событий Drop используйте эти данные для выполнения требуемой операции перетаскивания.In the Drop event handler, use the data to perform the desired drag-and-drop operation.

Вы можете улучшить реализацию перетаскивания путем создания пользовательского объекта DataObject и обработки дополнительных событий источника и цели перетаскивания, как показано в следующих задачах.You can enhance your drag-and-drop implementation by creating a custom DataObject and by handling optional drag source and drop target events, as shown in the following tasks:

  • Чтобы передать пользовательские данные или несколько элементов данных, создайте объект DataObject для передачи в метод DoDragDrop.To transfer custom data or multiple data items, create a DataObject to pass to the DoDragDrop method.

  • Для выполнения дополнительных действий в процессе перетаскивания обработайте события DragEnter, DragOver и DragLeave в цели перетаскивания.To perform additional actions during a drag, handle the DragEnter, DragOver, and DragLeave events on the drop target.

  • Чтобы изменить вид курсора мыши, обработайте событие GiveFeedback в источнике перетаскивания.To change the appearance of the mouse pointer, handle the GiveFeedback event on the drag source.

  • Для изменения способа отмены операции перетаскивания обработайте событие QueryContinueDrag в источнике перетаскивания.To change how the drag-and-drop operation is canceled, handle the QueryContinueDrag event on the drag source.

Пример перетаскиванияDrag-and-Drop Example

В этом разделе описывается реализация перетаскивания для элемента Ellipse.This section describes how to implement drag-and-drop for an Ellipse element. Элемент Ellipse является как источником, так и целью перетаскивания.The Ellipse is both a drag source and a drop target. Передаваемые данные — это строковое представление свойства Fill эллипса.The transferred data is the string representation of the ellipse’s Fill property. В следующем XAML показан элемент Ellipse и связанные с перетаскиванием события, которые он обрабатывает.The following XAML shows the Ellipse element and the drag-and-drop related events that it handles. Полное описание действий по реализации перетаскивания см. в разделе Пошаговое руководство. Включение перетаскивания для пользовательского элемента управления.For complete steps on how to implement drag-and-drop, see Walkthrough: Enabling Drag and Drop on a User Control.

<Ellipse Height="50" Width="50" Fill="Green"
     MouseMove="ellipse_MouseMove"
     GiveFeedback="ellipse_GiveFeedback"
     AllowDrop="True"
     DragEnter="ellipse_DragEnter" DragLeave="ellipse_DragLeave"
     DragOver="ellipse_DragOver" Drop="ellipse_Drop" />

Включение элемента в качестве источника перетаскиванияEnabling an Element to be a Drag Source

Объект, являющийся источником перетаскивания, отвечает за:An object that is a drag source is responsible for:

  • определение момента начала перетаскивания;Identifying when a drag occurs.

  • инициализацию операции перетаскивания;Initiating the drag-and-drop operation.

  • определение передаваемых данных;Identifying the data to be transferred.

  • указание разрешенного воздействия операции перетаскивания на передаваемые данные.Specifying the effects that the drag-and-drop operation is allowed to have on the transferred data.

Источник перетаскивания может также предоставить пользователю сведения о разрешенных действиях (перемещение, копирование или отсутствие действий) и может отменять операцию перетаскивания на основании дополнительного пользовательского ввода, например нажатия клавиши ESC во время перетаскивания.The drag source may also give feedback to the user regarding the allowed actions (move, copy, none), and can cancel the drag-and-drop operation based on additional user input, such as pressing the ESC key during the drag.

Ваше приложение должно определить, когда происходит перетаскивание, а затем инициировать операцию перетаскивания путем вызова метода DoDragDrop.It is the responsibility of your application to determine when a drag occurs, and then initiate the drag-and-drop operation by calling the DoDragDrop method. Обычно это происходит, когда возникает событие MouseMove в перетаскиваемом элементе при нажатой клавише мыши.Typically, this is when a MouseMove event occurs over the element to be dragged while a mouse button is pressed. В следующем примере показано, как инициировать операцию перетаскивания в обработчике событий MouseMove элемента Ellipse, чтобы сделать его источником перетаскивания.The following example shows how to initiate a drag-and-drop operation from the MouseMove event handler of an Ellipse element to make it a drag source. Передаваемые данные — это строковое представление свойства Fill эллипса.The transferred data is the string representation of the ellipse’s Fill property.

private void ellipse_MouseMove(object sender, MouseEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null && e.LeftButton == MouseButtonState.Pressed)
    {
        DragDrop.DoDragDrop( ellipse,
                             ellipse.Fill.ToString(),
                             DragDropEffects.Copy);
    }
}
Private Sub Ellipse_MouseMove(ByVal sender As System.Object, ByVal e As System.Windows.Input.MouseEventArgs)
    Dim ellipse = TryCast(sender, Ellipse)
    If ellipse IsNot Nothing AndAlso e.LeftButton = MouseButtonState.Pressed Then
        DragDrop.DoDragDrop(ellipse, ellipse.Fill.ToString(), DragDropEffects.Copy)
    End If
End Sub

В обработчике событий MouseMove вызовите метод DoDragDrop для инициации операции перетаскивания.Inside of the MouseMove event handler, call the DoDragDrop method to initiate the drag-and-drop operation. Метод DoDragDrop принимает три следующих параметра.The DoDragDrop method takes three parameters:

  • dragSource — ссылка на объект зависимости, который является источником передаваемых данных; обычно это источник события MouseMove.dragSource – A reference to the dependency object that is the source of the transferred data; this is typically the source of the MouseMove event.

  • data — объект, содержащий передаваемые данные, заключенные в объект DataObject.data - An object that contains the transferred data, wrapped in a DataObject.

  • allowedEffects — одно из значений перечисления DragDropEffects, которое определяет разрешенные эффекты операции перетаскивания.allowedEffects - One of the DragDropEffects enumeration values that specifies the permitted effects of the drag-and-drop operation.

В параметр data может быть передан любой сериализуемый объект.Any serializable object can be passed in the data parameter. Если данные еще не заключены в объект DataObject, они автоматически заключаются в новый объект DataObject.If the data is not already wrapped in a DataObject, it will automatically be wrapped in a new DataObject. Для передачи нескольких элементов данных вы должны создать объект DataObject самостоятельно и передать его в метод DoDragDrop.To pass multiple data items, you must create the DataObject yourself, and pass it to the DoDragDrop method. Дополнительные сведения см. в разделе Данные и объекты данных.For more information, see Data and Data Objects.

Параметр allowedEffects используется для указания, какие действия с передаваемыми данными источник перетаскивания будет разрешать цели перетаскивания.The allowedEffects parameter is used to specify what the drag source will allow the drop target to do with the transferred data. Обычные значения для источника перетаскивания — Copy, Move и All.The common values for a drag source are Copy, Move, and All.

Примечание

Цель перетаскивания также может указывать ожидаемые эффекты перетаскивания данных.The drop target is also able to specify what effects it intends in response to the dropped data. Например, если цель перетаскивания не распознает тип вставляемых данных, то она может отклонить эти данные, задав None в качестве разрешенных эффектов.For example, if the drop target does not recognize the data type to be dropped, it can refuse the data by setting its allowed effects to None. Обычно она делает это в своем обработчике событий DragOver.It typically does this in its DragOver event handler.

Источник перетаскивания может также обрабатывать события GiveFeedback и QueryContinueDrag.A drag source can optionally handle the GiveFeedback and QueryContinueDrag events. Эти события имеют обработчики по умолчанию, которые используются, если события не помечены как обработанные.These events have default handlers that are used unless you mark the events as handled. Обычно эти события игнорируются, если нет особой необходимости изменения их поведения по умолчанию.You will typically ignore these events unless you have a specific need to change their default behavior.

Событие GiveFeedback возникает постоянно, пока выполняется перетаскивание источника перетаскивания.The GiveFeedback event is raised continuously while the drag source is being dragged. Обработчик по умолчанию для этого события проверяет, находится ли источник перетаскивания над допустимым конечным расположением сброса.The default handler for this event checks whether the drag source is over a valid drop target. Если это так, то он проверяет разрешенные эффекты цели перетаскивания.If it is, it checks the allowed effects of the drop target. Затем он предоставляет конечному пользователю отзыв относительно разрешенных эффектов перетаскивания.It then gives feedback to the end user regarding the allowed drop effects. Обычно это выполняется путем изменения курсора мыши, чтобы указать запрет перетаскивания, копирование или перемещение.This is typically done by changing the mouse cursor to a no-drop, copy, or move cursor. Это событие следует обрабатывать, только если необходимо использовать пользовательские курсоры для предоставления отзыва пользователю.You should only handle this event if you need to use custom cursors to provide feedback to the user. Если вы обрабатываете это событие, не забудьте помечать его как обработанное, чтобы обработчик по умолчанию не переопределил ваш обработчик.If you handle this event, be sure to mark it as handled so that the default handler does not override your handler.

Событие QueryContinueDrag возникает постоянно, пока выполняется перетаскивание источника перетаскивания.The QueryContinueDrag event is raised continuously while the drag source is being dragged. Можно обработать это событие, чтобы определить, какое действие завершает операцию перетаскивания, на основе состояния клавиш ESC, SHIFT, CTRL и ALT, а также состояния кнопок мыши.You can handle this event to determine what action ends the drag-and-drop operation based on the state of the ESC, SHIFT, CTRL, and ALT keys, as well as the state of the mouse buttons. Обработчик по умолчанию для этого события отменяет операцию перетаскивания при нажатии клавиши ESC и сбрасывает данные при отпускании кнопки мыши.The default handler for this event cancels the drag-and-drop operation if the ESC key is pressed, and drops the data if the mouse button is released.

Внимание!

Эти события возникают постоянно во время операции перетаскивания.These events are raised continuously during the drag-and-drop operation. Поэтому следует избегать ресурсоемких задач в обработчиках событий.Therefore, you should avoid resource-intensive tasks in the event handlers. Например, используйте кэшированный курсор вместо создания нового курсора при каждом возникновении события GiveFeedback.For example, use a cached cursor instead of creating a new cursor each time the GiveFeedback event is raised.

Включение элемента в качестве цели перетаскиванияEnabling an Element to be a Drop Target

Объект, являющийся целью перетаскивания, отвечает за:An object that is a drop target is responsible for:

  • указание, что он является допустимой целью перетаскивания;Specifying that it is a valid drop target.

  • реакцию на источник перетаскивания, когда он перетаскивается над целевым объектом;Responding to the drag source when it drags over the target.

  • проверку, что передаваемые данные находятся в формате, который он может получить;Checking that the transferred data is in a format that it can receive.

  • обработку вставляемых данных.Processing the dropped data.

Чтобы указать, что элемент является целью перетаскивания, его свойство AllowDrop устанавливается в значение true.To specify that an element is a drop target, you set its AllowDrop property to true. Затем в этом элементе будут возникать события цели перетаскивания, чтобы их можно было обработать.The drop target events will then be raised on the element so that you can handle them. Во время операции перетаскивания в цели перетаскивания возникает следующая последовательность событий:During a drag-and-drop operation, the following sequence of events occurs on the drop target:

  1. DragEnter

  2. DragOver

  3. DragLeave или DropDragLeave or Drop

Событие DragEnter возникает, когда данные перетаскиваются в границы цели перетаскивания.The DragEnter event occurs when the data is dragged into the drop target's boundary. Обычно вы обрабатываете это событие, чтобы обеспечить предварительный просмотр эффектов операции перетаскивания, если это требуется для вашего приложения.You typically handle this event to provide a preview of the effects of the drag-and-drop operation, if appropriate for your application. Не устанавливайте свойство DragEventArgs.Effects в событии DragEnter, так как оно будет переопределено в событии DragOver.Do not set the DragEventArgs.Effects property in the DragEnter event, as it will be overwritten in the DragOver event.

В следующем примере показан обработчик событий DragEnter для элемента Ellipse.The following example shows the DragEnter event handler for an Ellipse element. Этот код выполняет предварительный просмотр эффектов операции перетаскивания путем сохранения текущей кисти Fill.This code previews the effects of the drag-and-drop operation by saving the current Fill brush. Затем он использует метод GetDataPresent для проверки, содержит ли объект DataObject, перетаскиваемый над эллипсом, строковые данные, которые можно преобразовать в Brush.It then uses the GetDataPresent method to check whether the DataObject being dragged over the ellipse contains string data that can be converted to a Brush. Если да, то данные извлекаются с помощью метода GetDataIf so, the data is extracted using the GetData method. Затем они преобразуются в Brush и применяются к эллипсу.It is then converted to a Brush and applied to the ellipse. Это изменение отменяется в обработчике событий DragLeave.The change is reverted in the DragLeave event handler. Если данные невозможно преобразовать в Brush, никакие действия не выполняются.If the data cannot be converted to a Brush, no action is performed.

private Brush _previousFill = null;
private void ellipse_DragEnter(object sender, DragEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null)
    {
        // Save the current Fill brush so that you can revert back to this value in DragLeave.
        _previousFill = ellipse.Fill;

        // If the DataObject contains string data, extract it.
        if (e.Data.GetDataPresent(DataFormats.StringFormat))
        {
            string dataString = (string)e.Data.GetData(DataFormats.StringFormat);

            // If the string can be converted into a Brush, convert it.
            BrushConverter converter = new BrushConverter();
            if (converter.IsValid(dataString))
            {
                Brush newFill = (Brush)converter.ConvertFromString(dataString);
                ellipse.Fill = newFill;
            }
        }
    }
}
Private _previousFill As Brush = Nothing
Private Sub Ellipse_DragEnter(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs)
    Dim ellipse = TryCast(sender, Ellipse)
    If ellipse IsNot Nothing Then
        ' Save the current Fill brush so that you can revert back to this value in DragLeave.
        _previousFill = ellipse.Fill

        ' If the DataObject contains string data, extract it.
        If e.Data.GetDataPresent(DataFormats.StringFormat) Then
            Dim dataString = e.Data.GetData(DataFormats.StringFormat)

            ' If the string can be converted into a Brush, convert it.
            Dim converter As New BrushConverter()
            If converter.IsValid(dataString) Then
                Dim newFill As Brush = CType(converter.ConvertFromString(dataString), Brush)
                ellipse.Fill = newFill
            End If
        End If
    End If
End Sub

Событие DragOver постоянно возникает при перетаскивании данных на цель перетаскивания.The DragOver event occurs continuously while the data is dragged over the drop target. Это событие является спаренным с событием GiveFeedback в источнике перетаскивания.This event is paired with the GiveFeedback event on the drag source. В обработчике событий DragOver, как правило, используются методы GetDataPresent и GetData для проверки, имеют ли передаваемые данные формат, который может обработать цель перетаскивания.In the DragOver event handler, you typically use the GetDataPresent and GetData methods to check whether the transferred data is in a format that the drop target can process. Можно также проверить, нажаты ли клавиши-модификаторы, которые обычно указывают, какую операцию предполагает выполнять пользователь — перемещения или копирования.You can also check whether any modifier keys are pressed, which will typically indicate whether the user intends a move or copy action. После выполнения этих проверок вы устанавливаете свойство DragEventArgs.Effects, чтобы уведомить источник перетаскивания о том, какой эффект окажет сброс данных.After these checks are performed, you set the DragEventArgs.Effects property to notify the drag source what effect dropping the data will have. Источник перетаскивания получает эти сведения в аргументах события GiveFeedback и может задать соответствующий курсор, чтобы обеспечить отзыв для пользователя.The drag source receives this information in the GiveFeedback event args, and can set an appropriate cursor to give feedback to the user.

В следующем примере показан обработчик событий DragOver для элемента Ellipse.The following example shows the DragOver event handler for an Ellipse element. В этом коде проверяется, содержит ли объект DataObject, перетаскиваемый над эллипсом, строковые данные, которые можно преобразовать в Brush.This code checks to see if the DataObject being dragged over the ellipse contains string data that can be converted to a Brush. Если содержит, то код устанавливает для свойства DragEventArgs.Effects значение Copy.If so, it sets the DragEventArgs.Effects property to Copy. Это указывает источнику перетаскивания, что данные можно скопировать в эллипс.This indicates to the drag source that the data can be copied to the ellipse. Если данные невозможно преобразовать в Brush, для свойства DragEventArgs.Effects устанавливается значение None.If the data cannot be converted to a Brush, the DragEventArgs.Effects property is set to None. Это указывает источнику перетаскивания, что эллипс не является допустимым конечным расположением сброса для данных.This indicates to the drag source that the ellipse is not a valid drop target for the data.

private void ellipse_DragOver(object sender, DragEventArgs e)
{
    e.Effects = DragDropEffects.None;

    // If the DataObject contains string data, extract it.
    if (e.Data.GetDataPresent(DataFormats.StringFormat))
    {
        string dataString = (string)e.Data.GetData(DataFormats.StringFormat);

        // If the string can be converted into a Brush, allow copying.
        BrushConverter converter = new BrushConverter();
        if (converter.IsValid(dataString))
        {
            e.Effects = DragDropEffects.Copy | DragDropEffects.Move;
        }
    }
}
Private Sub Ellipse_DragOver(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs)
    e.Effects = DragDropEffects.None

    ' If the DataObject contains string data, extract it.
    If e.Data.GetDataPresent(DataFormats.StringFormat) Then
        Dim dataString = e.Data.GetData(DataFormats.StringFormat)

        ' If the string can be converted into a Brush, convert it.
        Dim converter As New BrushConverter()
        If converter.IsValid(dataString) Then
            e.Effects = DragDropEffects.Copy Or DragDropEffects.Move
        End If
    End If
End Sub

Событие DragLeave возникает, когда данные перетаскиваются за границу целевого объекта без сбрасывания.The DragLeave event occurs when the data is dragged out of the target's boundary without being dropped. Обработка этого события позволяет отменить любые действия, которые были выполнены в обработчике событий DragEnter.You handle this event to undo anything that you did in the DragEnter event handler.

В следующем примере показан обработчик событий DragLeave для элемента Ellipse.The following example shows the DragLeave event handler for an Ellipse element. Этот код отменяет предварительный просмотр, выполненный в обработчике событий DragEnter, путем применения сохраненного объекта Brush к эллипсу.This code undoes the preview performed in the DragEnter event handler by applying the saved Brush to the ellipse.

private void ellipse_DragLeave(object sender, DragEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null)
    {
        ellipse.Fill = _previousFill;
    }
}
Private Sub Ellipse_DragLeave(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs)
    Dim ellipse = TryCast(sender, Ellipse)
    If ellipse IsNot Nothing Then
        ellipse.Fill = _previousFill
    End If
End Sub

Событие Drop возникает при сбросе данных в цель перетаскивания; по умолчанию это происходит при отпускании кнопки мыши.The Drop event occurs when the data is dropped over the drop target; by default, this happens when the mouse button is released. В обработчике событий Drop вы используете метод GetData для извлечения передаваемых данных из объекта DataObject и выполнения обработки данных, необходимой для вашего приложения.In the Drop event handler, you use the GetData method to extract the transferred data from the DataObject and perform any data processing that your application requires. Событие Drop завершает операцию перетаскивания.The Drop event ends the drag-and-drop operation.

В следующем примере показан обработчик событий Drop для элемента Ellipse.The following example shows the Drop event handler for an Ellipse element. Этот код применяет эффекты операции перетаскивания. Он аналогичен коду в обработчике событий DragEnter.This code applies the effects of the drag-and-drop operation, and is similar to the code in the DragEnter event handler. Он проверяет, содержит ли объект DataObject, перетаскиваемый над эллипсом, строковые данные, которые можно преобразовать в Brush.It checks to see if the DataObject being dragged over the ellipse contains string data that can be converted to a Brush. Если это так, то к эллипсу применяется объект Brush.If so, the Brush is applied to the ellipse. Если данные невозможно преобразовать в Brush, никакие действия не выполняются.If the data cannot be converted to a Brush, no action is performed.

private void ellipse_Drop(object sender, DragEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null)
    {
        // If the DataObject contains string data, extract it.
        if (e.Data.GetDataPresent(DataFormats.StringFormat))
        {
            string dataString = (string)e.Data.GetData(DataFormats.StringFormat);

            // If the string can be converted into a Brush,
            // convert it and apply it to the ellipse.
            BrushConverter converter = new BrushConverter();
            if (converter.IsValid(dataString))
            {
                Brush newFill = (Brush)converter.ConvertFromString(dataString);
                ellipse.Fill = newFill;
            }
        }
    }
}
Private Sub Ellipse_Drop(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs)
    Dim ellipse = TryCast(sender, Ellipse)
    If ellipse IsNot Nothing Then

        ' If the DataObject contains string data, extract it.
        If e.Data.GetDataPresent(DataFormats.StringFormat) Then
            Dim dataString = e.Data.GetData(DataFormats.StringFormat)

            ' If the string can be converted into a Brush, convert it.
            Dim converter As New BrushConverter()
            If converter.IsValid(dataString) Then
                Dim newFill As Brush = CType(converter.ConvertFromString(dataString), Brush)
                ellipse.Fill = newFill
            End If
        End If
    End If
End Sub

См. также разделSee also