Add support for drag images and drop descriptions

[willibrandon]

Allow drop targets to display the drag image while the cursor is over the target and add support for setting drop descriptions.

Allow drag sources to specify the drag image bitmap.

Resolves #5884.

Proposed changes

• Maintain the current default DropTarget behavior. By default, do not display the drag image and drop description.

• Add a new public enumeration; DropImageType.

namespace System.Windows.Forms
{
    /// <summary>
    /// Specifies the drop description image type.
    /// </summary>
    public enum DropImageType
    {
        /// <summary>
        /// No drop image preference; use the default image.
        /// </summary>
        Invalid = -1,

        /// <summary>
        /// A red bisected circle such as that found on a "no smoking" sign.
        /// </summary>
        None = 0,

        /// <summary>
        /// A plus sign (+) that indicates a copy operation.
        /// </summary>
        Copy = DragDropEffects.Copy,

        /// <summary>
        /// An arrow that indicates a move operation.
        /// </summary>
        Move = DragDropEffects.Move,

        /// <summary>
        /// An arrow that indicates a link.
        /// </summary>
        Link = DragDropEffects.Link,

        /// <summary>
        /// A tag icon that indicates that the metadata will be changed.
        /// </summary>
        Label = 6,

        /// <summary>
        /// A yellow exclamation mark that indicates that a problem has been encountered in the operation.
        /// </summary>
        Warning = 7,

        /// <summary>
        /// Windows 7 and later. Use no drop image.
        /// </summary>
        NoImage = 8
    }
}

• Add 3 new public DragEventArgs properties; DropImageType, Message, and MessageReplacementToken.

namespace System.Windows.Forms
{
  public class DragEventArgs : EventArgs
  {
      /// <summary>
      /// Gets or sets the drop description image type.
      /// </summary>
      public DropImageType DropImageType { get; set; }
  
        /// <summary>
        /// Gets or sets the drop description text such as "Move to %1" when "Documents" is specified in <see cref="MessageReplacementToken"/>.
        /// </summary>
        /// <remarks>
        /// <para>
        /// UI coloring is applied to the text in <see cref="MessageReplacementToken"/> if used by specifying %1 in <see cref="Message"/>.
        /// </para>
        /// </remarks>
        public string? Message { get; set; }
  
        /// <summary>
        /// Gets or sets the drop description text such as "Documents" when %1 is specified in <see cref="Message"/>.
        /// </summary>
        /// <remarks>
        /// <para>
        /// UI coloring is applied to the text in <see cref="MessageReplacementToken"/> if used by specifying %1 in <see cref="Message"/>.
        /// </para>
        /// </remarks>
        public string? MessageReplacementToken { get; set; }

        /// <summary>
        /// Initializes a new instance of the <see cref="DragEventArgs"/> class.
        /// </summary>
        public DragEventArgs(IDataObject? data, int keyState, int x, int y, DragDropEffects allowedEffect, DragDropEffects effect, DropImageType dropImageType, string message, string messageReplacementToken);
  }
}

• During the DragEnter event, if the application specifies a DragEventArgs.DropImageType greater than DropImageType.Invalid, display the drag image and drop description.

• Add 3 new GiveFeedbackEventArgs properties; DragImage, CursorOffset, and UseDefaultDragImage.

namespace System.Windows.Forms
{
  public class GiveFeedbackEventArgs: EventArgs
  {
        /// <summary>
        /// Gets or sets the drag image bitmap.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Note the outer edges of <see cref="DragImage"/> are blended out if the image width or height exceeds 300 pixels.
        /// </para>
        /// </remarks>
        public Bitmap? DragImage { get; set; }

        /// <summary>
        /// Gets or sets the drag image cursor offset.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Specifies the location of the cursor within <see cref="DragImage"/>, which is an offset from the upper-left corner.
        /// </para>
        /// </remarks>
        public Point CursorOffset { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether a layered window drag image is used.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Specify <see langword="true"/> for <see cref="UseDefaultDragImage"/> to use a layered window drag image with a size of 96x96; otherwise
        /// <see langword="false"/>.
        /// </para>
        /// </remarks>
        public bool UseDefaultDragImage { get; set; }

        /// <summary>
        /// Initializes a new instance of the <see cref="GiveFeedbackEventArgs"/> class.
        /// </summary>
        public GiveFeedbackEventArgs(DragDropEffects effect, bool useDefaultCursors, Bitmap? dragImage, Point cursorOffset, bool useDefaultDragImage);
  }
}

• Add 2 new DoDragDrop methods.

namespace System.Windows.Forms
{
    public partial class Control
    {
        /// <summary>
        /// Begins a drag operation. The <paramref name="allowedEffects"/> determine which drag operations can occur. If the drag operation
        /// needs to interop with applications in another process, <paramref name="data"/> should either be a base managed class
        /// (<see cref="string"/>, <see cref="Bitmap"/>, or <see cref="Drawing.Imaging.Metafile"/>) or some <see cref="object"/> that implements
        /// <see cref="Runtime.Serialization.ISerializable"/>. <paramref name="data"/> can also be any <see cref="object"/> that implements
        /// <see cref="IDataObject"/>. <paramref name="dragImage"/> is the bitmap that will be displayed during the  drag operation and
        /// <paramref name="cursorOffset"/> specifies the location of the cursor within <paramref name="dragImage"/>, which is an offset from the
        /// upper-left corner. Specify <see langword="true"/> for <paramref name="useDefaultDragImage"/> to use a layered window drag image with a
        /// size of 96x96; otherwise <see langword="false"/>. Note the outer edges of <paramref name="dragImage"/> are blended out if the image width
        /// or height exceeds 300 pixels.
        /// <remarks>
        /// <para>
        /// Because <see cref="DoDragDrop(object, DragDropEffects, Bitmap, Point, bool)"/> always performs the RGB multiplication step in calculating
        /// the alpha value, you should always pass a <see cref="Bitmap"/> without premultiplied alpha blending. Note that no error will result from
        /// passing a <see cref="Bitmap"/> with premultiplied alpha blending, but this method will multiply it again, doubling the resulting alpha
        /// value.
        /// </para>
        /// </remarks>
        /// </summary>
        /// <returns>
        /// A value from the <see cref="DragDropEffects"/> enumeration that represents the final effect that was performed during the drag-and-drop
        /// operation.
        /// </returns>
        public DragDropEffects DoDragDrop(object data, DragDropEffects allowedEffects, Bitmap dragImage, Point cursorOffset, bool useDefaultDragImage);
    }

    public abstract partial class ToolStripItem
    {
        /// <summary>
        /// Begins a drag operation. The <paramref name="allowedEffects"/> determine which drag operations can occur. If the drag operation
        /// needs to interop with applications in another process, <paramref name="data"/> should either be a base managed class
        /// (<see cref="string"/>, <see cref="Bitmap"/>, or <see cref="Drawing.Imaging.Metafile"/>) or some <see cref="object"/> that implements
        /// <see cref="Runtime.Serialization.ISerializable"/>. <paramref name="data"/> can also be any <see cref="object"/> that implements
        /// <see cref="IDataObject"/>. <paramref name="dragImage"/> is the bitmap that will be displayed during the  drag operation and
        /// <paramref name="cursorOffset"/> specifies the location of the cursor within <paramref name="dragImage"/>, which is an offset from the
        /// upper-left corner. Specify <see langword="true"/> for <paramref name="useDefaultDragImage"/> to use a layered window drag image with a
        /// size of 96x96; otherwise <see langword="false"/>. Note the outer edges of <paramref name="dragImage"/> are blended out if the image width
        /// or height exceeds 300 pixels.
        /// <remarks>
        /// <para>
        /// Because <see cref="DoDragDrop(object, DragDropEffects, Bitmap, Point, bool)"/> always performs the RGB multiplication step in calculating
        /// the alpha value, you should always pass a <see cref="Bitmap"/> without premultiplied alpha blending. Note that no error will result from
        /// passing a <see cref="Bitmap"/> with premultiplied alpha blending, but this method will multiply it again, doubling the resulting alpha
        /// value.
        /// </para>
        /// </remarks>
        /// </summary>
        /// <returns>
        /// A value from the <see cref="DragDropEffects"/> enumeration that represents the final effect that was performed during the drag-and-drop
        /// operation.
        /// </returns>
        public DragDropEffects DoDragDrop(object data, DragDropEffects allowedEffects, Bitmap dragImage, Point cursorOffset, bool useDefaultDragImage);
    }
}

• During the DoDragDrop method or the GiveFeedback event, if the application specifies a DragImage bitmap, set CFSTR_INDRAGLOOP to true and initialize the drag-image manager by calling IDragSourceHelper2.InitializeFromBitmap().

• Load and retrieve the arbitrary private data formats used by the drag-and-drop helpers and manage the storage and release of the related storage mediums using a private DragDropFormat class.

• Add an internal DragDropHelper class to manage the retrieval of the IDragSourceHelper2 and IDropTargetHelper interface pointers and expose the methods necessary to set and display the drag image and drop description.

• Add a drag and drop functional test form to the WinformsControlsTest project with files for testing drag and drop operations.

Customer Impact

• An improved drag-and-drop experience.

Regression?

• No

Risk

• I haven't had to work with pointers or allocate/de-allocate memory in the last 13 years, so the risk seems high.

Video

DropTarget_DragImageDropDescription.mp4

DragSource_DragImageDropDescription.mp4

ToolStrip_DragImageDropDescription.mp4

WinForms_DragImageDropDescription.mp4

Test methodology

• Manually test using WinformsControlsTest as startup project -> Drag and Drop. Click the Open Cats button and drag the cat bitmaps and rich text format file to the picture boxes on the form (see videos).
• Run unit and integration tests.
• TODO: Add unit tests.
• TODO: Add UIIntegration tests.

Accessibility testing

TODO

Test environment(s)

• .NET 7.0.0-preview.1.22076.8

Microsoft Reviewers: Open in CodeFlow

[RussKie]

👍

[willibrandon]

Include the cursor offset.

[dreddy-work]

@weltkante appreciate your feedback as well here. I think this will remove the need to expose interfaces publicly as discussed here: #457.

@willibrandon, We decided to take this forward and will work with you to get this ready for API review board.

[willibrandon]

@willibrandon, We decided to take this forward and will work with you to get this ready for API review board.

I have one last part I'd like to include in this draft before taking it to the API review board and would like a chance to first get some feedback from the team. Specifically, specifying the drag image bitmap itself when calling DoDragDrop().

I'll try to get this last part pushed this evening. The only thing holding me up is I need to implement a function to copy an STGMEDIUM since I've previously been using CopyStgMedium() in Urlmon.lib and I don't think I'm able to use that function here. I should be able to implement it fairly easily using the OleDuplicateData function and will have some time to work on it this evening.

[weltkante]

Thanks for the ping, looks promising, though I'm surprised this approach works considering WinForms doesn't implement SetData on its DataObject. I'll have a closer look at the proposed implementation and API over the next few days.

[willibrandon]

@weltkante - The IDataObject::SetData and IDataObject::GetData changes will be included in my next push, hopefully this evening.

[willibrandon]

@weltkante - I've pushed what I believe is the last major part required for this issue. Some further work needs to be done in order to add in the support for RichTextBox.OleCallback, ToolStripItem, and ToolStripDropTargetManager, but this is the gist of it. I am very interested in hearing what your thoughts are.

[dreddy-work]

I am moving this out of draft. @willibrandon , can you resolve conflict when you get chance. @JeremyKuhne Can you take a final look here.

[JeremyKuhne]

Looks good! Thanks for all of your hard work and patience!

[JeremyKuhne]

Resolved the conflict

[dreddy-work]

@willibrandon, as FYI, this will be merged for the Preview 7 release.

[willibrandon]

I'm seeing an AccessViolationException when drag-and-dropping to the RichTextBox, and the operation fails.

I'm not yet sure if this is related to the work done in this PR, or not.

[dreddy-work]

@willibrandon , can you open a new issue for this and we can track the discussion there to figure out ?

[willibrandon]

Before I forget, thank you for the opportunity to work on this. It has been an incredible learning experience for me and everyone here has been so helpful and welcoming. Early on I was terrified that I wouldn’t be able to figure this one out. While getting the drag images from Explorer to display on WinForms drop targets was trivial, specifying the drag image bitmap itself from a drag source was a much more daunting task for me. When I got it working the first time I almost had a heart attack and started screaming OMG. This has been an awesome experience for me, thank you.

[kant2002]

Congratulation! That’s WinForms team for you 🏅. Also, take care of your heart ;)

[RussKie]

Thank you so much for your efforts and your patience!