Esta documentación está archivada y no tiene mantenimiento.

ListViewInsertionMark (Clase)

Se utiliza para indicar la acción de colocar esperada cuando un elemento se arrastra hacia una nueva posición en un control ListView. Esta funcionalidad sólo está disponible en Windows XP y posterior.

Espacio de nombres: System.Windows.Forms
Ensamblado: System.Windows.Forms (en system.windows.forms.dll)

public sealed class ListViewInsertionMark
public final class ListViewInsertionMark
public final class ListViewInsertionMark
No aplicable.

Puede recuperar un ListViewInsertionMark de la propiedad InsertionMark de un control ListView y utilizarlo para indicar visualmente la ubicación de colocación esperada cuando se arrastra un elemento hasta una nueva posición.

Esta característica sólo funciona cuando el valor de la propiedad ListView.AutoArrange está establecido en true y el control ListView no ordena los elementos automáticamente. Para evitar la ordenación automática, debe establecer el valor de la propiedad ListView.Sorting en SortOrder.None y el valor de la propiedad ListView.View en View.LargeIcon, View.SmallIcon o View.Tile. Además, no puede utilizarse la característica de marca de inserción con la característica de agrupación de ListView porque esta característica ordena los elementos por su pertenencia a un grupo.

La clase ListViewInsertionMark se utiliza normalmente en un controlador del evento Control.DragOver o Control.MouseMove para actualizar la posición de la marca de inserción cuando se arrastra un elemento. También se utiliza en un controlador del evento Control.DragDrop o Control.MouseUp para insertar un elemento arrastrado en la ubicación correcta.

Para actualizar la posición de la marca de inserción, siga este procedimiento:

  1. En un controlador del evento Control.DragOver o Control.MouseMove, utilice la propiedad ListView.InsertionMark para obtener acceso al objeto ListViewInsertionMark asociado al control ListView.

  2. Utilice el método NearestIndex para recuperar el índice del elemento más cercano al puntero del mouse (ratón).

  3. Pase el valor de índice al método ListView.GetItemRect para recuperar el rectángulo delimitador del elemento.

  4. Si el puntero del mouse está situado a la izquierda del punto medio del rectángulo delimitador, establezca el valor de la propiedad AppearsAfterItem en false; en caso contrario, establézcalo en true.

  5. Establezca el valor de la propiedad Index en el valor de índice recuperado del método NearestIndex. La marca de inserción aparece junto al elemento con el índice especificado, ya sea a la izquierda o a la derecha, dependiendo del valor de la propiedad AppearsAfterItem. Si se arrastra un elemento sobre sí mismo, el índice es -1 y la marca de inserción está oculta.

Para insertar el elemento arrastrado en la ubicación correcta, siga este procedimiento:

  1. En un controlador del evento Control.DragDrop o Control.MouseUp, utilice la propiedad Index para determinar la ubicación actual de la marca de inserción. Almacene este valor que se va a utilizar más adelante como índice de inserción.

  2. Si el valor de la propiedad AppearsAfterItem está establecido en true, incremente el valor del índice de inserción almacenado.

  3. Utilice el método ListView.ListViewItemCollection.Insert para insertar un clon del elemento arrastrado en la colección de ListView.Items en el índice de inserción almacenado.

  4. Utilice el método ListView.ListViewItemCollection.Remove para quitar la copia original del elemento arrastrado.

Es preciso insertar un clon del elemento arrastrado antes de que se quite la copia original de modo que los valores de índice en la colección de ListView.Items no se vean alterados antes de la inserción.

Para garantizar que los elementos se muestran en el mismo orden que sus valores de índice, debe establecer la propiedad ListView.ListViewItemSorter en una implementación de la interfaz IComparer que ordene los elementos por valor de índice. Para obtener más información, vea la sección Ejemplo.

Se puede modificar el color de la marca de inserción mediante la propiedad Color. Si se necesita obtener el tamaño o la ubicación de la marca de inserción, se puede obtener su rectángulo delimitador mediante la propiedad Bounds.

NotaNota:

La característica de marca de inserción sólo está disponible en Windows XP y en la familia Windows Server 2003 cuando la aplicación llama al método Application.EnableVisualStyles. En los sistemas operativos anteriores, se omitirá cualquier código relacionado con la marca de inserción y no aparecerá la marca de inserción. Como resultado, cualquier código que dependa de la característica de marca de inserción podría no funcionar correctamente. Quizás desee incluir una prueba que determine si está disponible la característica de marca de inserción y proporcionar una funcionalidad alternativa cuando no lo está. Por ejemplo, puede desear omitir todo el código que implemente la recolocación de elementos mediante la operación de arrastrar y colocar al ejecutar sistemas operativos que no admitan las marcas de inserción.

La misma biblioteca que proporciona la función de temas del sistema operativo ofrece la función de marca de inserción. Para comprobar la disponibilidad de esta biblioteca, llame a la sobrecarga del método FeatureSupport.IsPresent(Object) y pase el valor OSFeature.Themes.

En el ejemplo de código siguiente se muestra cómo utilizar la característica de marca de inserción de ListView y se implementa la reordenación de elementos mediante arrastrar y colocar utilizando los eventos de arrastre estándar. La posición de la marca de inserción se actualiza en un controlador del evento Control.DragOver. En este controlador, la posición del puntero del mouse (ratón) se compara con el punto medio del elemento más cercano y se utiliza el resultado para determinar si la marca de inserción aparece a la izquierda o a la derecha del elemento.

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;
        }
    }

}

import System.*;
import System.Drawing.*;
import System.Windows.Forms.*;

public class ListViewInsertionMarkExample extends Form
{
    private ListView myListView;

    public ListViewInsertionMarkExample()
    {
        // Initialize myListView.
        myListView = new ListView();
        myListView.set_Dock(DockStyle.Fill);
        myListView.set_View(View.LargeIcon);
        myListView.set_MultiSelect(false);
        myListView.set_ListViewItemSorter(new ListViewIndexComparer());
        // Initialize the insertion mark.
        myListView.get_InsertionMark().set_Color(Color.get_Green());
        // Add items to myListView.
        myListView.get_Items().Add("zero");
        myListView.get_Items().Add("one");
        myListView.get_Items().Add("two");
        myListView.get_Items().Add("three");
        myListView.get_Items().Add("four");
        myListView.get_Items().Add("five");
        // Initialize the drag-and-drop operation when running
        // under Windows XP or a later operating system.
        if (System.Environment.get_OSVersion().get_Version().get_Major() > 5 
            || (System.Environment.get_OSVersion().get_Version().get_Major() 
            == 5 && System.Environment.get_OSVersion().get_Version().
            get_Minor() >= 1)) {
            myListView.set_AllowDrop(true);
            myListView.add_ItemDrag(new ItemDragEventHandler(
                myListView_ItemDrag));
            myListView.add_DragEnter(new DragEventHandler(
                myListView_DragEnter));
            myListView.add_DragOver(new DragEventHandler(myListView_DragOver));
            myListView.add_DragLeave(new EventHandler(myListView_DragLeave));
            myListView.add_DragDrop(new DragEventHandler(myListView_DragDrop));
        }
        // Initialize the form.
        this.set_Text("ListView Insertion Mark Example");
        this.get_Controls().Add(myListView);
    } //ListViewInsertionMarkExample

    /** @attribute STAThread()
     */
    public static void main(String[] args)
    {
        Application.Run(new ListViewInsertionMarkExample());
    } //main

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

    // Sets the target drop effect.
    private void myListView_DragEnter(Object sender, DragEventArgs e)
    {
        e.set_Effect(e.get_AllowedEffect());
    } //myListView_DragEnter

    // 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.get_X(), e.get_Y()));
        // Retrieve the index of the item closest to the mouse pointer.
        int targetIndex = myListView.get_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.get_X() > itemBounds.get_Left() 
                + itemBounds.get_Width() / 2) {
                myListView.get_InsertionMark().set_AppearsAfterItem(true);
            }
            else {
                myListView.get_InsertionMark().set_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.get_InsertionMark().set_Index(targetIndex);
    } //myListView_DragOver

    // Removes the insertion mark when the mouse leaves the control.
    private void myListView_DragLeave(Object sender, EventArgs e)
    {
        myListView.get_InsertionMark().set_Index(-1);
    } //myListView_DragLeave

    // 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.get_InsertionMark().get_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.get_InsertionMark().get_AppearsAfterItem()) {
            targetIndex++;
        }
        // Retrieve the dragged item.
        ListViewItem draggedItem = (ListViewItem)(e.get_Data().GetData(
                     ListViewItem.class.ToType()));
        // 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.get_Items().Insert(targetIndex, (ListViewItem)
            draggedItem.Clone());
        // Remove the original copy of the dragged item.
        myListView.get_Items().Remove(draggedItem);
    } //myListView_DragDrop

    // Sorts ListViewItem objects by index.
    private class ListViewIndexComparer 
        implements System.Collections.IComparer
    {
        public int Compare(Object x, Object y)
        {
            return ((ListViewItem)x).get_Index() 
                - ((ListViewItem)y).get_Index();
        } //Compare
    } //ListViewIndexComparer
} //ListViewInsertionMarkExample 

System.Object
  System.Windows.Forms.ListViewInsertionMark

Los miembros estáticos públicos (Shared en Visual Basic) de este tipo son seguros para la ejecución de subprocesos. No se garantiza que los miembros de instancias sean seguros para la ejecución de subprocesos.

Windows 98, Windows 2000 Service Pack 4, Windows CE, Windows Millennium, Windows Mobile para Pocket PC, Windows Mobile para Smartphone, Windows Server 2003, Windows XP Media Center, Windows XP Professional x64, Windows XP SP2, Windows XP Starter

Microsoft .NET Framework 3.0 es compatible con Windows Vista, Microsoft Windows XP SP2 y Windows Server 2003 SP1.

.NET Framework

Compatible con: 3.0, 2.0
Mostrar: