Used to indicate the expected drop location when an item is dragged to a new position in a ListView control. This functionality is available only on Windows XP and later.
Assembly: System.Windows.Forms (in System.Windows.Forms.dll)
Thetype exposes the following members.
|AppearsAfterItem||Gets or sets a value indicating whether the insertion mark appears to the right of the item with the index specified by the Index property.|
|Bounds||Gets the bounding rectangle of the insertion mark.|
|Color||Gets or sets the color of the insertion mark.|
|Index||Gets or sets the index of the item next to which the insertion mark appears.|
|Equals(Object)||Determines whether the specified object is equal to the current object. (Inherited from Object.)|
|GetHashCode||Serves as the default hash function. (Inherited from Object.)|
|GetType||Gets the Type of the current instance. (Inherited from Object.)|
|NearestIndex||Retrieves the index of the item closest to the specified point.|
|ToString||Returns a string that represents the current object. (Inherited from Object.)|
You can retrieve a from the InsertionMark property of a ListView control and use it to visually indicate the expected drop location in a drag-and-drop operation when an item is dragged to a new position.
This feature works only when the ListView.AutoArrange property is set to true and when the ListView control does not sort the items automatically. To prevent automatic sorting, the ListView.Sorting property must be set to SortOrder.None and the ListView.View property must be set to View.LargeIcon, View.SmallIcon, or View.Tile. Additionally, the insertion mark feature cannot be used with the ListView grouping feature because the grouping feature orders the items by group membership.
The class is typically used in a handler for the Control.DragOver or Control.MouseMove event to update the position of the insertion mark as an item is dragged. It is also used in a handler for the Control.DragDrop or Control.MouseUp event to insert a dragged item at the correct location.
To update the position of the insertion mark, follow these steps:
Use the NearestIndex method to retrieve the index of the item closest to the mouse pointer.
Pass the index value to the ListView.GetItemRect method to retrieve the bounding rectangle of the item.
If the mouse pointer is located to the left of the midpoint of the bounding rectangle, set the AppearsAfterItem property to false; otherwise, set it to true.
Set the Index property to the index value retrieved from the NearestIndex method. The insertion mark appears next to item with the specified index, either to the left or the right, depending on the AppearsAfterItem property value. If an item is dragged over itself, the index is -1 and the insertion mark is hidden.
To insert the dragged item at the correct location, follow these steps:
In a handler for the Control.DragDrop or Control.MouseUp event, use the Index property to determine the current location of the insertion mark. Store this value to be used later as the insertion index.
If the AppearsAfterItem property is set to true, increment the stored insertion index value.
Use the ListView.ListViewItemCollection.Remove method to remove the original copy of the dragged item.
You must insert a clone of the dragged item before the original copy is removed so the index values in the ListView.Items collection are not altered before the insertion.
To ensure that the items are displayed in the same order as their index values, you must set the ListView.ListViewItemSorter property to an implementation of the IComparer interface that sorts items by index value. For more information, see the Example section.
The insertion mark feature is available only on Windows XP and the Windows Server 2003 family when your application calls the Application.EnableVisualStyles method. On earlier operating systems, any code relating to the insertion mark will be ignored and the insertion mark will not appear. As a result, any code that depends on the insertion mark feature may not work correctly. You may want to include a test that determines whether the insertion mark feature is available, and provide alternate functionality when it is unavailable. For example, you may want to bypass all code that implements drag-and-drop item repositioning when running on operating systems that do not support insertion marks.
The insertion mark feature is provided by the same library that provides the operating system themes feature. To check for the availability of this library, call the FeatureSupport.IsPresent(Object) method overload and pass in the OSFeature.Themes value.
The following code example demonstrates how to use the ListView insertion mark feature and implements drag-and-drop item reordering using the standard drag events. The position of the insertion mark is updated in a handler for the Control.DragOver event. In this handler, the position of the mouse pointer is compared to the midpoint of the nearest item, and the result is used to determine whether the insertion mark appears to the left or the right of the item.
Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.