Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding a Tip to specify ScrollTo may not work under specific condition's #2736

Merged
merged 4 commits into from
Jan 17, 2025
Merged

Adding a Tip to specify ScrollTo may not work under specific condition's #2736

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5640b8e
adding scrollTo tip
bhavanesh2001 Jan 16, 2025
df6536e
Merge branch 'main' into patch-1
davidbritch Jan 17, 2025
f9b80e7
Edit tip and add xrefs.
davidbritch Jan 17, 2025
3e9c703
Fix xrefs.
davidbritch Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/user-interface/controls/collectionview/includes/scrolling-tip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>.
44 changes: 22 additions & 22 deletions docs/user-interface/controls/collectionview/scrolling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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.
Expand All @@ -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">
Expand All @@ -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)
Expand All @@ -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);
Expand All @@ -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;
Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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">
Expand All @@ -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.
Expand All @@ -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.

Expand All @@ -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.
Expand All @@ -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`.
Expand Down
Loading