UI Automation Support for Drag-and-Drop

Microsoft UI Automation defines two control patterns for supporting drag-and-drop scenarios, the Drag control pattern, and the DropTarget control pattern. You implement the Drag control pattern for an element that can be dragged, and the DropTarget control pattern for an element that can receive a dragged element; that is, a drop target. The two control patterns expose information that an assistive technology can use to help an accessibility user complete a drag-and-drop operation.

• Dragging Styles
  • Source/target Style
  • Source-only Style
• Dragging Multiple Items
• Client Interfaces for Drag-and-Drop

Dragging Styles

When you implement the Drag control pattern for a draggable element, you need to decide whether to implement the source/target dragging style, or the source-only dragging style.

Source/target Style

In the source/target style of drag-and-drop, the dragged element (the "source") and the drop-target element (the "target") are distinct, and each raises a distinct set of events. Here's the life cycle for a drag operation that uses the source/target style:

When the user starts a drag operation:

• The source raises the DragStart (UIA_Drag_DragStartEventId) event.
• The source sets the IDragProvider::IsGrabbed property to TRUE.
• Targets update their DropTargetEffect properties.

When the drag operation enters a target region:

• The target raises the DragEnter (UIA_DropTarget_DragEnterEventId) event.

When the drag operation leaves a target region:

• The target raises the DragLeave (UIA_DropTarget_DragLeaveEventId) event.

When the user releases the dragged item over a non-target:

• The source raises the DragCancel (UIA_Drag_DragCancelEventId) event.
• The source sets the IDragProvider::IsGrabbed property to FALSE.

When the user releases the dragged item over a target:

• The source raises the DragComplete (UIA_Drag_DragCompleteEventId) event.
• The source sets the IDragProvider::IsGrabbed property to FALSE.
• The target sets the IDropTargetProvider::DropTargetEffect property to indicate the effect that occurred.
• The target raises the Dropped (UIA_DropTarget_DroppedEventId) event.

The events from the source and target objects are closely related, but distinct. The data about what is being dragged comes from the source, while the data about "what could happen" and "what did happen" comes from the target.

When a drag operation is in progress, the dragged item can be dragged in and out of target regions any number of times before the operation completes.

Any drop target that needs to update its IDropTargetProvider::DropTargetEffect property on the fly should raise an additional property changed event on that property.

Source-only Style

The source-only dragging style lets a provider avoid implementing drop targets. Not implementing drop targets helps lower the implementation cost, but does not give accessibility client applications any information about the object that received the drop. Here's the life cycle for a drag operation that uses the source-only style:

When the user starts a drag operation:

• The source raises the DragStart (UIA_Drag_DragStartEventId) event.
• The source sets the IDragProvider::IsGrabbed property to TRUE.

When the drag operation enters a target region:

• The source sets the IDragProvider::DropEffect property to the appropriate value.

When the drag operation leaves a target region:

• The source sets the IDragProvider::DropEffect property to the appropriate value.

When the user releases the dragged item over a non-target:

• The source raises the DragCancel (UIA_Drag_DragCancelEventId) event.
• The source sets the IDragProvider::IsGrabbed property to FALSE.

When the user releases the dragged item over a target:

• The source raises the DragComplete (UIA_Drag_DragCompleteEventId) event.
• The source sets the IDragProvider::DropEffect property to indicate the effect that took place when the item was dropped.

Dragging Multiple Items

If a provider implements drag-and-drop operations where the user can drag multiple objects at the same time, the provider uses the source/target or source-only styles as described in the previous section, but with a small difference. When the user begins the drag operation, the provider creates a master source element that represents the full set of items that are being dragged. The master source element raises all events on behalf of the set of dragged items; the items don't raise any events of their own.

When the user starts a drag operation:

• The provider creates the master source element.
• The master source element raises the DragStart (UIA_Drag_DragStartEventId) event.
• The master source element sets the IDragProvider::IsGrabbed property to TRUE.
• The master source element updates the list of grabbed items to include all items being dragged so that the GetGrabbedItems method can retrieve the list.

For that point on, the master source element performs the same role as that of the source element as described in the previous section.

Client Interfaces for Drag-and-Drop

UI Automation client applications use the IUIAutomationDragPattern and IUIAutomationDropTargetPattern interfaces to access drag-and-drop information from UI elements.