Skip to content

Commit 744e6ab

Browse files
niels9001Arlodotexe
niels9001
authored and
Arlodotexe
committed
Adding samples
1 parent d88d444 commit 744e6ab

13 files changed

+765
-267
lines changed

‎components/IncrementalLoadingCollection/samples/Assets/AppIcon.png‎

1.32 KB
Loading

‎components/IncrementalLoadingCollection/samples/IncrementalLoadingCollection.Samples.csproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,12 @@
55

66
<!-- Sets this up as a toolkit component's sample project -->
77
<Import Project="$(ToolingDirectory)\ToolkitComponent.SampleProject.props" />
8+
<ItemGroup>
9+
<None Remove="Assets\AppIcon.png" />
10+
</ItemGroup>
11+
<ItemGroup>
12+
<Content Include="Assets\AppIcon.png">
13+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
14+
</Content>
15+
</ItemGroup>
816
</Project>

‎components/IncrementalLoadingCollection/samples/IncrementalLoadingCollection.md‎

Lines changed: 78 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
title: IncrementalLoadingCollection
3-
author: githubaccount
4-
description: TODO: Your experiment's description here
5-
keywords: IncrementalLoadingCollection, Control, Layout
3+
author: nmetulev
4+
description: The IncrementalLoadingCollection helpers greatly simplify the definition and usage of collections whose items can be loaded incrementally only when needed by the view
5+
keywords: IncrementalLoadingCollection, Control, Data, Incremental, Loading
66
dev_langs:
77
- csharp
88
category: Controls
@@ -11,22 +11,85 @@ discussion-id: 0
1111
issue-id: 0
1212
---
1313

14-
<!-- To know about all the available Markdown syntax, Check out https://docs.microsoft.com/contribute/markdown-reference -->
15-
<!-- Ensure you remove all comments before submission, to ensure that there are no formatting issues when displaying this page. -->
16-
<!-- It is recommended to check how the Documentation will look in the sample app, before Merging a PR -->
17-
<!-- **Note:** All links to other docs.microsoft.com pages should be relative without locale, i.e. for the one above would be /contribute/markdown-reference -->
18-
<!-- Included images should be optimized for size and not include any Intellectual Property references. -->
14+
# Incremental Loading Collection Helpers
1915

20-
<!-- Be sure to update the discussion/issue numbers above with your Labs discussion/issue id numbers in order for UI links to them from the sample app to work. -->
16+
The **IncrementalLoadingCollection** helpers greatly simplify the definition and usage of collections whose items can be loaded incrementally only when needed by the view, i.e., when user scrolls a [ListView](/uwp/api/Windows.UI.Xaml.Controls.ListView) or a [GridView](/uwp/api/Windows.UI.Xaml.Controls.GridView).
2117

22-
# IncrementalLoadingCollection
18+
> [!Sample IncrementalLoadingCollectionSample]
2319
24-
TODO: Fill in information about this experiment and how to get started here...
20+
[IIncrementalSource](/dotnet/api/microsoft.toolkit.collections.iincrementalsource-1) - An interface that represents a data source whose items can be loaded incrementally.
2521

26-
## Custom Control
22+
[IncrementalLoadingCollection](/dotnet/api/microsoft.toolkit.uwp.incrementalloadingcollection-2) - An extension of [ObservableCollection](/dotnet/api/system.collections.objectmodel.observablecollection-1) such that its items are loaded only when needed.
2723

28-
You can inherit from an existing component as well, like `Panel`, this example shows a control without a
29-
XAML Style that will be more light-weight to consume by an app developer:
24+
## IncrementalLoadingCollection Properties
3025

31-
> [!Sample IncrementalLoadingCollectionCustomSample]
26+
| Property | Type | Description |
27+
| -- | -- | -- |
28+
| CurrentPageIndex | int | Gets or sets a value indicating The zero-based index of the current items page |
29+
| HasMoreItems | bool | Gets a value indicating whether the collection contains more items to retrieve |
30+
| IsLoading | bool | Gets a value indicating whether new items are being loaded |
31+
| ItemsPerPage | int | Gets a value indicating how many items that must be retrieved for each incremental call |
32+
| OnEndLoading | [Action](/dotnet/api/system.action) | Gets or sets an Action that is called when a retrieval operation ends |
33+
| OnError | Action\<Exception> | Gets or sets an Action that is called if an error occours during data retrieval. The actual Exception is passed as an argument |
34+
| OnStartLoading | Action | Gets or sets an Action that is called when a retrieval operation begins |
3235

36+
## IncrementalLoadingCollection Methods
37+
38+
| Methods | Return Type | Description |
39+
| -- | -- | -- |
40+
| LoadDataAsync(CancellationToken) | Task<IEnumerable\<IType>> | Actually performs the incremental loading |
41+
| LoadMoreItemsAsync(UInt32) | IAsyncOperation\<LoadMoreItemsResult> | Initializes incremental loading from the view |
42+
| Refresh() | void | Clears the collection and resets the page index which triggers an automatic reload of the first page |
43+
| RefreshAsync() | Task | Clears the collection and reloads data from the source |
44+
45+
## Example
46+
47+
`IIncrementalSource` allows to define the data source:
48+
49+
```csharp
50+
// Be sure to include the using at the top of the file:
51+
//using CommunityToolkit.WinUI;
52+
53+
public class Person
54+
{
55+
public string Name { get; set; }
56+
}
57+
58+
public class PeopleSource : IIncrementalSource<Person>
59+
{
60+
private readonly List<Person> people;
61+
62+
public PeopleSource()
63+
{
64+
// Creates an example collection.
65+
people = new List<Person>();
66+
67+
for (int i = 1; i <= 200; i++)
68+
{
69+
var p = new Person { Name = "Person " + i };
70+
people.Add(p);
71+
}
72+
}
73+
74+
public async Task<IEnumerable<Person>> GetPagedItemsAsync(int pageIndex, int pageSize)
75+
{
76+
// Gets items from the collection according to pageIndex and pageSize parameters.
77+
var result = (from p in people
78+
select p).Skip(pageIndex * pageSize).Take(pageSize);
79+
80+
// Simulates a longer request...
81+
await Task.Delay(1000);
82+
83+
return result;
84+
}
85+
}
86+
```
87+
88+
The *GetPagedItemsAsync* method is invoked every time the view need to show more items.
89+
90+
`IncrementalLoadingCollection` can then be bound to a [ListView](/uwp/api/Windows.UI.Xaml.Controls.ListView) or a [GridView-like](/uwp/api/Windows.UI.Xaml.Controls.GridView) control:
91+
92+
```csharp
93+
var collection = new IncrementalLoadingCollection<PeopleSource, Person>();
94+
PeopleListView.ItemsSource = collection;
95+
```

‎components/IncrementalLoadingCollection/samples/IncrementalLoadingCollectionSample.xaml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
<!-- 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="IncrementalLoadingCollectionExperiment.Samples.IncrementalLoadingCollectionSample"
3+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
4+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
5+
xmlns:controls="using:CommunityToolkit.WinUI"
6+
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
7+
xmlns:local="using:IncrementalLoadingCollectionExperiment.Samples"
8+
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
9+
mc:Ignorable="d">
10+
11+
<Grid MaxWidth="460"
12+
HorizontalAlignment="Left">
13+
<Grid.RowDefinitions>
14+
<RowDefinition Height="Auto" />
15+
<RowDefinition Height="Auto" />
16+
<RowDefinition Height="*" />
17+
</Grid.RowDefinitions>
18+
19+
<StackPanel HorizontalAlignment="Left">
20+
<TextBlock Text="Items are loaded incrementally when the view needs to show them (i.e., when the user scrolls the ListView)"
21+
TextWrapping="Wrap" />
22+
<Button Margin="0,12,0,12"
23+
Click="RefreshCollection"
24+
Content="Refresh collection"
25+
Style="{StaticResource AccentButtonStyle}" />
26+
<TextBlock>
27+
<Run Text="Is loading:" />
28+
<Run FontWeight="SemiBold"
29+
Text="{Binding IsLoading, Mode=OneWay}" />
30+
</TextBlock>
31+
<TextBlock>
32+
<Run Text="Has more items:" />
33+
<Run FontWeight="SemiBold"
34+
Text="{Binding HasMoreItems, Mode=OneWay}" />
35+
</TextBlock>
36+
37+
</StackPanel>
38+
39+
<Grid Grid.Row="2"
40+
MaxHeight="420"
41+
Margin="0,24,0,0"
42+
VerticalAlignment="Top"
43+
Background="{ThemeResource CardBackgroundFillColorDefaultBrush}"
44+
BorderBrush="{ThemeResource CardStrokeColorDefaultBrush}"
45+
BorderThickness="1"
46+
CornerRadius="4">
47+
<ListView x:Name="PeopleListView">
48+
<ListView.ItemTemplate>
49+
<DataTemplate>
50+
<Grid>
51+
<Grid.ColumnDefinitions>
52+
<ColumnDefinition Width="Auto" />
53+
<ColumnDefinition />
54+
</Grid.ColumnDefinitions>
55+
<Image Width="24"
56+
Height="24"
57+
VerticalAlignment="Center"
58+
Source="ms-appx:///Assets/AppIcon.png" />
59+
<TextBlock Grid.Column="1"
60+
Margin="12"
61+
VerticalAlignment="Center"
62+
Text="{Binding Name}" />
63+
</Grid>
64+
</DataTemplate>
65+
</ListView.ItemTemplate>
66+
</ListView>
67+
</Grid>
68+
</Grid>
69+
</Page>

‎components/IncrementalLoadingCollection/samples/IncrementalLoadingCollectionSample.xaml.cs‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
5+
using CommunityToolkit.WinUI;
6+
7+
namespace IncrementalLoadingCollectionExperiment.Samples;
8+
9+
[ToolkitSample(id: nameof(IncrementalLoadingCollectionSample), "Incremental Loading Collection", description: $"A sample for showing how to create and use a IncrementalLoadingCollection.")]
10+
public sealed partial class IncrementalLoadingCollectionSample : Page
11+
{
12+
public IncrementalLoadingCollectionSample()
13+
{
14+
this.InitializeComponent();
15+
Load();
16+
}
17+
private void Load()
18+
{
19+
// IncrementalLoadingCollection can be bound to a GridView or a ListView. In this case it is a ListView called PeopleListView.
20+
var collection = new IncrementalLoadingCollection<PeopleSource, Person>();
21+
PeopleListView.ItemsSource = collection;
22+
23+
// Binds the collection to the page DataContext in order to use its IsLoading and HasMoreItems properties.
24+
DataContext = collection;
25+
}
26+
27+
private async void RefreshCollection(object sender, RoutedEventArgs e)
28+
{
29+
var collection = (IncrementalLoadingCollection<PeopleSource, Person>)PeopleListView.ItemsSource;
30+
await collection.RefreshAsync();
31+
}
32+
}

‎components/IncrementalLoadingCollection/samples/PeopleSource.cs‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
5+
using CommunityToolkit.WinUI;
6+
7+
namespace IncrementalLoadingCollectionExperiment.Samples;
8+
9+
/// <summary>
10+
/// A sample implementation of the <see cref="Collections.IIncrementalSource{TSource}"/> interface.
11+
/// </summary>
12+
/// <seealso cref="Collections.IIncrementalSource{TSource}"/>
13+
public class PeopleSource : IIncrementalSource<Person>
14+
{
15+
private readonly List<Person> _people;
16+
17+
/// <summary>
18+
/// Initializes a new instance of the <see cref="PeopleSource"/> class.
19+
/// </summary>
20+
public PeopleSource()
21+
{
22+
// Creates an example collection.
23+
_people = new List<Person>();
24+
25+
for (int i = 1; i <= 200; i++)
26+
{
27+
var p = new Person { Name = "Person " + i };
28+
_people.Add(p);
29+
}
30+
}
31+
32+
/// <summary>
33+
/// Retrieves items based on <paramref name="pageIndex"/> and <paramref name="pageSize"/> arguments.
34+
/// </summary>
35+
/// <param name="pageIndex">
36+
/// The zero-based index of the page that corresponds to the items to retrieve.
37+
/// </param>
38+
/// <param name="pageSize">
39+
/// The number of <see cref="Person"/> items to retrieve for the specified <paramref name="pageIndex"/>.
40+
/// </param>
41+
/// <param name="cancellationToken">
42+
/// Used to propagate notification that operation should be canceled.
43+
/// </param>
44+
/// <returns>
45+
/// Returns a collection of <see cref="Person"/>.
46+
/// </returns>
47+
public async Task<IEnumerable<Person>> GetPagedItemsAsync(int pageIndex, int pageSize, CancellationToken cancellationToken = default(CancellationToken))
48+
{
49+
// Gets items from the collection according to pageIndex and pageSize parameters.
50+
var result = (from p in _people
51+
select p).Skip(pageIndex * pageSize).Take(pageSize);
52+
53+
// Simulates a longer request...
54+
// Make sure the list is still in order after a refresh,
55+
// even if the first page takes longer to load
56+
if (pageIndex == 0)
57+
{
58+
await Task.Delay(2000);
59+
}
60+
else
61+
{
62+
await Task.Delay(1000);
63+
}
64+
65+
return result;
66+
}
67+
}

‎components/IncrementalLoadingCollection/samples/Person.cs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
5+
namespace IncrementalLoadingCollectionExperiment.Samples;
6+
7+
/// <summary>
8+
/// A sample class used to show how to use the <see cref="Collections.IIncrementalSource{TSource}"/> interface.
9+
/// </summary>
10+
public class Person
11+
{
12+
/// <summary>
13+
/// Gets or sets the name of the person.
14+
/// </summary>
15+
public string? Name { get; set; }
16+
}

‎components/IncrementalLoadingCollection/src/CommunityToolkit.WinUI.IncrementalLoadingCollection.csproj‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<Project Sdk="MSBuild.Sdk.Extras/3.0.23">
2+
<PropertyGroup>
3+
<ToolkitComponentName>IncrementalLoadingCollection</ToolkitComponentName>
4+
<Description>This package contains IncrementalLoadingCollection.</Description>
5+
<Version>0.0.1</Version>
6+
7+
<!-- Rns suffix is required for namespaces shared across projects. See https://github.com/CommunityToolkit/Labs-Windows/issues/152 -->
8+
<RootNamespace>CommunityToolkit.WinUI.IncrementalLoadingCollectionRns</RootNamespace>
9+
</PropertyGroup>
10+
11+
<!-- Sets this up as a toolkit component's source project -->
12+
<Import Project="$(ToolingDirectory)\ToolkitComponent.SourceProject.props" />
13+
</Project>

‎components/IncrementalLoadingCollection/src/IIncrementalSource.cs‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
5+
namespace CommunityToolkit.WinUI;
6+
7+
/// <summary>
8+
/// This interface represents a data source whose items can be loaded incrementally.
9+
/// </summary>
10+
/// <typeparam name="TSource">Type of collection element.</typeparam>
11+
public interface IIncrementalSource<TSource>
12+
{
13+
/// <summary>
14+
/// This method is invoked every time the view need to show more items. Retrieves items based on <paramref name="pageIndex"/> and <paramref name="pageSize"/> arguments.
15+
/// </summary>
16+
/// <param name="pageIndex">
17+
/// The zero-based index of the page that corresponds to the items to retrieve.
18+
/// </param>
19+
/// <param name="pageSize">
20+
/// The number of <typeparamref name="TSource"/> items to retrieve for the specified <paramref name="pageIndex"/>.
21+
/// </param>
22+
/// <param name="cancellationToken">
23+
/// Used to propagate notification that operation should be canceled.
24+
/// </param>
25+
/// <returns>
26+
/// Returns a collection of <typeparamref name="TSource"/>.
27+
/// </returns>
28+
Task<IEnumerable<TSource>> GetPagedItemsAsync(int pageIndex, int pageSize, CancellationToken cancellationToken = default);
29+
}

0 commit comments

Comments
 (0)