Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

ListView::InsertionMark Property

Gets an object used to indicate the expected drop location when an item is dragged within a ListView control.

Namespace:  System.Windows.Forms
Assembly:  System.Windows.Forms (in System.Windows.Forms.dll)

[BrowsableAttribute(false)]
public:
property ListViewInsertionMark^ InsertionMark {
	ListViewInsertionMark^ get ();
}

Property Value

Type: System.Windows.Forms::ListViewInsertionMark
A ListViewInsertionMark object representing the insertion mark.

The ListView insertion mark feature lets you 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 AutoArrange property is set to true and when the ListView control does not sort the items automatically. To prevent automatic sorting, the Sorting property must be set to SortOrder::None and the View property must be set to View::LargeIcon, View::SmallIcon, or View::Tile. Additionally, the insertion mark feature may not be visible with the ListView grouping feature because the grouping feature orders the items by group membership.

The ListViewInsertionMark 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. For more information, see ListViewInsertionMark and How to: Display an Insertion Mark in a Windows Forms ListView Control.

NoteNote:

The insertion mark feature is available only on Windows XP and Windows Server 2003 when your application calls the Application::EnableVisualStyles method. On earlier operating systems, any code relating to the insertion mark has no effect and the insertion mark will not appear. As a result, any code that depends on the insertion mark feature might not work correctly. You might want to include code that determines whether this feature is available, and provide alternate functionality when it is unavailable. For example, you might 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. This example 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.

#using <System.dll>
#using <System.Windows.Forms.dll>
#using <System.Drawing.dll>

using namespace System;
using namespace System::Drawing;
using namespace System::Windows::Forms;
public ref class ListViewInsertionMarkExample: public Form
{
private:
   ListView^ myListView;

public:

   ListViewInsertionMarkExample()
   {
      // Initialize myListView.
      myListView = gcnew ListView;
      myListView->Dock = DockStyle::Fill;
      myListView->View = View::LargeIcon;
      myListView->MultiSelect = false;
      myListView->ListViewItemSorter = gcnew ListViewIndexComparer;

      // Initialize the insertion mark.
      myListView->InsertionMark->Color = Color::Green;

      // Add items to myListView.
      myListView->Items->Add( "zero" );
      myListView->Items->Add( "one" );
      myListView->Items->Add( "two" );
      myListView->Items->Add( "three" );
      myListView->Items->Add( "four" );
      myListView->Items->Add( "five" );

      // Initialize the drag-and-drop operation when running 
      // under Windows XP or a later operating system. 
      if ( System::Environment::OSVersion->Version->Major > 5 || (System::Environment::OSVersion->Version->Major == 5 && System::Environment::OSVersion->Version->Minor >= 1) )
      {
         myListView->AllowDrop = true;
         myListView->ItemDrag += gcnew ItemDragEventHandler( this, &ListViewInsertionMarkExample::myListView_ItemDrag );
         myListView->DragEnter += gcnew DragEventHandler( this, &ListViewInsertionMarkExample::myListView_DragEnter );
         myListView->DragOver += gcnew DragEventHandler( this, &ListViewInsertionMarkExample::myListView_DragOver );
         myListView->DragLeave += gcnew EventHandler( this, &ListViewInsertionMarkExample::myListView_DragLeave );
         myListView->DragDrop += gcnew DragEventHandler( this, &ListViewInsertionMarkExample::myListView_DragDrop );
      }

      // Initialize the form. 
      this->Text = "ListView Insertion Mark Example";
      this->Controls->Add( myListView );
   }

private:

   // Starts the drag-and-drop operation when an item is dragged. 
   void myListView_ItemDrag( Object^ /*sender*/, ItemDragEventArgs^ e )
   {
      myListView->DoDragDrop( e->Item, DragDropEffects::Move );
   }

   // Sets the target drop effect. 
   void myListView_DragEnter( Object^ /*sender*/, DragEventArgs^ e )
   {
      e->Effect = e->AllowedEffect;
   }

   // Moves the insertion mark as the item is dragged. 
   void myListView_DragOver( Object^ /*sender*/, DragEventArgs^ e )
   {
      // Retrieve the client coordinates of the mouse pointer.
      Point targetPoint = myListView->PointToClient( Point(e->X,e->Y) );

      // Retrieve the index of the item closest to the mouse pointer. 
      int targetIndex = myListView->InsertionMark->NearestIndex( targetPoint );

      // Confirm that the mouse pointer is not over the dragged item. 
      if ( targetIndex > -1 )
      {
         // Determine whether the mouse pointer is to the left or 
         // the right of the midpoint of the closest item and set 
         // the InsertionMark.AppearsAfterItem property accordingly.
         Rectangle itemBounds = myListView->GetItemRect( targetIndex );
         if ( targetPoint.X > itemBounds.Left + (itemBounds.Width / 2) )
         {
            myListView->InsertionMark->AppearsAfterItem = true;
         }
         else
         {
            myListView->InsertionMark->AppearsAfterItem = false;
         }
      }

      // Set the location of the insertion mark. If the mouse is 
      // over the dragged item, the targetIndex value is -1 and 
      // the insertion mark disappears.
      myListView->InsertionMark->Index = targetIndex;
   }

   // Removes the insertion mark when the mouse leaves the control. 
   void myListView_DragLeave( Object^ /*sender*/, EventArgs^ /*e*/ )
   {
      myListView->InsertionMark->Index = -1;
   }

   // Moves the item to the location of the insertion mark. 
   void myListView_DragDrop( Object^ /*sender*/, DragEventArgs^ e )
   {
      // Retrieve the index of the insertion mark; 
      int targetIndex = myListView->InsertionMark->Index;

      // If the insertion mark is not visible, exit the method. 
      if ( targetIndex == -1 )
      {
         return;
      }

      // If the insertion mark is to the right of the item with 
      // the corresponding index, increment the target index. 
      if ( myListView->InsertionMark->AppearsAfterItem )
      {
         targetIndex++;
      }

      // Retrieve the dragged item.
      ListViewItem^ draggedItem = dynamic_cast<ListViewItem^>(e->Data->GetData( ListViewItem::typeid ));

      // Insert a copy of the dragged item at the target index. 
      // A copy must be inserted before the original item is removed 
      // to preserve item index values.
      myListView->Items->Insert( targetIndex, dynamic_cast<ListViewItem^>(draggedItem->Clone()) );

      // Remove the original copy of the dragged item.
      myListView->Items->Remove( draggedItem );

   }

   // Sorts ListViewItem objects by index. 
   ref class ListViewIndexComparer: public System::Collections::IComparer
   {
   public:
      virtual int Compare( Object^ x, Object^ y )
      {
         return (dynamic_cast<ListViewItem^>(x))->Index - (dynamic_cast<ListViewItem^>(y))->Index;
      }
   };
};

[STAThread]
int main()
{
   Application::EnableVisualStyles();
   Application::Run( gcnew ListViewInsertionMarkExample );
}

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0

Community Additions

ADD
Show:
© 2015 Microsoft