diff --git a/active/ItemsRepeater/ItemsRepeater-FirstVisibleIndex.md b/active/ItemsRepeater/ItemsRepeater-FirstVisibleIndex.md new file mode 100644 index 000000000..4b9b9e9e7 --- /dev/null +++ b/active/ItemsRepeater/ItemsRepeater-FirstVisibleIndex.md @@ -0,0 +1,132 @@ + + + + +# Background + + + + + + + + + + +[ItemsRepeater](https://docs.microsoft.com/uwp/api/microsoft.ui.xaml.controls.itemsrepeater?view=winui-2.4) is a flexible layout control that allows you to easily display collections of items complete with custom layouts, animations, styling, and more. Currently, there is no built-in way to access which items are visible or realized in the viewport of the ItemsRepeater. This inhibits lots of interaction-based UIs and puts lots of extra work on the developer to manually determine which items are visible. + +ItemsRepeater does independent scrolling, and requires a buffer area that holds non-visible items and runs layout processes on them before they become visible/scrolled onto. This buffer area size is configurable via the [HorizontalCacheLength](https://docs.microsoft.com/uwp/api/microsoft.ui.xaml.controls.itemsrepeater.horizontalcachelength?view=winui-2.4) and [VerticalCacheLength](https://docs.microsoft.com/uwp/api/microsoft.ui.xaml.controls.itemsrepeater.verticalcachelength?view=winui-2.4) properties. + +The [ListView](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.listview?view=winrt-19041) and [GridView](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.gridview?view=winrt-19041) controls have properties to access the indices of their first and last visible items in the form of the [FirstVisibleIndex](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.itemswrapgrid.firstvisibleindex?view=winrt-19041#Windows_UI_Xaml_Controls_ItemsWrapGrid_FirstVisibleIndex) and [LastVisibleIndex](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.itemswrapgrid.lastvisibleindex?view=winrt-19041) properties on their respective base panels, [ItemsStackPanel](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.itemsstackpanel?view=winrt-19041) and [ItemsWrapGrid](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.ItemsWrapGrid?redirectedfrom=MSDN&view=winrt-19041#Windows_UI_Xaml_Controls_ItemsWrapGrid_FirstVisibleIndex). These properties allow you to access all currently visible items. + +# Description + + +`RealizedItems` and `VisibleItems` are properties that give you access to all realized or visible items within an ItemsRepeater. These two properties both return lists of [UIElement](https://docs.microsoft.com/uwp/api/windows.ui.xaml.uielement?view=winrt-19041) objects that make up the ItemsRepeater. + +Realized items includes all items that are currently visible and all items that are in the cache/buffer area. The size of these buffer areas are configurable via the [HorizontalCacheLength](https://docs.microsoft.com/uwp/api/microsoft.ui.xaml.controls.itemsrepeater.horizontalcachelength?view=winui-2.4) and [VerticalCacheLength](https://docs.microsoft.com/uwp/api/microsoft.ui.xaml.controls.itemsrepeater.verticalcachelength?view=winui-2.4) properties + +Visible items refers to all items that are visible in the ItemsRepeater, whether they are fully or partially visible. + +# Examples + + + + + + +```csharp +/* Example 1: Check if a specific item is visible by the user. If visible, inform the user that they've scrolled to the bottom of the list. */ + +int repeater_length = repeater.ItemsSourceView.Count; + +foreach (Grid item in repeater.VisibleItems){ + // Check to see if the last item of the list is visible. + if (repeater.GetElementIndex(item) == repeater_length - 1){ + // If so, we've reached the end of the list. + myTextBlock.Text = "No more elements to display."; + } +} + +/* Example 2: Get the list of realized items and mark in the source collection that the item has been realized. */ +int item_idx = 0; +foreach (Grid item in repeater.RealizedItems){ + item_idx = repeater.GetElementIndex(item); + // IsRealized is a custom attribute created for objects that are a part of the repeater's ItemsSource. + repeater.ItemsSourceView[item_idx].IsRealized = true; +} + +/* Example 3: Find the item with the first visible index and change its color */ + +int firstVisibleIndex = int.MaxValue; + +foreach (Grid item in repeater.VisbleItems){ + int index = repeater.GetElementIndex(item); + firstVisibleIndex = Math.Min(index, firstVisibleIndex); +} + +Grid firstVisibleItem = repeater.TryGetElement(firstVisibleIndex) as Grid; +firstVisibleItem.Background = "Light Green"; +``` + +# API Notes + + + +```csharp + +public IEnumerable RealizedItems { get; } +public IEnumerable VisibleItems { get; } + +// RealizedItems and VisibleItems are *unsorted* IEnumerable objects. + +``` + +# API Details + +```csharp +unsealed runtimeclass ItemsRepeater : Windows.UI.Xaml.FrameworkElement +{ + ItemsRepeater(); + + // ... + Windows.Foundation.Collections.IEnumerable RealizedItems { get; } + + Windows.Foundation.Collections.IEnumerable VisibleItems { get; } + + // ... +} +``` + +