Edit

Drag Control Pattern

  • Article

Provides guidelines and conventions for implementing the Drag control pattern by using IDragProvider, including information about properties and methods. The Drag control pattern is used to support draggable controls, or controls with draggable items.

Implementation Guidelines and Conventions

When implementing the Drag control pattern, use these guidelines and conventions:

  • The IDragProvider interface supports two different dragging styles: the source/target style, and the source-only style. You need to choose the style that works best for your drag-and-drop scenarios:
    • Source/target style: Each possible drop target is represented by an element that implements the IDropTargetProvider interface. During a drag operation, Microsoft UI Automation events originate from the element that is being dragged, and from the drop-target elements.
    • Source-only style: Drop targets are not represented by UI Automation elements. During a drag operation, events originate only from the element that is being dragged.
  • IDragProvider is a read-only interface intended for monitoring drag operations. You cannot use it to control a drag operation. You can automate drag operations by sending mouse input to a control.
  • The IDragProvider::IsGrabbed property is required.
  • The IDragProvider::DropEffect and IDragProvider::DropEffects properties are required for a source-only style implementation, and prohibited for a source/target style implementation. In a source/target style implementation, drop-target elements can be queried for their drop effects.
  • The IDragProvider::GrabbedItems property represents the dragging of multiple items. When the user begins the drag operation, you need to create a new UI Automation element to serve as the event source element. This new element fires all events that the source element would have fired in either the source/target or source-only mode, while none of the elements that are actually being dragged fire any events. When the drag operation is complete, destroy the event source element.
  • The element must fire property-changed events for the DropEffect (UIA_DragDropEffectPropertyId) and DropEffects (UIA_DragDropEffectsPropertyId) properties when they change. Property-changed events for the other properties are allowed, but can be inferred from the required DragStart (UIA_Drag_DragStartEventId), DragCancel (UIA_Drag_DragCancelEventId), and DragComplete (UIA_Drag_DragCompleteEventId) events.

Required Members for IDragProvider

The following properties and methods are required for implementing the IDragProvider interface.

Required members Member type Notes
IsGrabbed Property None
DropEffect Property Required for an implementation of the source-only style.
DropEffects Property Required if there is more than one possible drop effect for the grabbed item.
GetGrabbedItems Method Required for a multiple-item drag operation.
UIA_Drag_DragStartEventId Event None
UIA_Drag_DragCancelEventId Event None
UIA_Drag_DragCompleteEventId Event None

 

Control Types and their Supported Control Patterns

DropTarget Control Pattern

UI Automation Control Patterns Overview

UI Automation Tree Overview

UI Automation Support for Drag-and-Drop