BinaryTreeListView

Creates a tree list view with no columns and no rows.

Add columns to Columns, then give the control its rows through ItemsControl.ItemsSource or ItemsControl.Items.

Gets or sets whether the user can move a column by dragging its heading.

While a heading is dragged, the column is washed in ColumnReorderIndicatorBrush and a line shows where it will land. The tree column can be moved like any other; the tree goes with it. ColumnReordered is raised after each move.

Gets or sets whether clicking a column heading sorts the rows by that column.

The first click on a heading sorts ascending and the next click descending; an arrow over the heading shows which, in SortGlyphBrush. Every branch is sorted within itself, so the tree keeps its shape: top-level rows are ordered against each other, each row's children against each other, and so on down.

A column is sorted by the property its GridViewColumn.DisplayMemberBinding reads. A column that draws its cells with a template names its property with SetSortMemberPath; without one, clicking its heading does nothing.

Numbers sort by value, dates by date, other comparable values by their own order, and anything else by its text, ignoring case. Empty values sort first in ascending order.

Turning this off removes the sort arrow and, for a bound tree, the ordering.

<tlv:BinaryTreeListView AllowsColumnSorting="True">
    <tlv:BinaryTreeListView.Columns>
        <GridViewColumn Header="Name" DisplayMemberBinding="{Binding Name}" />
        <!-- A templated column says what to sort by. -->
        <GridViewColumn Header="Status" tlv:BinaryTreeListView.SortMemberPath="Status">
            <GridViewColumn.CellTemplate>
                <DataTemplate>
                    <TextBlock Text="{Binding Status}" FontWeight="SemiBold" />
                </DataTemplate>
            </GridViewColumn.CellTemplate>
        </GridViewColumn>
    </tlv:BinaryTreeListView.Columns>
</tlv:BinaryTreeListView>

Gets or sets the background of every other row – the second, fourth, sixth and so on – counting the rows as they are drawn on screen.

The control counts the rows on show, from the top, passing over collapsed branches, and lays the stripes again whenever a branch opens or closes, the rows are sorted or the items change. So the stripes always alternate on screen, however deep the tree. If rows are expanded by something the control does not see – a binding to TreeViewItem.IsExpanded, say – call RefreshRowStriping afterwards.

<tlv:BinaryTreeListView RowBackgroundBrush="White"
                        AlternateRowBackgroundBrush="#F4F7FB"
                        RowSeparatorBrush="#E3E8EF" />

Gets or sets a picture to draw as the expander of an expanded row, in place of the shape the control draws.

See ExpandButtonImage, which works the same way for collapsed rows.

Gets or sets the fill behind the column headings.

Gets or sets the colour of the edge drawn to the right of and under each column heading.

Gets or sets the colour of the column headings' text.

Gets or sets the height of the column heading row.

Gets or sets the fill behind a column heading while the pointer is over it.

Gets or sets the fill behind a column heading while it is being pressed.

Gets or sets the colour of the line that shows where a dragged column will land, and of the wash over the column being dragged.

Gets the columns the rows are laid out in.

Columns can be added, removed and reordered at any time; every row follows. In XAML, add them inside a BinaryTreeListView.Columns property element.

<tlv:BinaryTreeListView.Columns>
    <GridViewColumn Header="Account" Width="280" DisplayMemberBinding="{Binding Name}" />
    <GridViewColumn Header="Balance" Width="120">
        <GridViewColumn.CellTemplate>
            <DataTemplate>
                <TextBlock Text="{Binding Balance, StringFormat=C}" TextAlignment="Right" />
            </DataTemplate>
        </GridViewColumn.CellTemplate>
    </GridViewColumn>
</tlv:BinaryTreeListView.Columns>

Gets or sets a picture to draw as the expander of a collapsed row, in place of the shape the control draws.

While this or CollapseButtonImage is set, the image is drawn over the ExpanderGlyph shape, so set both. ExpandCollapseButtonImageStretch sizes them. The drawn shapes need no images: they are sharp at every display scale and take their colours from ExpandCollapseControlFillBrush, ExpandCollapseBorderBrush and ExpandCollapsePlusMinusBrush.

<!-- Your own expander pictures, from the application's resources. -->
<tlv:BinaryTreeListView ExpandButtonImage="/Images/folder-closed.png"
                        CollapseButtonImage="/Images/folder-open.png"
                        ExpandCollapseButtonImageStretch="Uniform" />

Gets or sets the colour of the box drawn around the expander's mark.

Gets or sets how ExpandButtonImage and CollapseButtonImage are sized in the expander.

Gets or sets the colour inside the box of the boxed expander shapes, BinaryTreeListViewExpanderGlyph.PlusMinus and BinaryTreeListViewExpanderGlyph.BoxedChevron.

Gets or sets the colour of the expander's mark: the plus and minus, the chevron, the triangle, or the whole of the BinaryTreeListViewExpanderGlyph.Disc.

Gets or sets the shape the expander is drawn as.

The shape is drawn by the control, sharp at every display scale, and lightens under the pointer. Its colours are ExpandCollapsePlusMinusBrush for the mark, and ExpandCollapseControlFillBrush and ExpandCollapseBorderBrush for the box of the boxed shapes. Each Theme sets all three.

To use pictures of your own instead, set ExpandButtonImage and CollapseButtonImage; they are drawn over the shape.

<tlv:BinaryTreeListView ExpanderGlyph="BoxedChevron"
                        ExpandCollapsePlusMinusBrush="SteelBlue" />

Gets or sets the background of a selected row while the control does not have focus.

SelectionBackgroundBrush applies only while the tree has focus; set this as well to keep a designed selection colour when the user clicks elsewhere.

Gets or sets the text colour of a selected row while the control does not have focus.

Gets or sets whether the user can hold several rows selected at once.

Each Ctrl+click toggles one row in or out of the selection, keeping the row last clicked without Ctrl, and a plain click starts again with a single row. Turn on IsShiftMultiSelectionEnabled as well for Shift+click range selection.

The rows chosen with Ctrl+click and Shift+click are listed in MultiSelectedItems.

tree.IsMultiSelectionEnabled = true;

archiveButton.Click += (sender, e) =>
{
    foreach (BinaryTreeListViewItem row in tree.MultiSelectedItems)
    {
        // Header is the row object in a built tree; DataContext is, in a bound one.
        Archive(row.Header);
    }
};

Gets or sets whether the lines that join the rows are drawn dotted rather than solid.

Gets or sets whether lines are drawn joining each row to its parent and its siblings.

Gets or sets whether Shift+click selects a range of rows.

The range runs from the row last clicked without Shift (or last added with Ctrl) to the row clicked, in either direction, over the rows on show in the order they are drawn – so it can cross parents and levels, as in Windows Explorer. Rows inside collapsed branches are not included. The rows selected are in MultiSelectedItems.

<tlv:BinaryTreeListView IsMultiSelectionEnabled="True"
                        IsShiftMultiSelectionEnabled="True" />

Gets or sets the row background drawn while the pointer is over it.

Set a brush to give rows a hover state; with the default of null rows look the same whether or not the pointer is over them.

Gets or sets the row foreground drawn while the pointer is over it.

Gets the rows the user has selected while multi-selection is on.

The list is the control's own. Read it, but change the selection through the rows' TreeViewItem.IsSelected, or SelectNodesByIndices, rather than by adding or removing entries.

Gets or sets the colour of the lines that join the rows of the tree.

Gets or sets whether the tree is always drawn in the left-most column, whichever column TreeListViewColumn names.

Gets or sets the background of the first, third, fifth row and so on, counting the rows as they are drawn on screen.

Rows are striped only while AlternateRowBackgroundBrush is set; this brush is the other half of the pair.

Gets or sets the colour of a thin line drawn under every row.

A separator makes wide rows easier to follow across the columns, much as gridlines do in a spreadsheet; alternate-row striping (AlternateRowBackgroundBrush) does the same job more softly.

Gets or sets the background of a selected row while the control has focus.

Gets or sets the text colour of a selected row while the control has focus.

Gets the direction SortedColumn is sorted in.

Gets or sets the colour of the arrow drawn over the heading of the column the rows are sorted by.

Gets the column the rows are sorted by.

Gets or sets the built-in colour scheme the control is drawn in.

A scheme sets every colour the control has – the background, text and border, the row stripes and separators, the connecting lines and expander, hover and selection, the sort arrow, and the column headings – in one setting.

The scheme writes the control's brush properties, so set any one of them afterwards to change that colour alone. Setting the theme back to BinaryTreeListViewTheme.Custom clears every brush a scheme writes, returning the control to its default colours – or to the skin's, when a Binarymission skin is in force.

<!-- The dark scheme, with the selection in the application's own accent colour. -->
<tlv:BinaryTreeListView Theme="Midnight"
                        SelectionBackgroundBrush="#3A6FD8" />

// Follow the application's light and dark modes.
tree.Theme = darkMode ? BinaryTreeListViewTheme.Midnight : BinaryTreeListViewTheme.Office;

Gets or sets the column that carries the tree: the indent, the expander and the connecting lines.

Every other column draws a plain cell. The rows keep their parents and children whichever column carries the tree, and it can be changed at any time.

TreeListViewColumnIndex always reports this column's position, including after the user drags it somewhere else. Setting either property sets the other. RenderCollapseExpandVisualAlwaysInTheFirstColumn overrides both.

GridViewColumn nameColumn = new GridViewColumn { Header = "Name", DisplayMemberBinding = new Binding("Name") };
tree.Columns.Add(new GridViewColumn { Header = "Id", DisplayMemberBinding = new Binding("Id") });
tree.Columns.Add(nameColumn);

// The tree is drawn in the Name column, wherever the user moves it.
tree.TreeListViewColumn = nameColumn;

Gets or sets the position in Columns of the column that carries the tree.

It can be set before any columns are added, in XAML or in code: the column at that position becomes the tree column as soon as there is one. After that it follows TreeListViewColumn, so it changes when the user drags the tree column to a new place.

Gets or sets whether each row's background – its selection, hover and stripe colour – is drawn with rounded corners.

Stops sorting by a column and removes the sort arrow.

A bound tree goes back to the order of its source. A built tree's nodes stay where the last sort put them, because they were moved rather than viewed in order.

Collapses every row in the tree, at every level, and scrolls back to the first row.

Expands every row in the tree, at every level.

expandAllButton.Click += (sender, e) => tree.ExpandAllNodes(true);
collapseAllButton.Click += (sender, e) => tree.CollapseAllNodes();

Expands one top-level row and every row beneath it.

Expands several top-level rows, each with every row beneath it, then scrolls the first top-level row into view.

Creates the row that shows one bound item: a BinaryTreeListViewItem.

A new, empty BinaryTreeListViewItem.

Gets the name of the property a column is sorted by.

The property's name, or null when none has been set (the column's GridViewColumn.DisplayMemberBinding is used instead).

Tells the control whether an item is already a row, and so needs no row of its own.

true when item is a BinaryTreeListViewItem.

Applies the control's template.

The heading row and the sort arrow belong to the template that has just been thrown away, so both are looked for again the next time they are wanted.

Lays the alternate-row stripes again when top-level rows are added, removed or moved.

A derived class that overrides this should call the base implementation.

Draws the connecting lines and row separators of every row on screen again.

The control redraws them when its own properties change. Call this after changing something the rows are drawn from that the control does not watch, such as a brush you have modified in place rather than replaced.

Lays the alternating row backgrounds again, in the order the rows are drawn.

The control calls this itself whenever a branch opens or closes, the rows are sorted or the items change. Call it when rows are expanded or collapsed by something else – a binding to TreeViewItem.IsExpanded, for example – which the control has no way to notice.

Selects a top-level row by its position.

Only top-level rows are reached this way. To select a nested row, set TreeViewItem.IsSelected on its BinaryTreeListViewItem. The row must already have been created, which it is once the control has been loaded.

// Select the first top-level row once the window is on screen.
tree.Loaded += (sender, e) => tree.SelectNodeByIndex(0);

Selects several top-level rows by their positions, then scrolls the first top-level row into view.

With IsMultiSelectionEnabled on, every row asked for is selected and held in MultiSelectedItems, just as if the user had Ctrl+clicked each one. With it off, the tree holds one selected row, so the row left selected is the last valid position.

tree.IsMultiSelectionEnabled = true;
tree.SelectNodesByIndices(new[] { 0, 2, 3 });   // three rows selected together

Sets the name of the property a column is sorted by.

Needed only for columns that draw their cells with a GridViewColumn.CellTemplate. A path set here wins over the column's GridViewColumn.DisplayMemberBinding.

GridViewColumn status = new GridViewColumn { Header = "Status", CellTemplate = statusTemplate };
BinaryTreeListView.SetSortMemberPath(status, "Status");
tree.Columns.Add(status);

Sorts every branch of the tree by one column.

Works whether or not AllowsColumnSorting is on, so a tree can open already sorted while the headings stay unclickable. Each branch is sorted within itself, so children stay under their parents.

A bound tree is sorted through each level's collection view, leaving your collections untouched. A built tree has its nodes put in order in place.

// Open with the largest folders first.
tree.SortByColumn(tree.Columns[2], ListSortDirection.Descending);

Occurs after a column has moved: dragged to a new place by the user, or moved in code with Move on Columns.

Read the new order from Columns – to save the user's layout, for example. TreeListViewColumnIndex has already been updated when the event is raised.

tree.ColumnReordered += (sender, e) =>
{
    // Remember the user's column order, by heading.
    Settings.ColumnOrder = string.Join("|", tree.Columns.Select(c => c.Header));
};

Occurs after the rows have been sorted by a column, by a click on its heading or by SortByColumn.

SortedColumn and SortDirection hold the new sort when the event is raised.

tree.ColumnSorted += (sender, e) =>
{
    statusText.Text = "Sorted by " + tree.SortedColumn.Header
        + (tree.SortDirection == ListSortDirection.Ascending ? ", A to Z" : ", Z to A");
};

Identifies the AllowsColumnReorder dependency property.

Identifies the AllowsColumnSorting dependency property.

Identifies the AlternateRowBackgroundBrush dependency property.

Identifies the CollapseButtonImage dependency property.

Identifies the ColumnHeaderBackgroundBrush dependency property.

Identifies the ColumnHeaderBorderBrush dependency property.

Identifies the ColumnHeaderForegroundBrush dependency property.

Identifies the ColumnHeaderHeight dependency property.

Identifies the ColumnHeaderHoverBackgroundBrush dependency property.

Identifies the ColumnHeaderPressedBackgroundBrush dependency property.

Identifies the ColumnReorderIndicatorBrush dependency property.

Identifies the ExpandButtonImage dependency property.

Identifies the ExpandCollapseBorderBrush dependency property.

Identifies the ExpandCollapseButtonImageStretch dependency property.

Identifies the ExpandCollapseControlFillBrush dependency property.

Identifies the ExpandCollapsePlusMinusBrush dependency property.

Identifies the ExpanderGlyph dependency property.

Identifies the InactiveSelectionBackgroundBrush dependency property.

Identifies the InactiveSelectionForegroundBrush dependency property.

Identifies the IsMultiSelectionEnabled dependency property.

Identifies the IsNodesConnectingLineDotted dependency property.

Identifies the IsNodesConnectingLineVisible dependency property.

Identifies the IsShiftMultiSelectionEnabled dependency property.

Identifies the MouseOverBackgroundBrush dependency property.

Identifies the MouseOverForegroundBrush dependency property.

Identifies the NodesConnectingLineBrush dependency property.

Identifies the RenderCollapseExpandVisualAlwaysInTheFirstColumn dependency property.

Identifies the RowBackgroundBrush dependency property.

Identifies the RowSeparatorBrush dependency property.

Identifies the SelectionBackgroundBrush dependency property.

Identifies the SelectionForegroundBrush dependency property.

Identifies the SortDirection dependency property.

Identifies the SortGlyphBrush dependency property.

Identifies the SortMemberPath attached property: the name of the property a column is sorted by, for a column that draws its cells with a template and so has no GridViewColumn.DisplayMemberBinding to read one from.

Identifies the SortedColumn dependency property.

Identifies the Theme dependency property.

Identifies the TreeListViewColumnIndex dependency property.

Identifies the TreeListViewColumn dependency property.

Identifies the TreeListViewItemIsRenderedWithRoundedCorner dependency property.