Add ListView ScrollIntoView and ListViewPersistenceHelper samples

WinUIGallery/Samples/ListView/ListViewPage.xaml

@@ -484,5 +484,79 @@
 
         </controls:ControlExample>
 
+        <controls:ControlExample SampleDefinition="ListView\ListviewRestoreScrollPosition.txt">
+            <ListView
+                x:Name="RestoreScrollListView"
+                Width="400"
+                Height="220"
+                HorizontalAlignment="Left"
+                BorderBrush="{ThemeResource ControlStrongStrokeColorDefaultBrush}"
+                BorderThickness="1"
+                ItemsSource="{x:Bind contacts5}">
+                <ListView.ItemTemplate>
+                    <DataTemplate x:DataType="x:String">
+                        <TextBlock Margin="0,8,0,8" Text="{x:Bind}" />
+                    </DataTemplate>
+                </ListView.ItemTemplate>
+            </ListView>
+
+            <controls:ControlExample.Options>
+                <StackPanel Spacing="8">
+                    <Button x:Name="SavePositionButton" Click="SavePositionButton_Click" Content="Save position" />
+                    <Button
+                        x:Name="RestorePositionButton"
+                        Click="RestorePositionButton_Click"
+                        Content="Restore position"
+                        IsEnabled="False" />
+                    <TextBlock
+                        x:Name="SavedPositionTextBlock"
+                        MaxWidth="220"
+                        Style="{ThemeResource CaptionTextBlockStyle}"
+                        Text="No position saved."
+                        TextWrapping="Wrap" />
+                </StackPanel>
+            </controls:ControlExample.Options>
+        </controls:ControlExample>
+
+        <controls:ControlExample SampleDefinition="ListView\ListviewScrollIntoView.txt">
+            <ListView
+                x:Name="ScrollIntoViewListView"
+                Width="400"
+                Height="220"
+                HorizontalAlignment="Left"
+                BorderBrush="{ThemeResource ControlStrongStrokeColorDefaultBrush}"
+                BorderThickness="1"
+                ItemsSource="{x:Bind contacts6}">
+                <ListView.ItemTemplate>
+                    <DataTemplate x:DataType="x:String">
+                        <TextBlock Margin="0,8,0,8" Text="{x:Bind}" />
+                    </DataTemplate>
+                </ListView.ItemTemplate>
+            </ListView>
+
+            <controls:ControlExample.Options>
+                <StackPanel Spacing="8">
+                    <NumberBox
+                        x:Name="ScrollIndexNumberBox"
+                        Header="Index"
+                        LargeChange="10"
+                        Maximum="999"
+                        Minimum="0"
+                        SmallChange="1"
+                        SpinButtonPlacementMode="Inline"
+                        ValidationMode="InvalidInputOverwritten"
+                        Value="10" />
+                    <ComboBox
+                        x:Name="ScrollAlignmentComboBox"
+                        Header="Alignment"
+                        SelectedIndex="0">
+                        <ComboBoxItem Content="Default" />
+                        <ComboBoxItem Content="Leading" />
+                    </ComboBox>
+                    <Button Click="ScrollIntoViewButton_Click" Content="Scroll into view" />
+                </StackPanel>
+            </controls:ControlExample.Options>
+        </controls:ControlExample>
+
     </StackPanel>
 </pages:ItemsPageBase>

WinUIGallery/Samples/ListView/ListViewPage.xaml.cs

@@ -8,6 +8,7 @@
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
 using System.Linq;
+using System.Runtime.InteropServices.WindowsRuntime;
 using System.Threading.Tasks;
 using Windows.ApplicationModel.DataTransfer;
 using WinUIGallery.Helpers;
@@ -22,6 +23,10 @@ public sealed partial class ListViewPage : ItemsPageBase
     ObservableCollection<Contact> contacts3 = new ObservableCollection<Contact>();
     ObservableCollection<Contact> contacts3Filtered = new ObservableCollection<Contact>();
     ObservableCollection<Contact> contacts4ContextMenu = new ObservableCollection<Contact>();
+    ObservableCollection<string> contacts5 = new ObservableCollection<string>();
+    ObservableCollection<string> contacts6 = new ObservableCollection<string>();
+
+    private string _persistedPosition = string.Empty;
 
     ItemsStackPanel? stackPanelObj;
 
@@ -67,6 +72,26 @@ protected override async void OnNavigatedTo(NavigationEventArgs e)
         contacts4ContextMenu = await Contact.GetContactsAsync();
         ContextMenuList.ItemsSource = contacts4ContextMenu;
 
+        // Populate ListViews for the RestoreScrollPosition and ScrollIntoView samples.
+        // Pre-format each entry with its index so the position in the list is easy to track.
+        var baseContacts = await Contact.GetContactsAsync();
+        contacts5 = new ObservableCollection<string>(
+            baseContacts.Select((c, i) => $"{i + 1}. {c.Name}"));
+
+        // ScrollIntoView is more interesting with a long list, so seed multiple copies.
+        var manyContacts = new List<string>();
+        int n = 1;
+        for (int i = 0; i < 10; i++)
+        {
+            foreach (var c in baseContacts)
+            {
+                manyContacts.Add($"{n++}. {c.Name}");
+            }
+        }
+        contacts6 = new ObservableCollection<string>(manyContacts);
+        RestoreScrollListView.ItemsSource = contacts5;
+        ScrollIntoViewListView.ItemsSource = contacts6;
+
         FilteredListView.ItemsSource = contacts3Filtered;
     }
 
@@ -319,6 +344,56 @@ private void ContactDeleteMenuItem_Click(object sender, RoutedEventArgs e)
 
         contacts4ContextMenu.Remove(contact);
     }
+
+    //===================================================================================================================
+    // Save / restore scroll position sample
+    //===================================================================================================================
+
+    private void SavePositionButton_Click(object sender, RoutedEventArgs e)
+    {
+        // GetRelativeScrollPosition returns an opaque string identifying the item at the
+        // top of the viewport plus its pixel offset. Store it for later restoration.
+        _persistedPosition = ListViewPersistenceHelper.GetRelativeScrollPosition(
+            RestoreScrollListView,
+            item => item as string ?? string.Empty);
+
+        SavedPositionTextBlock.Text = $"Saved position: {_persistedPosition}";
+        RestorePositionButton.IsEnabled = true;
+    }
+
+    private async void RestorePositionButton_Click(object sender, RoutedEventArgs e)
+    {
+        if (string.IsNullOrEmpty(_persistedPosition))
+        {
+            return;
+        }
+
+        // SetRelativeScrollPositionAsync scrolls the ListView back to the item identified
+        // by the saved string. The callback resolves a key back to its data item.
+        await ListViewPersistenceHelper.SetRelativeScrollPositionAsync(
+            RestoreScrollListView,
+            _persistedPosition,
+            key => Task.FromResult<object?>(contacts5.FirstOrDefault(c => c == key))!.AsAsyncOperation()!);
+    }
+
+    //===================================================================================================================
+    // ScrollIntoView sample
+    //===================================================================================================================
+
+    private void ScrollIntoViewButton_Click(object sender, RoutedEventArgs e)
+    {
+        int index = (int)ScrollIndexNumberBox.Value;
+        if (index < 0 || index >= ScrollIntoViewListView.Items.Count)
+        {
+            return;
+        }
+
+        var alignment = ScrollAlignmentComboBox.SelectedIndex == 1
+            ? ScrollIntoViewAlignment.Leading
+            : ScrollIntoViewAlignment.Default;
+
+        ScrollIntoViewListView.ScrollIntoView(ScrollIntoViewListView.Items[index], alignment);
+    }
 }
 
 public class Message

WinUIGallery/Samples/ListView/ListviewRestoreScrollPosition.txt

@@ -0,0 +1,45 @@
+--- header
+Save and restore the scroll position using ListViewPersistenceHelper.
+--- xaml
+<ListView x:Name="RestoreScrollListView"
+          Height="220" Width="400" HorizontalAlignment="Left"
+          BorderThickness="1" BorderBrush="{ThemeResource ControlStrongStrokeColorDefaultBrush}"
+          ItemsSource="{x:Bind contacts5}">
+    <ListView.ItemTemplate>
+        <DataTemplate x:DataType="x:String">
+            <TextBlock Text="{x:Bind}" Margin="0,8,0,8"/>
+        </DataTemplate>
+    </ListView.ItemTemplate>
+</ListView>
+--- c#
+// Persisted scroll position string. In a real app, store this somewhere that survives
+// the lifetime of the page (e.g. a static field, view-model, or app state) so it is
+// available after navigating away and back.
+private string _persistedPosition = string.Empty;
+
+private void SavePositionButton_Click(object sender, RoutedEventArgs e)
+{
+    // GetRelativeScrollPosition returns an opaque string that identifies the
+    // item currently at the top of the viewport plus its pixel offset.
+    _persistedPosition = ListViewPersistenceHelper.GetRelativeScrollPosition(
+        RestoreScrollListView,
+        item => item as string ?? string.Empty);
+
+    SavedPositionTextBlock.Text = $"Saved position: {_persistedPosition}";
+    RestorePositionButton.IsEnabled = true;
+}
+
+private async void RestorePositionButton_Click(object sender, RoutedEventArgs e)
+{
+    if (string.IsNullOrEmpty(_persistedPosition))
+    {
+        return;
+    }
+
+    // SetRelativeScrollPositionAsync scrolls the ListView back to the item identified
+    // by the saved string. The callback resolves a key back to its data item.
+    await ListViewPersistenceHelper.SetRelativeScrollPositionAsync(
+        RestoreScrollListView,
+        _persistedPosition,
+        key => Task.FromResult<object?>(contacts5.FirstOrDefault(c => c == key))!.AsAsyncOperation()!);
+}

WinUIGallery/Samples/ListView/ListviewScrollIntoView.txt

@@ -0,0 +1,28 @@
+--- header
+Scroll a ListView programmatically with ScrollIntoView.
+--- xaml
+<ListView x:Name="ScrollIntoViewListView"
+          Height="220" Width="400" HorizontalAlignment="Left"
+          BorderThickness="1" BorderBrush="{ThemeResource ControlStrongStrokeColorDefaultBrush}"
+          ItemsSource="{x:Bind contacts6}">
+    <ListView.ItemTemplate>
+        <DataTemplate x:DataType="x:String">
+            <TextBlock Text="{x:Bind}" Margin="0,8,0,8"/>
+        </DataTemplate>
+    </ListView.ItemTemplate>
+</ListView>
+--- c#
+private void ScrollIntoViewButton_Click(object sender, RoutedEventArgs e)
+{
+    int index = (int)ScrollIndexNumberBox.Value;
+    if (index < 0 || index >= ScrollIntoViewListView.Items.Count)
+    {
+        return;
+    }
+
+    var alignment = ScrollAlignmentComboBox.SelectedIndex == 1
+        ? ScrollIntoViewAlignment.Leading
+        : ScrollIntoViewAlignment.Default;
+
+    ScrollIntoViewListView.ScrollIntoView(ScrollIntoViewListView.Items[index], alignment);
+}