ListViewInsertionMark Clase

Definición

Se utiliza para indicar la acción de colocar esperada cuando un elemento se arrastra hacia una nueva posición en un control ListView.Used to indicate the expected drop location when an item is dragged to a new position in a ListView control. Esta funcionalidad sólo está disponible en Windows XP y posterior.This functionality is available only on Windows XP and later.

public ref class ListViewInsertionMark sealed
public sealed class ListViewInsertionMark
type ListViewInsertionMark = class
Public NotInheritable Class ListViewInsertionMark
Herencia
ListViewInsertionMark

Ejemplos

En el ejemplo de código siguiente se muestra cómo ListView usar la característica de marca de inserción e implementa la reordenación de elementos de arrastrar y colocar con los eventos de arrastre estándar.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. La posición de la marca de inserción se actualiza en un controlador para Control.DragOver el evento.The position of the insertion mark is updated in a handler for the Control.DragOver event. En este controlador, la posición del puntero del mouse se compara con el punto medio del elemento más cercano y el resultado se usa para determinar si la marca de inserción aparece a la izquierda o a la derecha del elemento.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 );
}
using System;
using System.Drawing;
using System.Windows.Forms;

public class ListViewInsertionMarkExample : Form
{
    private ListView myListView; 

    public ListViewInsertionMarkExample()
    {
        // Initialize myListView.
        myListView = new ListView();
        myListView.Dock = DockStyle.Fill;
        myListView.View = View.LargeIcon;
        myListView.MultiSelect = false;
        myListView.ListViewItemSorter = new 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 (OSFeature.Feature.IsPresent(OSFeature.Themes))
        {
            myListView.AllowDrop = true;
            myListView.ItemDrag += new ItemDragEventHandler(myListView_ItemDrag);
            myListView.DragEnter += new DragEventHandler(myListView_DragEnter);
            myListView.DragOver += new DragEventHandler(myListView_DragOver);
            myListView.DragLeave += new EventHandler(myListView_DragLeave);
            myListView.DragDrop += new DragEventHandler(myListView_DragDrop);
        }

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

    [STAThread]
    static void Main() 
    {
        Application.EnableVisualStyles();
        Application.Run(new ListViewInsertionMarkExample());
    }

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

    // Sets the target drop effect.
    private void myListView_DragEnter(object sender, DragEventArgs e)
    {
        e.Effect = e.AllowedEffect;
    }

    // Moves the insertion mark as the item is dragged.
    private void myListView_DragOver(object sender, DragEventArgs e)
    {
        // Retrieve the client coordinates of the mouse pointer.
        Point targetPoint = 
            myListView.PointToClient(new 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.
    private void myListView_DragLeave(object sender, EventArgs e)
    {
        myListView.InsertionMark.Index = -1;
    }

    // Moves the item to the location of the insertion mark.
    private 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 = 
            (ListViewItem)e.Data.GetData(typeof(ListViewItem));

        // 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, (ListViewItem)draggedItem.Clone());

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

    // Sorts ListViewItem objects by index.
    private class ListViewIndexComparer : System.Collections.IComparer
    {
        public int Compare(object x, object y)
        {
            return ((ListViewItem)x).Index - ((ListViewItem)y).Index;
        }
    }

}
Imports System.Drawing
Imports System.Windows.Forms

Public Class ListViewInsertionMarkExample
    Inherits Form

    Private myListView As ListView
    
    Public Sub New()
        ' Initialize myListView.
        myListView = New ListView()
        myListView.Dock = DockStyle.Fill
        myListView.View = View.LargeIcon
        myListView.MultiSelect = False
        myListView.ListViewItemSorter = New 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 OSFeature.Feature.IsPresent(OSFeature.Themes)
            myListView.AllowDrop = True
            AddHandler myListView.ItemDrag, AddressOf myListView_ItemDrag
            AddHandler myListView.DragEnter, AddressOf myListView_DragEnter
            AddHandler myListView.DragOver, AddressOf myListView_DragOver
            AddHandler myListView.DragLeave, AddressOf myListView_DragLeave
            AddHandler myListView.DragDrop, AddressOf myListView_DragDrop
        End If 

        ' Initialize the form.
        Me.Text = "ListView Insertion Mark Example"
        Me.Controls.Add(myListView)
    End Sub

    <STAThread()> _
    Shared Sub Main()
        Application.EnableVisualStyles()
        Application.Run(New ListViewInsertionMarkExample())
    End Sub
    
    ' Starts the drag-and-drop operation when an item is dragged.
    Private Sub myListView_ItemDrag(sender As Object, e As ItemDragEventArgs)
        myListView.DoDragDrop(e.Item, DragDropEffects.Move)
    End Sub
    
    ' Sets the target drop effect.
    Private Sub myListView_DragEnter(sender As Object, e As DragEventArgs)
        e.Effect = e.AllowedEffect
    End Sub
    
    ' Moves the insertion mark as the item is dragged.
    Private Sub myListView_DragOver(sender As Object, e As DragEventArgs)
        ' Retrieve the client coordinates of the mouse pointer.
        Dim targetPoint As Point = myListView.PointToClient(New Point(e.X, e.Y))
        
        ' Retrieve the index of the item closest to the mouse pointer.
        Dim targetIndex As Integer = _
            myListView.InsertionMark.NearestIndex(targetPoint)
        
        ' Confirm that the mouse pointer is not over the dragged item.
        If targetIndex > -1 Then
            ' 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.
            Dim itemBounds As Rectangle = myListView.GetItemRect(targetIndex)
            If targetPoint.X > itemBounds.Left + (itemBounds.Width / 2) Then
                myListView.InsertionMark.AppearsAfterItem = True
            Else
                myListView.InsertionMark.AppearsAfterItem = False
            End If
        End If
        
        ' 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
    End Sub

    ' Removes the insertion mark when the mouse leaves the control.
    Private Sub myListView_DragLeave(sender As Object, e As EventArgs)
        myListView.InsertionMark.Index = -1
    End Sub
    
    ' Moves the item to the location of the insertion mark.
    Private Sub myListView_DragDrop(sender As Object, e As DragEventArgs)
        ' Retrieve the index of the insertion mark;
        Dim targetIndex As Integer = myListView.InsertionMark.Index
        
        ' If the insertion mark is not visible, exit the method.
        If targetIndex = -1 Then
            Return
        End If 

        ' If the insertion mark is to the right of the item with
        ' the corresponding index, increment the target index.
        If myListView.InsertionMark.AppearsAfterItem Then
            targetIndex += 1
        End If 

        ' Retrieve the dragged item.
        Dim draggedItem As ListViewItem = _
            CType(e.Data.GetData(GetType(ListViewItem)), ListViewItem)
        
        ' 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, _
            CType(draggedItem.Clone(), ListViewItem))
        
        ' Remove the original copy of the dragged item.
        myListView.Items.Remove(draggedItem)

    End Sub
    
    ' Sorts ListViewItem objects by index.    
    Private Class ListViewIndexComparer
        Implements System.Collections.IComparer
        
        Public Function Compare(x As Object, y As Object) As Integer _
            Implements System.Collections.IComparer.Compare
            Return CType(x, ListViewItem).Index - CType(y, ListViewItem).Index
        End Function 'Compare

    End Class

End Class

Comentarios

Puede recuperar un ListViewInsertionMark objeto de la InsertionMark propiedad de un ListView control y usarlo para indicar visualmente la ubicación de destino esperada en una operación de arrastrar y colocar cuando un elemento se arrastra a una nueva posición.You can retrieve a ListViewInsertionMark 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.

Esta característica solo funciona cuando la ListView.AutoArrange propiedad está establecida en true y cuando el ListView control no ordena los elementos automáticamente.This feature works only when the ListView.AutoArrange property is set to true and when the ListView control does not sort the items automatically. Para evitar la ordenación automática, ListView.Sorting la propiedad debe establecerse SortOrder.None en y ListView.View la propiedad se debe establecer View.LargeIconen View.SmallIcon, o View.Tile.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. Además, la característica de la marca de inserción no se ListView puede usar con la característica de agrupación porque la característica de agrupación ordena los elementos según la pertenencia al grupo.Additionally, the insertion mark feature cannot be used with the ListView grouping feature because the grouping feature orders the items by group membership.

La ListViewInsertionMark clase se utiliza normalmente en un controlador para el Control.DragOver evento Control.MouseMove o para actualizar la posición de la marca de inserción a medida que se arrastra un elemento.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. También se usa en un controlador para el Control.DragDrop evento o Control.MouseUp para insertar un elemento arrastrado en la ubicación correcta.It is also used in a handler for the Control.DragDrop or Control.MouseUp event to insert a dragged item at the correct location.

Para actualizar la posición de la marca de inserción, siga estos pasos:To update the position of the insertion mark, follow these steps:

  1. En un controlador para el Control.DragOver evento Control.MouseMove o, use ListViewInsertionMark la ListView.InsertionMark ListView propiedad para tener acceso al objeto asociado al control.In a handler for the Control.DragOver or Control.MouseMove event, use the ListView.InsertionMark property to access the ListViewInsertionMark object associated with the ListView control.

  2. Utilice el NearestIndex método para recuperar el índice del elemento más próximo al puntero del mouse.Use the NearestIndex method to retrieve the index of the item closest to the mouse pointer.

  3. Pase el valor de índice al ListView.GetItemRect método para recuperar el rectángulo delimitador del elemento.Pass the index value to the ListView.GetItemRect method to retrieve the bounding rectangle of the item.

  4. Si el puntero del mouse se encuentra a la izquierda del punto medio del rectángulo delimitador, establezca la AppearsAfterItem propiedad en false; de lo contrario, establézcalo trueen.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.

  5. Establezca la Index propiedad en el valor NearestIndex de índice recuperado del método.Set the Index property to the index value retrieved from the NearestIndex method. La marca de inserción aparece junto a elemento con el índice especificado, a la izquierda o a la derecha, dependiendo del valor AppearsAfterItem de la propiedad.The insertion mark appears next to item with the specified index, either to the left or the right, depending on the AppearsAfterItem property value. Si un elemento se arrastra sobre sí mismo, el índice es-1 y se oculta la marca de inserción.If an item is dragged over itself, the index is -1 and the insertion mark is hidden.

Para insertar el elemento arrastrado en la ubicación correcta, siga estos pasos:To insert the dragged item at the correct location, follow these steps:

  1. En un controlador para el Control.DragDrop evento Control.MouseUp o, use la Index propiedad para determinar la ubicación actual de la marca de inserción.In a handler for the Control.DragDrop or Control.MouseUp event, use the Index property to determine the current location of the insertion mark. Almacene este valor para usarlo más adelante como índice de inserción.Store this value to be used later as the insertion index.

  2. Si la AppearsAfterItem propiedad está establecida en true, aumente el valor del índice de inserción almacenado.If the AppearsAfterItem property is set to true, increment the stored insertion index value.

  3. Utilice el ListView.ListViewItemCollection.Insert método para insertar un clon del elemento arrastrado en la ListView.Items colección, en el índice de inserción almacenado.Use the ListView.ListViewItemCollection.Insert method to insert a clone of the dragged item into the ListView.Items collection at the stored insertion index.

  4. Use el ListView.ListViewItemCollection.Remove método para quitar la copia original del elemento arrastrado.Use the ListView.ListViewItemCollection.Remove method to remove the original copy of the dragged item.

Debe insertar un clon del elemento arrastrado antes de que se elimine la copia original, de modo que los ListView.Items valores de índice de la colección no se modifiquen antes de la inserción.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.

Para asegurarse de que los elementos se muestran en el mismo orden que sus valores de índice, debe establecer ListView.ListViewItemSorter la propiedad en una implementación de IComparer la interfaz que ordena los elementos por valor de índice.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. Para obtener más información, vea la sección ejemplo.For more information, see the Example section.

Puede modificar el color de la marca de inserción utilizando la Color propiedad.You can modify the color of the insertion mark by using the Color property. Si necesita el tamaño o la posición de la marca de inserción, puede obtener su rectángulo delimitador a Bounds través de la propiedad.If you need the size or position of the insertion mark, you can get its bounding rectangle through the Bounds property.

Nota

La característica de marca de inserción solo está disponible en Windows XP y en la familia de Windows Server 2003 cuando Application.EnableVisualStyles la aplicación llama al método.The insertion mark feature is available only on Windows XP and the Windows Server 2003 family when your application calls the Application.EnableVisualStyles method. En los sistemas operativos anteriores, cualquier código relacionado con la marca de inserción se omitirá y la marca de inserción no aparecerá.On earlier operating systems, any code relating to the insertion mark will be ignored and the insertion mark will not appear. Como resultado, es posible que cualquier código que dependa de la característica de marca de inserción no funcione correctamente.As a result, any code that depends on the insertion mark feature may not work correctly. Es posible que desee incluir una prueba que determine si la característica de marca de inserción está disponible y proporcionar una funcionalidad alternativa cuando no está disponible.You may want to include a test that determines whether the insertion mark feature is available, and provide alternate functionality when it is unavailable. Por ejemplo, puede que desee omitir todo el código que implementa la reposición de los elementos de arrastrar y colocar al ejecutarse en sistemas operativos que no admiten marcas de inserción.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.

La característica de marca de inserción la proporciona la misma biblioteca que proporciona la característica temas del sistema operativo.The insertion mark feature is provided by the same library that provides the operating system themes feature. Para comprobar la disponibilidad de esta biblioteca, llame a la FeatureSupport.IsPresent(Object) sobrecarga del método y pase el OSFeature.Themes valor.To check for the availability of this library, call the FeatureSupport.IsPresent(Object) method overload and pass in the OSFeature.Themes value.

Propiedades

AppearsAfterItem

Obtiene o establece un valor que indica si la marca de inserción aparece a la derecha del elemento con el índice especificado por la propiedad Index.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

Obtiene el rectángulo delimitador de la marca de inserción.Gets the bounding rectangle of the insertion mark.

Color

Obtiene o establece el color de la marca de inserción.Gets or sets the color of the insertion mark.

Index

Obtiene o establece el índice del elemento junto al cual aparece la marca de inserción.Gets or sets the index of the item next to which the insertion mark appears.

Métodos

Equals(Object)

Determina si el objeto especificado es igual al objeto actual.Determines whether the specified object is equal to the current object.

(Heredado de Object)
GetHashCode()

Sirve como la función hash predeterminada.Serves as the default hash function.

(Heredado de Object)
GetType()

Obtiene el Type de la instancia actual.Gets the Type of the current instance.

(Heredado de Object)
MemberwiseClone()

Crea una copia superficial del objeto Object actual.Creates a shallow copy of the current Object.

(Heredado de Object)
NearestIndex(Point)

Recupera el índice del elemento más próximo al punto especificado.Retrieves the index of the item closest to the specified point.

ToString()

Devuelve una cadena que representa el objeto actual.Returns a string that represents the current object.

(Heredado de Object)

Se aplica a

Consulte también: