# Item Reordering

Better ListView: Ultimate .NET ListView replacement control for WinForms (C#, VB.NET)
Download More Info

Changing item order by dragging items can be turned on by setting ItemReorderMode to one of the following values:

- Disabled

  - Item reordering is disabled (default value).

- Enabled

  - Item reordering is enabled and automatic.

- Custom

  - Item reordering is enabled, but the actual reordering is up to the user.

The reordering is realized through Drag and Drop mechanism.

Item reordering can supports groups and item hierarchy.

Target location of reordered items is displayed using Insertion mark. If the reordering cannot be performed (e.g. when inserting item between its own children), then the insertion mark is displayed as disabled and the reordering will not be performed.

## Reordering Options

There are several item reordering options to adjust the feature for working with groups and hierarchical items. These options can be used as flags of the enumm property ItemReorderOptions:

- AllowCreateChild

  - Allow creating a child items by inserting item into another item without children.

- AutoCollapse

  - Collapse item with children prior to reordering.

- KeepGroups

  - Do not change item groups when reordering.

- KeepItemHierarchy

  - Keep parent-child item relations when reordering.

- None

  - No options are active.

- SameParentOnly

  - Allow reordering items with same parent item only.

None of the extra options are on by default so the default value is ItemReorderOptions.None.

## Auto-Expansion Checking

Auto expansion checking is performed during item reordering and looks whether it is valid to auto expand item over which mouse cursor hovers. By default, there is only one situation when auto expansion is not allowed: Item which is auto-collapsed will not be than auto-expanded again.

It is possible to add custom checking (e.g. when some items or groups should not expand when user drags items over it) by handling CheckAutoExpand event and than set BetterListViewCheckAutoExpandEventArgs.IsValid to false whenever you want to deny auto-expansion. Event data contains both source and target items.

## Item Reordering Checking

Checking for item reorder validity is performed during item reordering. It looks for possible reasons why the reordering may not be valid (e.g. reordering parent item into itself) and sets BetterListViewItemReorderEventArgs.InvalidationReasons property. The property can have the following flags:

- None

  - Item reorder is valid.

- NotTopLevel

  - Item reorder is invalid in case of data binding when other than top-level item is being reordered.

- NotSameParent

  - Item is being reordered under different parent when SameParentOnly item reordering option is turned on.

- PutInItself

  - Item is being reordered under itself.

- AnotherGroup

  - Item is being reordered in differenet group while changing groups is not allowed.

- Custom

  - User-specified reason for invalid item reorder.

You can override the OnCheckItemReorder method or add CheckItemReorder event handler to add your own validation.

Event data contains read-only property called IsValid, which is true whenever InvalidationReasons property is equal to BetterListViewInvalidationReasons.None.

Item reorder validity influences appearance of insertion mark (will be displayed in disabled state) and whether the reordering will be performed.

## Item Reordering Info

When user releases mouse button, the ItemReorder event is raised. You can find useful properties in the event data:

- Locations

  - Item locations before and after reordering structured as key-value pairs within dictionary.

- SourceItems

  - Items being reordered.

- TargetAddress

  - Target item address before reordering.

- TargetAddressAdjusted

  - Target item address after reordering. When doing custom reordering, this adjusted address is relevant when source items are removed from the list.

## Sample Source Code

C#

    this.listView.BeginUpdate();

    this.listView.Columns.Add("column");

    this.listView.Items.AddRange(
        new[]
        {
            "first item",
            "second item",
            "third item",
            "fourth item",
            "fifth item"
        });

    // enable item reordering
    this.listView.ItemReorderMode = BetterListViewItemReorderMode.Enabled;

    this.listView.EndUpdate();

Visual Basic

    ListView.BeginUpdate()

    ListView.Columns.Add ("column")

    ListView.Items.AddRange (
        New String() { _
                         "first item",
                         "second item",
                         "third item",
                         "fourth item",
                         "fifth item"
                     })

    ' enable item reordering
    ListView.ItemReorderMode = BetterListViewItemReorderMode.Enabled

    ListView.EndUpdate()

Better ListView: Ultimate .NET ListView replacement control for WinForms (C#, VB.NET)
Download More Info