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

Porting AdvancedCollectionView #72

Merged
merged 10 commits into from
Jun 2, 2023
Merged

Porting AdvancedCollectionView #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
41989fd
Init
niels9001 May 26, 2023
814bab8
Removing generic.xaml
niels9001 May 26, 2023
e8b96ce
XAML styling
niels9001 May 26, 2023
86a09f7
Bump version number
niels9001 May 26, 2023
2d5e5db
Merge branch 'main' into niels9001/advancedcollectionview
niels9001 May 30, 2023
bee3fbd
Update tooling
niels9001 May 30, 2023
bd67d0c
Suppress CA1033
Arlodotexe Jun 1, 2023
360665a
Suppress CA1063 in whole file
Arlodotexe Jun 2, 2023
4bce645
Suppress CA1001 with attribute to handle partials
Arlodotexe Jun 2, 2023
798f3b1
Additional CA1001 suppression
Arlodotexe Jun 2, 2023
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
3 changes: 3 additions & 0 deletions components/AdvancedCollectionView/OpenSolution.bat
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
@ECHO OFF

powershell ..\..\tooling\ProjectHeads\GenerateSingleSampleHeads.ps1 -componentPath %CD% %*
8 changes: 8 additions & 0 deletions components/AdvancedCollectionView/samples/AdvancedCollectionView.Samples.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<Project Sdk="MSBuild.Sdk.Extras/3.0.23">
<PropertyGroup>
<ToolkitComponentName>AdvancedCollectionView</ToolkitComponentName>
</PropertyGroup>

<!-- Sets this up as a toolkit component's sample project -->
<Import Project="$(ToolingDirectory)\ToolkitComponent.SampleProject.props" />
</Project>
152 changes: 152 additions & 0 deletions components/AdvancedCollectionView/samples/AdvancedCollectionView.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
---
title: AdvancedCollectionView
author: nmetulev
description: The AdvancedCollectionView is a collection view implementation that support filtering, sorting and incremental loading. It's meant to be used in a viewmodel.
keywords: AdvancedCollectionView, data, sorting, filtering
dev_langs:
- csharp
category: Controls
subcategory: Layout
discussion-id: 0
issue-id: 0
---

# AdvancedCollectionView

The [AdvancedCollectionView](/dotnet/api/microsoft.toolkit.uwp.ui.advancedcollectionview) is a collection view implementation that support filtering, sorting and incremental loading. It's meant to be used in a viewmodel.

> [!Sample AdvancedCollectionViewSample]

## Usage

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:

* sorting your list using the `SortDirection` helper: specify any number of property names to sort on with the direction desired
* 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
* 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
* incremental loading: if your source collection supports the feature then AdvancedCollectionView will do as well (it simply forwards the calls)
* 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`

## Example

```csharp
using Microsoft.Toolkit.Uwp.UI;

// Grab a sample type
public class Person
{
public string Name { get; set; }
}

// Set up the original list with a few sample items
var oc = new ObservableCollection<Person>
{
new Person { Name = "Staff" },
new Person { Name = "42" },
new Person { Name = "Swan" },
new Person { Name = "Orchid" },
new Person { Name = "15" },
new Person { Name = "Flame" },
new Person { Name = "16" },
new Person { Name = "Arrow" },
new Person { Name = "Tempest" },
new Person { Name = "23" },
new Person { Name = "Pearl" },
new Person { Name = "Hydra" },
new Person { Name = "Lamp Post" },
new Person { Name = "4" },
new Person { Name = "Looking Glass" },
new Person { Name = "8" },
};

// Set up the AdvancedCollectionView with live shaping enabled to filter and sort the original list
var acv = new AdvancedCollectionView(oc, true);

// Let's filter out the integers
int nul;
acv.Filter = x => !int.TryParse(((Person)x).Name, out nul);

// And sort ascending by the property "Name"
acv.SortDescriptions.Add(new SortDescription("Name", SortDirection.Ascending));

// Let's add a Person to the observable collection
var person = new Person { Name = "Aardvark" };
oc.Add(person);

// Our added person is now at the top of the list, but if we rename this person, we can trigger a re-sort
person.Name = "Zaphod"; // Now a re-sort is triggered and person will be last in the list

// AdvancedCollectionView can be bound to anything that uses collections.
YourListView.ItemsSource = acv;
```

## Properties

| Property | Type | Description |
| -- | -- | -- |
| CanFilter | bool | Gets a value indicating whether this CollectionView can filter its items |
| CanSort | bool | Gets a value indicating whether this CollectionView can sort its items |
| CollectionGroups | IObservableVector\<object> | Gets the groups in collection |
| Count | int | Get the count of items |
| CurrentItem | object | Gets or sets the current item |
| CurrentPosition | int | Gets the position of current item |
| Filter | Predicate\<object> | Gets or sets the predicate used to filter the visible items |
| HasMoreItems | bool | Gets a value indicating whether the source has more items |
| IsCurrentAfterLast | bool | Gets a value indicating whether the current item is after the last visible item |
| IsCurrentBeforeFirst | bool | Gets a value indicating whether the current item is before the first visible item |
| IsReadOnly | bool | Get a value indicating whether this CollectionView is read only |
| SortDescriptions | IList<[SortDescription](/dotnet/api/microsoft.toolkit.uwp.ui.sortdescription)> | Gets SortDescriptions to sort the visible items |
| Source | IEnumerable | Gets or sets the source |
| SourceCollection | IEnumerable | Gets the source collection |
| this[int] | int | Gets or sets the element at the specified index |

## Methods

| Methods | Return Type | Description |
| -- | -- | -- |
| Add(Object) | void | Add item |
| Clear() | void | Clear item |
| Contains(Object) | bool | Returns `true` if the given item contained in CollectionView |
| B(float, string) | int | Description |
| DeferRefresh() | IDisposable | Stops refreshing until it is disposed |
| IndexOf(Object) | int | Return index of an item |
| Insert(Int32, Object) | void | Insert an item in a particular place |
| LoadMoreItemsAsync(UInt32) | IAsyncOperation<[LoadMoreItemsResult](/uwp/api/Windows.UI.Xaml.Data.LoadMoreItemsResult)> | Load more items from the source |
| MoveCurrentTo(Object) | bool | Move current index to item. Returns success of operation |
| MoveCurrentToFirst() | bool | Move current item to first item. Returns success of operation |
| MoveCurrentToLast() | bool | Move current item to last item. Returns success of operation |
| MoveCurrentToNext() | bool | Move current item to next item |
| MoveCurrentToPosition(Int32) | bool | Moves selected item to position |
| MoveCurrentToPrevious() | bool | Move current item to previous item |
| Refresh() | void | Manually refresh the view |
| Remove(Object) | bool | Remove item |
| RemoveAt(Int32) | bool | Remove item with index |

## Events

| Events | Description |
| -- | -- |
| CurrentChanged | Current item changed event handler |
| CurrentChanging | Current item changing event handler |
| PropertyChanged | Occurs when a property value changes |
| VectorChanged | Occurs when the vector changes |

## Remarks

_What source can I use?_

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.

_Any performance guidelines?_

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.

```csharp
using (acv.DeferRefresh())
{
for (var i = 0; i < 500; i++)
{
acv.Add(new Person { Name = "defer" });
}
} // acv.Refresh() gets called here
```
73 changes: 73 additions & 0 deletions components/AdvancedCollectionView/samples/AdvancedCollectionViewSample.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
// 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.

using CommunityToolkit.WinUI;

namespace AdvancedCollectionViewExperiment.Samples;

[ToolkitSample(id: nameof(AdvancedCollectionViewSample), "AdvancedCollectionView", description: $"A sample for showing how to create and use a {nameof(AdvancedCollectionView)}.")]
public sealed partial class AdvancedCollectionViewSample : Page
{
public ObservableCollection<Person>? oc;

public AdvancedCollectionViewSample()
{
this.InitializeComponent();
Setup();
}

private void Setup()
{
// left list
oc = new ObservableCollection<Person>
{
new Person { Name = "Staff" },
new Person { Name = "42" },
new Person { Name = "Swan" },
new Person { Name = "Orchid" },
new Person { Name = "15" },
new Person { Name = "Flame" },
new Person { Name = "16" },
new Person { Name = "Arrow" },
new Person { Name = "Tempest" },
new Person { Name = "23" },
new Person { Name = "Pearl" },
new Person { Name = "Hydra" },
new Person { Name = "Lamp Post" },
new Person { Name = "4" },
new Person { Name = "Looking Glass" },
new Person { Name = "8" },
};

LeftList.ItemsSource = oc;

// right list
var acv = new AdvancedCollectionView(oc);
int nul;
acv.Filter = x => !int.TryParse(((Person)x).Name, out nul);
acv.SortDescriptions.Add(new SortDescription("Name", SortDirection.Ascending));

RightList.ItemsSource = acv;
}

private void Add_Click(object sender, RoutedEventArgs e)
{
if (!string.IsNullOrWhiteSpace(NewItemBox.Text))
{
oc!.Insert(0, new Person { Name = NewItemBox.Text });
NewItemBox.Text = "";
}
}

/// <summary>
/// A sample class used to show how to use the <see cref="Collections.IIncrementalSource{TSource}"/> interface.
/// </summary>
public class Person
{
/// <summary>
/// Gets or sets the name of the person.
/// </summary>
public string? Name { get; set; }
}
}
67 changes: 67 additions & 0 deletions components/AdvancedCollectionView/samples/AdvancedCollectionViewSample.xaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
<!-- 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. -->
<Page x:Class="AdvancedCollectionViewExperiment.Samples.AdvancedCollectionViewSample"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:controls="using:CommunityToolkit.WinUI"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:local="using:AdvancedCollectionViewExperiment.Samples"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d">

<Page.Resources>
<Style x:Name="CardStyle"
TargetType="Grid">
<Style.Setters>
<Setter Property="Background" Value="{ThemeResource CardBackgroundFillColorDefaultBrush}" />
<Setter Property="BorderBrush" Value="{ThemeResource CardStrokeColorDefaultBrush}" />
<Setter Property="BorderThickness" Value="1" />
<Setter Property="CornerRadius" Value="{StaticResource ControlCornerRadius}" />
</Style.Setters>
</Style>
<DataTemplate x:Key="PersonDataTemplate">
<TextBlock Text="{Binding Name}" />
</DataTemplate>
</Page.Resources>
<Grid ColumnSpacing="12"
RowSpacing="8">
<Grid.ColumnDefinitions>
<ColumnDefinition />
<ColumnDefinition />
</Grid.ColumnDefinitions>
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition />
</Grid.RowDefinitions>
<StackPanel Grid.Column="0"
Grid.ColumnSpan="2"
Margin="0,24,0,24"
Orientation="Horizontal"
Spacing="8">
<TextBox x:Name="NewItemBox"
MinWidth="320"
PlaceholderText="Add new item" />
<Button x:Name="AddButton"
VerticalAlignment="Bottom"
Click="Add_Click"
Content="Add"
Style="{StaticResource AccentButtonStyle}" />
</StackPanel>
<TextBlock Grid.Row="1"
Text="Original list" />
<Grid Grid.Row="2"
Style="{StaticResource CardStyle}">
<ListView x:Name="LeftList"
ItemTemplate="{StaticResource PersonDataTemplate}" />
</Grid>
<TextBlock Grid.Row="1"
Grid.Column="1"
Text="Sorted and filtered list (bound via AdvancedCollectionView)" />
<Grid Grid.Row="2"
Grid.Column="1"
Style="{StaticResource CardStyle}">
<ListView x:Name="RightList"
ItemTemplate="{StaticResource PersonDataTemplate}" />
</Grid>
</Grid>
</Page>
31 changes: 31 additions & 0 deletions components/AdvancedCollectionView/samples/Dependencies.props
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!--
WinUI 2 under UWP uses TargetFramework uap10.0.*
WinUI 3 under WinAppSdk uses TargetFramework net6.0-windows10.*
However, under Uno-powered platforms, both WinUI 2 and 3 can share the same TargetFramework.

MSBuild doesn't play nicely with this out of the box, so we've made it easy for you.

For .NET Standard packages, you can use the Nuget Package Manager in Visual Studio.
For UWP / WinAppSDK / Uno packages, place the package references here.
-->
<Project>
<!-- WinUI 2 / UWP -->
<ItemGroup Condition="'$(IsUwp)' == 'true'">
<!-- <PackageReference Include="Microsoft.Toolkit.Uwp.UI.Controls.Primitives" Version="7.1.2"/> -->
</ItemGroup>

<!-- WinUI 2 / Uno -->
<ItemGroup Condition="'$(IsUno)' == 'true' AND '$(WinUIMajorVersion)' == '2'">
<!-- <PackageReference Include="Uno.Microsoft.Toolkit.Uwp.UI.Controls.Primitives" Version="7.1.11"/> -->
</ItemGroup>

<!-- WinUI 3 / WinAppSdk -->
<ItemGroup Condition="'$(IsWinAppSdk)' == 'true'">
<!-- <PackageReference Include="CommunityToolkit.WinUI.UI.Controls.Primitives" Version="7.1.2"/> -->
</ItemGroup>

<!-- WinUI 3 / Uno -->
<ItemGroup Condition="'$(IsUno)' == 'true' AND '$(WinUIMajorVersion)' == '3'">
<!-- <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls.Primitives" Version="7.1.100-dev.15.g12261e2626"/> -->
</ItemGroup>
</Project>
Loading