Skip to content

Commit 13bcf22

Browse files
XAML-KnightXAML-Knight
authored
Merge pull request #314 from Vijay-Nirmal/SmoothScrollIntoView
Documentation for SmoothScrollIntoView ListView Extension
2 parents 4cbc1f5 + 902f51f commit 13bcf22

File tree

3 files changed

+215
-101
lines changed

3 files changed

+215
-101
lines changed

‎docs/extensions/ListViewExtensions.md‎

Lines changed: 215 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,215 @@
1-
---
2-
title: ListViewExtensions
3-
author: nmetulev
4-
description: ListViewExtensions extensions provide a lightweight way to extend every control that inherits the ListViewBase class with attached properties.
5-
keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, ListViewBase, extensions
6-
---
7-
8-
# ListViewExtensions
9-
10-
The [`ListViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.listviewextensions) class provide a lightweight way to extend every control that inherits the [`ListViewBase`](/uwp/api/Windows.UI.Xaml.Controls.ListViewBase) class with attached properties. This means that all the extensions in this class can apply to both [`ListView`](/uwp/api/windows.ui.xaml.controls.listview), [`GridView`](/uwp/api/windows.ui.xaml.controls.gridview) and other controls.
11-
12-
> **Platform APIs:** [`ListViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.listviewextensions), [`ItemContainerStretchDirection`](/dotnet/api/microsoft.toolkit.uwp.ui.ItemContainerStretchDirection)
13-
14-
## AlternateColor
15-
16-
The `AlternateColor` property provides a way to assign a background color to every other item.
17-
18-
> [!WARNING]
19-
> The [`ContainerContentChanging`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ContainerContentChanging) event used for this extension to work, will not be raised when the [`ItemsPanel`](/uwp/api/windows.ui.xaml.controls.itemscontrol.itemspanel) is replaced with another type of panel than [`ItemsStackPanel`](/uwp/api/windows.ui.xaml.controls.itemsstackpanel) or [`ItemsWrapGrid`](/uwp/api/windows.ui.xaml.controls.itemswrapgrid).
20-
21-
Here is how this property can be used in XAML:
22-
23-
```xaml
24-
<Page ...
25-
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
26-
27-
<ListView
28-
ui:ListViewExtensions.AlternateColor="Silver"
29-
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}" />
30-
```
31-
32-
## AlternateItemTemplate
33-
34-
The `AlternateItemTemplate` property provides a way to assign an alternate [`DataTemplate`](/uwp/api/windows.ui.xaml.datatemplate) to every other item. It is also possible to combine with the `AlternateColor` property.
35-
36-
> [!WARNING]
37-
> The [`ContainerContentChanging`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ContainerContentChanging) event used for this extension to work, will not be raised when the [`ItemsPanel`](/uwp/api/windows.ui.xaml.controls.itemscontrol.itemspanel) is replaced with another type of panel than [`ItemsStackPanel`](/uwp/api/windows.ui.xaml.controls.itemsstackpanel) or [`ItemsWrapGrid`](/uwp/api/windows.ui.xaml.controls.itemswrapgrid).
38-
39-
Here is how this property can be used in XAML:
40-
41-
```xaml
42-
<Page ...
43-
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
44-
45-
<Page.Resources>
46-
<DataTemplate x:Name="NormalTemplate">
47-
<TextBlock Text="{Binding " Foreground="Green"></TextBlock>
48-
</DataTemplate>
49-
50-
<DataTemplate x:Name="AlternateTemplate">
51-
<TextBlock Text="{Binding}" Foreground="Orange"></TextBlock>
52-
</DataTemplate>
53-
</Page.Resources>
54-
55-
<ListView
56-
ItemTemplate="{StaticResource NormalTemplate}"
57-
ui:ListViewExtensions.AlternateItemTemplate="{StaticResource AlternateTemplate}"
58-
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}" />
59-
```
60-
61-
## Command
62-
63-
`ListViewExtensions` provides extension method that allow attaching an [`ICommand`](/uwp/api/Windows.UI.Xaml.Input.ICommand) to handle `ListViewBase` item interaction by means of [`ItemClick`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ItemClick) event.
64-
65-
> [!IMPORTANT]
66-
> ListViewBase [`IsItemClickEnabled`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_IsItemClickEnabled) must be set to `true`.
67-
68-
Here is how this property can be used in XAML:
69-
70-
```xaml
71-
<Page ...
72-
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
73-
74-
<ListView
75-
ui:ListViewExtensions.Command="{x:Bind MainViewModel.ItemSelectedCommand, Mode=OneWay}"
76-
IsItemClickEnabled="True"
77-
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}"
78-
SelectionMode="None" />
79-
```
80-
81-
## StretchItemContainerDirection
82-
83-
The `ItemContainerStretchDirection` property provides a way to stretch the `ItemContainer` in horizontal, vertical or both ways. The allowed values are items from the `ItemContainerStretchDirection` type.
84-
85-
> [!WARNING]
86-
> The [`ContainerContentChanging`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ContainerContentChanging) event used for this extension to work, will not be raised when the [`ItemsPanel`](/uwp/api/windows.ui.xaml.controls.itemscontrol.itemspanel) is replaced with another type of panel than [`ItemsStackPanel`](/uwp/api/windows.ui.xaml.controls.itemsstackpanel) or [`ItemsWrapGrid`](/uwp/api/windows.ui.xaml.controls.itemswrapgrid).
87-
88-
Here is how this property can be used from XAML:
89-
90-
```xaml
91-
<Page ...
92-
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
93-
94-
<ListView
95-
ui:ListViewExtensions.StretchItemContainerDirection="Horizontal"
96-
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}" />
97-
```
98-
99-
## Examples
100-
101-
You can find more examples in the [unit tests](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.0.0/UnitTests).
1+
---
2+
title: ListViewExtensions
3+
author: nmetulev
4+
description: ListViewExtensions extensions provide a lightweight way to extend every control that inherits the ListViewBase class with attached properties.
5+
keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, ListViewBase, extensions
6+
---
7+
8+
# ListViewExtensions
9+
10+
The [`ListViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.listviewextensions) class provide a lightweight way to extend every control that inherits the [`ListViewBase`](/uwp/api/Windows.UI.Xaml.Controls.ListViewBase) class with attached properties. This means that all the extensions in this class can apply to both [`ListView`](/uwp/api/windows.ui.xaml.controls.listview), [`GridView`](/uwp/api/windows.ui.xaml.controls.gridview) and other controls.
11+
12+
> **Platform APIs:** [`ListViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.listviewextensions), [`ItemContainerStretchDirection`](/dotnet/api/microsoft.toolkit.uwp.ui.ItemContainerStretchDirection)
13+
14+
> [!div class="nextstepaction"]
15+
> [Try it in the sample app](uwpct://Extensions?sample=ListViewExtensions)
16+
17+
## ListViewBase Extensions
18+
19+
- [AlternateColor](#alternatecolor)
20+
- [AlternateItemTemplate](#alternateitemtemplate)
21+
- [Command](#command)
22+
- [StretchItemContainerDirection](#stretchitemcontainerdirection)
23+
- [SmoothScrollIntoView](#smoothscrollintoview)
24+
25+
## AlternateColor
26+
27+
The `AlternateColor` property provides a way to assign a background color to every other item.
28+
29+
> [!WARNING]
30+
> The [`ContainerContentChanging`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ContainerContentChanging) event used for this extension to work, will not be raised when the [`ItemsPanel`](/uwp/api/windows.ui.xaml.controls.itemscontrol.itemspanel) is replaced with another type of panel than [`ItemsStackPanel`](/uwp/api/windows.ui.xaml.controls.itemsstackpanel) or [`ItemsWrapGrid`](/uwp/api/windows.ui.xaml.controls.itemswrapgrid).
31+
32+
Here is how this property can be used in XAML:
33+
34+
```xaml
35+
<Page ...
36+
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
37+
38+
<ListView
39+
ui:ListViewExtensions.AlternateColor="Silver"
40+
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}" />
41+
```
42+
43+
## AlternateItemTemplate
44+
45+
The `AlternateItemTemplate` property provides a way to assign an alternate [`DataTemplate`](/uwp/api/windows.ui.xaml.datatemplate) to every other item. It is also possible to combine with the `AlternateColor` property.
46+
47+
> [!WARNING]
48+
> The [`ContainerContentChanging`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ContainerContentChanging) event used for this extension to work, will not be raised when the [`ItemsPanel`](/uwp/api/windows.ui.xaml.controls.itemscontrol.itemspanel) is replaced with another type of panel than [`ItemsStackPanel`](/uwp/api/windows.ui.xaml.controls.itemsstackpanel) or [`ItemsWrapGrid`](/uwp/api/windows.ui.xaml.controls.itemswrapgrid).
49+
50+
Here is how this property can be used in XAML:
51+
52+
```xaml
53+
<Page ...
54+
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
55+
56+
<Page.Resources>
57+
<DataTemplate x:Name="NormalTemplate">
58+
<TextBlock Text="{Binding " Foreground="Green"></TextBlock>
59+
</DataTemplate>
60+
61+
<DataTemplate x:Name="AlternateTemplate">
62+
<TextBlock Text="{Binding}" Foreground="Orange"></TextBlock>
63+
</DataTemplate>
64+
</Page.Resources>
65+
66+
<ListView
67+
ItemTemplate="{StaticResource NormalTemplate}"
68+
ui:ListViewExtensions.AlternateItemTemplate="{StaticResource AlternateTemplate}"
69+
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}" />
70+
```
71+
72+
## Command
73+
74+
`ListViewExtensions` provides extension method that allow attaching an [`ICommand`](/uwp/api/Windows.UI.Xaml.Input.ICommand) to handle `ListViewBase` item interaction by means of [`ItemClick`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ItemClick) event.
75+
76+
> [!IMPORTANT]
77+
> ListViewBase [`IsItemClickEnabled`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_IsItemClickEnabled) must be set to `true`.
78+
79+
Here is how this property can be used in XAML:
80+
81+
```xaml
82+
<Page ...
83+
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
84+
85+
<ListView
86+
ui:ListViewExtensions.Command="{x:Bind MainViewModel.ItemSelectedCommand, Mode=OneWay}"
87+
IsItemClickEnabled="True"
88+
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}"
89+
SelectionMode="None" />
90+
```
91+
92+
## StretchItemContainerDirection
93+
94+
The `ItemContainerStretchDirection` property provides a way to stretch the `ItemContainer` in horizontal, vertical or both ways. The allowed values are items from the `ItemContainerStretchDirection` type.
95+
96+
> [!WARNING]
97+
> The [`ContainerContentChanging`](/uwp/api/windows.ui.xaml.controls.listviewbase#Windows_UI_Xaml_Controls_ListViewBase_ContainerContentChanging) event used for this extension to work, will not be raised when the [`ItemsPanel`](/uwp/api/windows.ui.xaml.controls.itemscontrol.itemspanel) is replaced with another type of panel than [`ItemsStackPanel`](/uwp/api/windows.ui.xaml.controls.itemsstackpanel) or [`ItemsWrapGrid`](/uwp/api/windows.ui.xaml.controls.itemswrapgrid).
98+
99+
Here is how this property can be used from XAML:
100+
101+
```xaml
102+
<Page ...
103+
xmlns:ui="using:Microsoft.Toolkit.Uwp.UI">
104+
105+
<ListView
106+
ui:ListViewExtensions.StretchItemContainerDirection="Horizontal"
107+
ItemsSource="{x:Bind MainViewModel.Items, Mode=OneWay}" />
108+
```
109+
110+
## SmoothScrollIntoView
111+
112+
Use SmoothScrollIntoView helps to scroll the item into the view with animation. Specify the ItemPosition property to align the item.
113+
114+
### Syntax
115+
116+
```csharp
117+
// Scrolling with index
118+
await MyGridView.SmoothScrollIntoViewWithIndexAsync(index: int, itemPlacement: ItemPlacement, disableAnimation: bool, scrollIfVisibile: bool, additionalHorizontalOffset: int, additionalVerticalOffset: int);
119+
120+
// Scrolling with item
121+
await MyGridView.SmoothScrollIntoViewWithItemAsync(item: object, itemPlacement: ItemPlacement, disableAnimation: bool, scrollIfVisibile: bool, additionalHorizontalOffset: int, additionalVerticalOffset: int);
122+
```
123+
124+
```vb
125+
' Scrolling with index
126+
Await MyGridView.SmoothScrollIntoViewWithItemAsync(index:=Integer, itemPlacement:=ItemPlacement.Bottom, disableAnimation:=Boolean, scrollIfVisibile:=Boolean, additionalHorizontalOffset:=Integer, additionalVerticalOffset:=Integer)
127+
128+
' Scrolling with item
129+
Await MyGridView.SmoothScrollIntoViewWithItemAsync(item:=Object, itemPlacement:=ItemPlacement.Bottom, disableAnimation:=Boolean, scrollIfVisibile:=Boolean, additionalHorizontalOffset:=Integer, additionalVerticalOffset:=Integer)
130+
```
131+
132+
### Sample Output
133+
134+
![SmoothScrollIntoView Helper](../resources/images/Extensions/SmoothScrollIntoView.gif)
135+
136+
### Methods
137+
138+
| Methods | Return Type | Description |
139+
| -- | -- | -- |
140+
| SmoothScrollIntoViewWithIndexAsync(int, ScrollItemPlacement, bool, bool, int, int) | Task | Smooth scroll item into view With index number |
141+
| SmoothScrollIntoViewWithItemAsync(object, ScrollItemPlacement, bool, bool, int, int) | Task | Smooth scroll item into view With item object |
142+
143+
### Method params
144+
145+
| Properties | Type | Description |
146+
|------------|------|-------------|
147+
| intex | int | Intex of the item to be scrolled. Index can be negative |
148+
| item | int | Intex of the item to be scrolled |
149+
| itemPosition | ScrollItemPlacement | Specify the position of the Item after scrolling |
150+
| disableAnimation | bool | To disable the scrolling animation |
151+
| scrollIfVisibile | bool | Set `true` to scroll even if the scroll to item is visible so that the item will be aligned depend upon `itemPosition` |
152+
| additionalHorizontalOffset | bool | Give addition horizontal offset |
153+
| additionalVerticalOffset | bool | Give addition vertical offset |
154+
155+
### ItemPosition
156+
157+
| ScrollItemPlacement | Description |
158+
|--------------|-------------|
159+
| Default | If visible then it will not scroll, if not then item will be aligned to the nearest edge |
160+
| Left | Aligned left |
161+
| Top | Aligned top |
162+
| Center | Aligned center |
163+
| Right | Aligned right |
164+
| Bottom | Aligned bottom |
165+
166+
### Examples
167+
168+
- We can use this extension to make the selected item always centered.
169+
170+
**Sample Code**
171+
172+
```xaml
173+
<ListView ItemsSource="{x:Bind itemSources}" SelectionChanged="ListView_SelectionChanged">
174+
<ListView.ItemTemplate>
175+
<DataTemplate>
176+
<!-- Your Template -->
177+
</DataTemplate>
178+
</ListView.ItemTemplate>
179+
<ListView.ItemsPanel>
180+
<ItemsPanelTemplate>
181+
<StackPanel Orientation="Horizontal"/>
182+
</ItemsPanelTemplate>
183+
</ListView.ItemsPanel>
184+
</ListView>
185+
```
186+
187+
```csharp
188+
private async void ListView_SelectionChanged(object sender, SelectionChangedEventArgs e)
189+
{
190+
var listView = (sender as ListView);
191+
await listView.SmoothScrollIntoViewWithIndexAsync(listView.SelectedIndex, ScrollItemPlacement.Center, false, true);
192+
}
193+
```
194+
195+
```vb
196+
Private Async Sub ListView_SelectionChanged(ByVal sender As Object, ByVal e As SelectionChangedEventArgs)
197+
Dim listView = (TryCast(sender, ListView))
198+
Await listView.SmoothScrollIntoViewWithIndexAsync(listView.SelectedIndex, ScrollItemPlacement.Center, False, True)
199+
End Sub
200+
```
201+
202+
**Sample Output**
203+
204+
![Use Case 1 Output](../resources/images/Extensions/SmoothScrollIntoView-CenterSelected.gif)
205+
206+
## Requirements
207+
208+
| Device family | Universal, 10.0.16299.0 or higher |
209+
| --- | --- |
210+
| Namespace | Microsoft.Toolkit.Uwp.UI.Extensions |
211+
| NuGet package | [Microsoft.Toolkit.Uwp.UI](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI/) |
212+
213+
## API
214+
215+
- [ListViewExtensions source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI/Extensions/ListViewBase)

‎docs/resources/images/Extensions/SmoothScrollIntoView-CenterSelected.gif‎

608 KB
Loading

‎docs/resources/images/Extensions/SmoothScrollIntoView.gif‎

444 KB
Loading

0 commit comments

Comments
 (0)