Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

TreeView selection API spec #31

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

TreeView selection API spec #31

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a18a7b2
Add TreeView selection api spec
Jun 7, 2019
14ce3a0
Spec updates (#42)
MikeHillberg Aug 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions active/TreeView/TreeViewSelectionAPI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
MikeHillberg marked this conversation as resolved.
Show resolved Hide resolved

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<Object> SelectedItems{ get; };

...
}
}
```

# Examples

```C#
TreeViewNode node = ...
// Set SelectedNode for single selection
treeView.SelectedNode = node;
// Get SelectedNode in single selection
TreeViewNode selectedNode = treeView.SelectedNode;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the value of SelectedNode if SelectedNodes was used to select multiple nodes?

Copy link
Author

@kaiguo kaiguo Aug 5, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the value of SelectedNode if SelectedNodes was used to select multiple nodes?

Currently it returns the first node in SelectedNodes list (maybe it should return the newly selected node which is the last one in list?).

winrt::TreeViewNode TreeView::SelectedNode()
{
    auto nodes = SelectedNodes();
    return nodes.Size() > 0 ? nodes.GetAt(0) : nullptr;
}

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does ListView behave?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ListView returns first item in list too so they are consistent.



TreeViewItemsSourceType item = ...
// Set SelectedItem
treeView.SelectedItem = item;
// Get SelectedItems
TreeViewItemsSourceType selectedItem = treeView.SelectedItem;

// Get SelectedItems collection
IList<Object> 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. |