From a18a7b25e44684c117d9e73cc8464dd60e468e40 Mon Sep 17 00:00:00 2001 From: Kai Guo Date: Fri, 7 Jun 2019 12:11:14 -0700 Subject: [PATCH 1/2] Add TreeView selection api spec --- active/TreeView/TreeViewSelectionAPI.md | 76 +++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 active/TreeView/TreeViewSelectionAPI.md diff --git a/active/TreeView/TreeViewSelectionAPI.md b/active/TreeView/TreeViewSelectionAPI.md new file mode 100644 index 000000000..883907bb5 --- /dev/null +++ b/active/TreeView/TreeViewSelectionAPI.md @@ -0,0 +1,76 @@ +# Background + +`SelectedNodes` is the only API we currently have on TreeView to update selections, and it only works in multi-select mode, which means there's no easy way to programmatically change selections in single selection mode. Also, with the new data binding capability, people would prefer to work on their own data source instead of `TreeViewNode`. With current APIs, they will have to do `ContainerFromItem` and then `NodeFromContainer` to get the associated TreeViewNode in order to update SelectedNodes. + +This API change introduces 3 new APIs to make things easier, `SelectedNode`, `SelectedItem` and `SelectedItems`. + +Related GitHub issues: +https://github.com/microsoft/microsoft-ui-xaml/issues/197 +https://github.com/microsoft/microsoft-ui-xaml/issues/124 +https://github.com/microsoft/microsoft-ui-xaml/issues/386 + +# Description + +Extend TreeView selection API sets to make selections easier. + +- Fix SelectedNodes: Currently this only works in multi-select mode. It should also work in single selection mode (consistent with ListView). +- 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. + +# 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 SelectedItems{ get; }; + + ... + } +} +``` + +# Examples + +```C# +TreeViewNode node = ... +// Set SelectedNode for single selection +treeView.SelectedNode = node; +// Get SelectedNode in single selection +TreeViewNode selectedNode = treeView.SelectedNode; + + +TreeViewItemsSourceType item = ... +// Set SelectedItem +treeView.SelectedItem = item; +// Get SelectedItems +TreeViewItemsSourceType selectedItem = treeView.SelectedItem; + +// Get SelectedItems collection +IList selectedItems = treeView.SelectedItems(); +// Modify the collection to update selections +selectedItems.Add(item); + +``` + +# Remarks + +SelectedNode(s) always returns/takes TreeViewNode. +SelectedItem(s) returns Object(collection of objects), it will be the ItemsSource type object when using databinding, or TreeViewNode when not using databinding. + +# 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. | From 14ce3a02679161b22632d1c1ac71ece4c92934b7 Mon Sep 17 00:00:00 2001 From: MikeHillberg <18429489+MikeHillberg@users.noreply.github.com> Date: Mon, 5 Aug 2019 14:24:35 -0700 Subject: [PATCH 2/2] Spec updates (#42) * Add some more background for those not as familiar with the current TreeView * Update the examples to be close to real-world usage. * Reordered the sections to match the spec template * Explain the SelectedItems behavior change in the Remarks section --- active/TreeView/TreeViewSelectionAPI.md | 70 ++++++++++++++----------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/active/TreeView/TreeViewSelectionAPI.md b/active/TreeView/TreeViewSelectionAPI.md index 883907bb5..869b8b750 100644 --- a/active/TreeView/TreeViewSelectionAPI.md +++ b/active/TreeView/TreeViewSelectionAPI.md @@ -1,8 +1,12 @@ # Background -`SelectedNodes` is the only API we currently have on TreeView to update selections, and it only works in multi-select mode, which means there's no easy way to programmatically change selections in single selection mode. Also, with the new data binding capability, people would prefer to work on their own data source instead of `TreeViewNode`. With current APIs, they will have to do `ContainerFromItem` and then `NodeFromContainer` to get the associated TreeViewNode in order to update SelectedNodes. +The Xaml [TreeView](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.TreeView) control shows a list of hierarchical data, similar to a ListView. -This API change introduces 3 new APIs to make things easier, `SelectedNode`, `SelectedItem` and `SelectedItems`. +When TreeView was first released, you populated it using the [RootNode property](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.TreeView.RootNodes), 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](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.ItemsControl.ItemsSource). + +So a [TreeView.ItemsSource](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.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](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.TreeView.SelectedNodes) property today, and this spec is adding a singular SelectedNode property. Related GitHub issues: https://github.com/microsoft/microsoft-ui-xaml/issues/197 @@ -13,10 +17,38 @@ https://github.com/microsoft/microsoft-ui-xaml/issues/386 Extend TreeView selection API sets to make selections easier. -- Fix SelectedNodes: Currently this only works in multi-select mode. It should also work in single selection mode (consistent with ListView). -- 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. +- 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](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.TreeView.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. +```C# +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. +```Xaml + +``` + +## TreeView.SelectedItems +```C# +void AddToSelection(TreeView treeView, object item) +{ + IList selectedItems = treeView.SelectedItems; + selectedItems.Add(item); +} +``` # API Details @@ -37,34 +69,12 @@ namespace Microsoft.UI.Xaml.Controls } ``` -# Examples - -```C# -TreeViewNode node = ... -// Set SelectedNode for single selection -treeView.SelectedNode = node; -// Get SelectedNode in single selection -TreeViewNode selectedNode = treeView.SelectedNode; - - -TreeViewItemsSourceType item = ... -// Set SelectedItem -treeView.SelectedItem = item; -// Get SelectedItems -TreeViewItemsSourceType selectedItem = treeView.SelectedItem; - -// Get SelectedItems collection -IList selectedItems = treeView.SelectedItems(); -// Modify the collection to update selections -selectedItems.Add(item); - -``` - # Remarks -SelectedNode(s) always returns/takes TreeViewNode. 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](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.TreeView.SelectedNodes) property can only be used when the [SelectionMode](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.TreeView.SelectionMode) is set to `Multiple`. + # API Notes ## Class: TreeView