Skip to content

Latest commit

 

History

History
86 lines (65 loc) · 4.04 KB

TreeViewSelectionAPI.md

File metadata and controls

86 lines (65 loc) · 4.04 KB

Background

The Xaml TreeView control shows a list of hierarchical data, similar to a ListView.

When TreeView was first released, you populated it using the RootNode property, giving it a tree of nodes, each node referencing a data item. There was negative feedback about this nodes approach, though, from developers preferring a more data binding friendly pattern along the lines of ListView.ItemsSource.

So a TreeView.ItemsSource property was added, and now you can use either the nodes approach or the ItemsSource approach. But unlike ListView, TreeView doesn't have the corresponding SelectedItem and SelectedItems properties for single- and multi-select. Those are being added in this spec.

Also being added in this spec, for the case where the RootNode is being used instead of ItemsSource, is an API to select a single node. That is, there is a SelectedNodes property today, and this spec is adding a singular SelectedNode property.

Related GitHub issues:
microsoft/microsoft-ui-xaml#197
microsoft/microsoft-ui-xaml#124
microsoft/microsoft-ui-xaml#386

Description

Extend TreeView selection API sets to make selections easier.

  • Add SelectedNode: get/set the selected TreeViewNode for single selection
  • Add SelectedItem: get/set the selected item for single selection
  • Add SelectedItems: get the SelectedItems collection.
  • Fix existing SelectedNodes property: Currently this only works in multi-select mode (SelectionMode set to Multiple). It will now also work in single selection mode (consistent with ListView).

Examples

TreeView.SelectedNode

Ouput the depth of the selected tree view node.

TreeViewNode selectedNode = treeView.SelectedNode;
if (selectedNode != null)
{
    Debug.WriteLine($"Selected node depth: {selectedNode.Depth}");
}

TreeView.SelectedItem

Bind the TreeView control to a View Model with the data source and the currently selected item.

<TreeView ItemsSource="{x:Bind Descendants}"
            SelectedItem="{x:Bind CurrentDescendant, Mode=TwoWay}" />

TreeView.SelectedItems

void AddToSelection(TreeView treeView, object item)
{
    IList<Object> selectedItems = treeView.SelectedItems;
    selectedItems.Add(item);
}

API Details

namespace Microsoft.UI.Xaml.Controls
{
    [webhosthidden]
    unsealed runtimeclass TreeView : Windows.UI.Xaml.Controls.Control
    {
        ...

        TreeViewNode SelectedNode{ get; set; };
        Object SelectedItem{ get; set; };
        Windows.Foundation.Collections.IVector<Object> SelectedItems{ get; };

        ...
    }
}

Remarks

SelectedItem(s) returns Object(collection of objects), it will be the ItemsSource type object when using databinding, or TreeViewNode when not using databinding.

Prior to WinUI 2.2, the TreeView.SelectedNodes property can only be used when the SelectionMode is set to Multiple.

API Notes

Class: TreeView

Member Name Description
SelectedNode Gets or sets the selected TreeViewNode.
SelectedNodes The collection of nodes that are selected in the tree. The default is an empty collection.
SelectedItem Gets or sets the selected item.
SelectedItems The collection of items that are selected in the tree. The default is an empty collection.