Skip to content

Commit be4577e

Browse files
authored
Collections component (#123)
* New Collections component * Removing IncrementalLoadingCollection and AdvanctedCollectionView components * Fix namespaces
1 parent 3decd11 commit be4577e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+154
-372
lines changed

components/AdvancedCollectionView/samples/AdvancedCollectionView.Samples.csproj

Lines changed: 0 additions & 8 deletions
This file was deleted.

components/AdvancedCollectionView/samples/AdvancedCollectionView.md

Lines changed: 0 additions & 149 deletions
This file was deleted.
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: AdvancedCollectionView
3+
author: nmetulev
4+
description: The AdvancedCollectionView is a collection view implementation that support filtering, sorting and incremental loading. It's meant to be used in a viewmodel.
5+
keywords: AdvancedCollectionView, data, sorting, filtering
6+
dev_langs:
7+
- csharp
8+
category: Helpers
9+
subcategory: Data
10+
discussion-id: 0
11+
issue-id: 0
12+
icon: Assets/AdvancedCollectionView.png
13+
---
14+
15+
> [!Sample AdvancedCollectionViewSample]
16+
17+
## Usage
18+
19+
In your viewmodel instead of having a public [IEnumerable](/dotnet/core/api/system.collections.generic.ienumerable-1) of some sort to be bound to an eg. [Listview](/uwp/api/Windows.UI.Xaml.Controls.ListView), create a public AdvancedCollectionView and pass your list in the constructor to it. If you've done that you can use the many useful features it provides:
20+
21+
* sorting your list using the `SortDirection` helper: specify any number of property names to sort on with the direction desired
22+
* filtering your list using a [Predicate](/dotnet/core/api/system.predicate-1): this will automatically filter your list only to the items that pass the check by the predicate provided
23+
* deferring notifications using the `NotificationDeferrer` helper: with a convenient _using_ pattern you can increase performance while doing large-scale modifications in your list by waiting with updates until you've completed your work
24+
* incremental loading: if your source collection supports the feature then AdvancedCollectionView will do as well (it simply forwards the calls)
25+
* live shaping: when constructing the `AdvancedCollectionView` you may specify that the collection use live shaping. This means that the collection will re-filter or re-sort if there are changes to the sort properties or filter properties that are specified using `ObserveFilterProperty`
26+
27+
## Example
28+
29+
```csharp
30+
using Microsoft.Toolkit.Uwp.UI;
31+
32+
// Grab a sample type
33+
public class Person
34+
{
35+
public string Name { get; set; }
36+
}
37+
38+
// Set up the original list with a few sample items
39+
var oc = new ObservableCollection<Person>
40+
{
41+
new Person { Name = "Staff" },
42+
new Person { Name = "42" },
43+
new Person { Name = "Swan" },
44+
new Person { Name = "Orchid" },
45+
new Person { Name = "15" },
46+
new Person { Name = "Flame" },
47+
new Person { Name = "16" },
48+
new Person { Name = "Arrow" },
49+
new Person { Name = "Tempest" },
50+
new Person { Name = "23" },
51+
new Person { Name = "Pearl" },
52+
new Person { Name = "Hydra" },
53+
new Person { Name = "Lamp Post" },
54+
new Person { Name = "4" },
55+
new Person { Name = "Looking Glass" },
56+
new Person { Name = "8" },
57+
};
58+
59+
// Set up the AdvancedCollectionView with live shaping enabled to filter and sort the original list
60+
var acv = new AdvancedCollectionView(oc, true);
61+
62+
// Let's filter out the integers
63+
int nul;
64+
acv.Filter = x => !int.TryParse(((Person)x).Name, out nul);
65+
66+
// And sort ascending by the property "Name"
67+
acv.SortDescriptions.Add(new SortDescription("Name", SortDirection.Ascending));
68+
69+
// Let's add a Person to the observable collection
70+
var person = new Person { Name = "Aardvark" };
71+
oc.Add(person);
72+
73+
// Our added person is now at the top of the list, but if we rename this person, we can trigger a re-sort
74+
person.Name = "Zaphod"; // Now a re-sort is triggered and person will be last in the list
75+
76+
// AdvancedCollectionView can be bound to anything that uses collections.
77+
YourListView.ItemsSource = acv;
78+
```
79+
80+
## Remarks
81+
82+
_What source can I use?_
83+
84+
It's not necessary to use an eg. [ObservableCollection](/dotnet/core/api/system.collections.objectmodel.observablecollection-1) to use the AdvancedCollectionView. It works as expected even when providing a simple [List](/dotnet/core/api/system.collections.generic.list-1) in the constructor.
85+
86+
_Any performance guidelines?_
87+
88+
If you're removing, modifying or inserting large amounts of items while having filtering and/or sorting set up, it's recommended that you use the `NotificationDeferrer` helper provided. It skips any performance heavy logic while it's in use, and automatically calls the `Refresh` method when disposed.
89+
90+
```csharp
91+
using (acv.DeferRefresh())
92+
{
93+
for (var i = 0; i < 500; i++)
94+
{
95+
acv.Add(new Person { Name = "defer" });
96+
}
97+
} // acv.Refresh() gets called here
98+
```

components/AdvancedCollectionView/samples/AdvancedCollectionViewSample.xaml renamed to components/Collections/samples/AdvancedCollectionViewSample.xaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!-- Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information. -->
2-
<Page x:Class="AdvancedCollectionViewExperiment.Samples.AdvancedCollectionViewSample"
2+
<Page x:Class="CollectionsExperiment.Samples.AdvancedCollectionViewSample"
33
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
44
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
55
xmlns:controls="using:CommunityToolkit.WinUI"

components/AdvancedCollectionView/samples/AdvancedCollectionViewSample.cs renamed to components/Collections/samples/AdvancedCollectionViewSample.xaml.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
using CommunityToolkit.WinUI;
66

7-
namespace AdvancedCollectionViewExperiment.Samples;
7+
namespace CollectionsExperiment.Samples;
88

99
[ToolkitSample(id: nameof(AdvancedCollectionViewSample), "AdvancedCollectionView", description: $"A sample for showing how to create and use a {nameof(AdvancedCollectionView)}.")]
1010
public sealed partial class AdvancedCollectionViewSample : Page
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<Project Sdk="MSBuild.Sdk.Extras/3.0.23">
22
<PropertyGroup>
3-
<ToolkitComponentName>IncrementalLoadingCollection</ToolkitComponentName>
3+
<ToolkitComponentName>Collections</ToolkitComponentName>
44
</PropertyGroup>
55

66
<!-- Sets this up as a toolkit component's sample project -->

0 commit comments

Comments
 (0)