Adding a Tip to specify ScrollTo may not work under specific conditio…

…n's (#2736)

* adding scrollTo tip

* Edit tip and add xrefs.

* Fix xrefs.

---------

Co-authored-by: David Britch <davidbritch@users.noreply.github.com>

docs/user-interface/controls/collectionview/includes/scrolling-tip.md

@@ -1,7 +1,7 @@
 ---
 ms.topic: include
-ms.date: 06/09/2023
+ms.date: 01/17/2025
 ---
 
 > [!TIP]
-> Placing a <xref:Microsoft.Maui.Controls.CollectionView> inside a <xref:Microsoft.Maui.Controls.VerticalStackLayout> can stop the <xref:Microsoft.Maui.Controls.CollectionView> scrolling, and can limit the number of items that are displayed. In this situation, replace the <xref:Microsoft.Maui.Controls.VerticalStackLayout> with a <xref:Microsoft.Maui.Controls.Grid>.
+> Placing a <xref:Microsoft.Maui.Controls.CollectionView> inside a <xref:Microsoft.Maui.Controls.VerticalStackLayout> or <xref:Microsoft.Maui.Controls.StackLayout> can prevent the <xref:Microsoft.Maui.Controls.CollectionView> from scrolling, can prevent the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method from scrolling the <xref:Microsoft.Maui.Controls.CollectionView>, and can limit the number of items that are displayed. In this situation, replace the <xref:Microsoft.Maui.Controls.VerticalStackLayout> or <xref:Microsoft.Maui.Controls.StackLayout> with a <xref:Microsoft.Maui.Controls.Grid>.

docs/user-interface/controls/collectionview/scrolling.md

@@ -8,13 +8,13 @@ ms.date: 09/30/2024
 
 [![Browse sample.](~/media/code-sample.png) Browse the sample](/samples/dotnet/maui-samples/userinterface-collectionview)
 
-The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CollectionView> defines two `ScrollTo` methods, that scroll items into view. One of the overloads scrolls the item at the specified index into view, while the other scrolls the specified item into view. Both overloads have additional arguments that can be specified to indicate the group the item belongs to, the exact position of the item after the scroll has completed, and whether to animate the scroll.
+The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CollectionView> defines two <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> methods, that scroll items into view. One of the overloads scrolls the item at the specified index into view, while the other scrolls the specified item into view. Both overloads have additional arguments that can be specified to indicate the group the item belongs to, the exact position of the item after the scroll has completed, and whether to animate the scroll.
 
-<xref:Microsoft.Maui.Controls.CollectionView> defines a `ScrollToRequested` event that is fired when one of the `ScrollTo` methods is invoked. The `ScrollToRequestedEventArgs` object that accompanies the `ScrollToRequested` event has many properties, including `IsAnimated`, `Index`, `Item`, and `ScrollToPosition`. These properties are set from the arguments specified in the `ScrollTo` method calls.
+<xref:Microsoft.Maui.Controls.CollectionView> defines a <xref:Microsoft.Maui.Controls.ItemsView.ScrollToRequested> event that is fired when one of the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> methods is invoked. The <xref:Microsoft.Maui.Controls.ScrollToRequestedEventArgs> object that accompanies the <xref:Microsoft.Maui.Controls.ItemsView.ScrollToRequested> event has many properties, including `IsAnimated`, `Index`, `Item`, and `ScrollToPosition`. These properties are set from the arguments specified in the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method calls.
 
-In addition, <xref:Microsoft.Maui.Controls.CollectionView> defines a `Scrolled` event that is fired to indicate that scrolling occurred. The `ItemsViewScrolledEventArgs` object that accompanies the `Scrolled` event has many properties. For more information, see [Detect scrolling](#detect-scrolling).
+In addition, <xref:Microsoft.Maui.Controls.CollectionView> defines a <xref:Microsoft.Maui.Controls.ItemsView.Scrolled> event that is fired to indicate that scrolling occurred. The <xref:Microsoft.Maui.Controls.ItemsViewScrolledEventArgs> object that accompanies the <xref:Microsoft.Maui.Controls.ItemsView.Scrolled> event has many properties. For more information, see [Detect scrolling](#detect-scrolling).
 
-<xref:Microsoft.Maui.Controls.CollectionView> also defines a `ItemsUpdatingScrollMode` property that represents the scrolling behavior of the <xref:Microsoft.Maui.Controls.CollectionView> when new items are added to it. For more information about this property, see [Control scroll position when new items are added](#control-scroll-position-when-new-items-are-added).
+<xref:Microsoft.Maui.Controls.CollectionView> also defines a <xref:Microsoft.Maui.Controls.ItemsView.ItemsUpdatingScrollMode> property that represents the scrolling behavior of the <xref:Microsoft.Maui.Controls.CollectionView> when new items are added to it. For more information about this property, see [Control scroll position when new items are added](#control-scroll-position-when-new-items-are-added).
 
 When a user swipes to initiate a scroll, the end position of the scroll can be controlled so that items are fully displayed. This feature is known as snapping, because items snap to position when scrolling stops. For more information, see [Snap points](#snap-points).
 
@@ -24,7 +24,7 @@ When a user swipes to initiate a scroll, the end position of the scroll can be c
 
 ## Detect scrolling
 
-<xref:Microsoft.Maui.Controls.CollectionView> defines a `Scrolled` event which is fired to indicate that scrolling occurred. The `ItemsViewScrolledEventArgs` class, which represents the object that accompanies the `Scrolled` event, defines the following properties:
+<xref:Microsoft.Maui.Controls.CollectionView> defines a <xref:Microsoft.Maui.Controls.ItemsView.Scrolled> event which is fired to indicate that scrolling occurred. The <xref:Microsoft.Maui.Controls.ItemsViewScrolledEventArgs> class, which represents the object that accompanies the <xref:Microsoft.Maui.Controls.ItemsView.Scrolled> event, defines the following properties:
 
 - `HorizontalDelta`, of type `double`, represents the change in the amount of horizontal scrolling. This is a negative value when scrolling left, and a positive value when scrolling right.
 - `VerticalDelta`, of type `double`, represents the change in the amount of vertical scrolling. This is a negative value when scrolling upwards, and a positive value when scrolling downwards.
@@ -34,7 +34,7 @@ When a user swipes to initiate a scroll, the end position of the scroll can be c
 - `CenterItemIndex`, of type `int`, is the index of the center item that's visible in the list.
 - `LastVisibleItemIndex`, of type `int`, is the index of the last item that's visible in the list.
 
-The following XAML example shows a <xref:Microsoft.Maui.Controls.CollectionView> that sets an event handler for the `Scrolled` event:
+The following XAML example shows a <xref:Microsoft.Maui.Controls.CollectionView> that sets an event handler for the <xref:Microsoft.Maui.Controls.ItemsView.Scrolled> event:
 
 ```xaml
 <CollectionView Scrolled="OnCollectionViewScrolled">
@@ -49,7 +49,7 @@ CollectionView collectionView = new CollectionView();
 collectionView.Scrolled += OnCollectionViewScrolled;
 ```
 
-In this code example, the `OnCollectionViewScrolled` event handler is executed when the `Scrolled` event fires:
+In this code example, the `OnCollectionViewScrolled` event handler is executed when the <xref:Microsoft.Maui.Controls.ItemsView.Scrolled> event fires:
 
 ```csharp
 void OnCollectionViewScrolled(object sender, ItemsViewScrolledEventArgs e)
@@ -59,11 +59,11 @@ void OnCollectionViewScrolled(object sender, ItemsViewScrolledEventArgs e)
 ```
 
 > [!IMPORTANT]
-> The `Scrolled` event is fired for user initiated scrolls, and for programmatic scrolls.
+> The <xref:Microsoft.Maui.Controls.ItemsView.Scrolled> event is fired for user initiated scrolls, and for programmatic scrolls.
 
 ## Scroll an item at an index into view
 
-One `ScrollTo` method overload scrolls the item at the specified index into view. Given a <xref:Microsoft.Maui.Controls.CollectionView> object named <xref:Microsoft.Maui.Controls.CollectionView>, the following example shows how to scroll the item at index 12 into view:
+One <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method overload scrolls the item at the specified index into view. Given a <xref:Microsoft.Maui.Controls.CollectionView> object named <xref:Microsoft.Maui.Controls.CollectionView>, the following example shows how to scroll the item at index 12 into view:
 
 ```csharp
 collectionView.ScrollTo(12);
@@ -77,11 +77,11 @@ collectionView.ScrollTo(2, 1);
 ```
 
 > [!NOTE]
-> The `ScrollToRequested` event is fired when the `ScrollTo` method is invoked.
+> The <xref:Microsoft.Maui.Controls.ItemsView.ScrollToRequested> event is fired when the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method is invoked.
 
 ## Scroll an item into view
 
-Another `ScrollTo` method overload scrolls the specified item into view. Given a <xref:Microsoft.Maui.Controls.CollectionView> object named <xref:Microsoft.Maui.Controls.CollectionView>, the following example shows how to scroll the Proboscis Monkey item into view:
+Another <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method overload scrolls the specified item into view. Given a <xref:Microsoft.Maui.Controls.CollectionView> object named <xref:Microsoft.Maui.Controls.CollectionView>, the following example shows how to scroll the Proboscis Monkey item into view:
 
 ```csharp
 MonkeysViewModel viewModel = BindingContext as MonkeysViewModel;
@@ -99,19 +99,19 @@ collectionView.ScrollTo(monkey, group);
 ```
 
 > [!NOTE]
-> The `ScrollToRequested` event is fired when the `ScrollTo` method is invoked.
+> The <xref:Microsoft.Maui.Controls.ItemsView.ScrollToRequested> event is fired when the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method is invoked.
 
 ## Disable scroll animation
 
-A scrolling animation is displayed when scrolling an item into view. However, this animation can be disabled by setting the `animate` argument of the `ScrollTo` method to `false`:
+A scrolling animation is displayed when scrolling an item into view. However, this animation can be disabled by setting the `animate` argument of the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method to `false`:
 
 ```csharp
 collectionView.ScrollTo(monkey, animate: false);
 ```
 
 ## Control scroll position
 
-When scrolling an item into view, the exact position of the item after the scroll has completed can be specified with the `position` argument of the `ScrollTo` methods. This argument accepts a `ScrollToPosition` enumeration member.
+When scrolling an item into view, the exact position of the item after the scroll has completed can be specified with the `position` argument of the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> methods. This argument accepts a <xref:Microsoft.Maui.Controls.ScrollToPosition> enumeration member.
 
 ### MakeVisible
 
@@ -126,7 +126,7 @@ This example code results in the minimal scrolling required to scroll the item i
 :::image type="content" source="media/scrolling/scrolltoposition-makevisible.png" alt-text="Screenshot of a CollectionView vertical list with ScrollToPosition.MakeVisible.":::
 
 > [!NOTE]
-> The `ScrollToPosition.MakeVisible` member is used by default, if the `position` argument is not specified when calling the `ScrollTo` method.
+> The `ScrollToPosition.MakeVisible` member is used by default, if the `position` argument is not specified when calling the <xref:Microsoft.Maui.Controls.ItemsView.ScrollTo%2A> method.
 
 ### Start
 
@@ -166,13 +166,13 @@ This example code results in the item being scrolled to the end of the view:
 
 ## Control scroll position when new items are added
 
-<xref:Microsoft.Maui.Controls.CollectionView> defines a `ItemsUpdatingScrollMode` property, which is backed by a bindable property. This property gets or sets a `ItemsUpdatingScrollMode` enumeration value that represents the scrolling behavior of the <xref:Microsoft.Maui.Controls.CollectionView> when new items are added to it. The `ItemsUpdatingScrollMode` enumeration defines the following members:
+<xref:Microsoft.Maui.Controls.CollectionView> defines a <xref:Microsoft.Maui.Controls.ItemsView.ItemsUpdatingScrollMode> property, which is backed by a bindable property. This property gets or sets a <xref:Microsoft.Maui.Controls.ItemsUpdatingScrollMode> enumeration value that represents the scrolling behavior of the <xref:Microsoft.Maui.Controls.CollectionView> when new items are added to it. The <xref:Microsoft.Maui.Controls.ItemsUpdatingScrollMode> enumeration defines the following members:
 
 - `KeepItemsInView` keeps the first item in the list displayed when new items are added.
 - `KeepScrollOffset` ensures that the current scroll position is maintained when new items are added.
 - `KeepLastItemInView` adjusts the scroll offset to keep the last item in the list displayed when new items are added.
 
-The default value of the `ItemsUpdatingScrollMode` property is `KeepItemsInView`. Therefore, when new items are added to a <xref:Microsoft.Maui.Controls.CollectionView> the first item in the list will remain displayed. To ensure that the last item in the list is displayed when new items are added, set the `ItemsUpdatingScrollMode` property to `KeepLastItemInView`:
+The default value of the <xref:Microsoft.Maui.Controls.ItemsView.ItemsUpdatingScrollMode> property is `KeepItemsInView`. Therefore, when new items are added to a <xref:Microsoft.Maui.Controls.CollectionView> the first item in the list will remain displayed. To ensure that the last item in the list is displayed when new items are added, set the <xref:Microsoft.Maui.Controls.ItemsView.ItemsUpdatingScrollMode> property to `KeepLastItemInView`:
 
 ```xaml
 <CollectionView ItemsUpdatingScrollMode="KeepLastItemInView">
@@ -191,7 +191,7 @@ CollectionView collectionView = new CollectionView
 
 ## Scroll bar visibility
 
-<xref:Microsoft.Maui.Controls.CollectionView> defines `HorizontalScrollBarVisibility` and `VerticalScrollBarVisibility` properties, which are backed by bindable properties. These properties get or set a `ScrollBarVisibility` enumeration value that represents when the horizontal, or vertical, scroll bar is visible. The `ScrollBarVisibility` enumeration defines the following members:
+<xref:Microsoft.Maui.Controls.CollectionView> defines `HorizontalScrollBarVisibility` and `VerticalScrollBarVisibility` properties, which are backed by bindable properties. These properties get or set a <xref:Microsoft.Maui.ScrollBarVisibility> enumeration value that represents when the horizontal, or vertical, scroll bar is visible. The <xref:Microsoft.Maui.ScrollBarVisibility> enumeration defines the following members:
 
 - `Default` indicates the default scroll bar behavior for the platform, and is the default value for the `HorizontalScrollBarVisibility` and `VerticalScrollBarVisibility` properties.
 - `Always` indicates that scroll bars will be visible, even when the content fits in the view.
@@ -201,8 +201,8 @@ CollectionView collectionView = new CollectionView
 
 When a user swipes to initiate a scroll, the end position of the scroll can be controlled so that items are fully displayed. This feature is known as snapping, because items snap to position when scrolling stops, and is controlled by the following properties from the `ItemsLayout` class:
 
-- `SnapPointsType`, of type `SnapPointsType`, specifies the behavior of snap points when scrolling.
-- `SnapPointsAlignment`, of type `SnapPointsAlignment`, specifies how snap points are aligned with items.
+- `SnapPointsType`, of type <xref:Microsoft.Maui.Controls.SnapPointsType>, specifies the behavior of snap points when scrolling.
+- `SnapPointsAlignment`, of type <xref:Microsoft.Maui.Controls.SnapPointsAlignment>, specifies how snap points are aligned with items.
 
 These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
 
@@ -211,7 +211,7 @@ These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> o
 
 ### Snap points type
 
-The `SnapPointsType` enumeration defines the following members:
+The <xref:Microsoft.Maui.Controls.SnapPointsType> enumeration defines the following members:
 
 - `None` indicates that scrolling does not snap to items.
 - `Mandatory` indicates that content always snaps to the closest snap point to where scrolling would naturally stop, along the direction of inertia.
@@ -223,7 +223,7 @@ By default, the `SnapPointsType` property is set to `SnapPointsType.None`, which
 
 ### Snap points alignment
 
-The `SnapPointsAlignment` enumeration defines `Start`, `Center`, and `End` members.
+The <xref:Microsoft.Maui.Controls.SnapPointsAlignment> enumeration defines `Start`, `Center`, and `End` members.
 
 > [!IMPORTANT]
 > The value of the `SnapPointsAlignment` property is only respected when the `SnapPointsType` property is set to `Mandatory`, or `MandatorySingle`.