ScrollView

Use ScrollView to present layouts that can't fit on just one screen and have content make room for the keyboard.

PDF for offline use
Sample Code:

Let us know how you feel about this


0/250

last updated: 2016-04

ScrollView contains layouts and enables them to scroll offscreen. ScrollView is also used to allow views to automatically move to the visible portion of the screen when the keyboard is showing.

This article covers:

  • Purpose – the purpose for ScrollView and when it is used.
  • Usage – how to use ScrollView in practice.
  • Properties – public properties that can be read and modified.
  • Methods – public methods that can be called to scroll the view.
  • Events – events that can be used to listen to changes in the view's states.

Purpose

ScrollView can be used to ensure that larger views display well on smaller phones. For example, a layout that works on an iPhone 6s may be clipped on an iPhone 4s. Using a ScrollView would allow the clipped portions of the layout to be displayed on the smaller screen.

Usage

Note: ScrollViews should not be nested. In addition, ScrollViews should not be nested with other controls that provide scrolling, like ListView and WebView.

ScrollView exposes a Content property which can be set to a single view or layout. Consider this example of a layout with a very large boxView, followed by an Entry:

<ContentPage.Content>
    <ScrollView>
        <StackLayout>
            <BoxView BackgroundColor="Red" HeightRequest="600" WidthRequest="150" />
            <Entry />
        </StackLayout>
    </ScrollView>
</ContentPage.Content>

In C#:

var scroll = new ScrollView();
Content = scroll;
var stack = new StackLayout();
stack.Children.Add(new BoxView { BackgroundColor = Color.Red,   HeightRequest = 600, WidthRequest = 600 });
stack.Children.Add(new Entry());

Before the user scrolls down, only the BoxView is visible:

Notice that when the user starts to enter text in the Entry, the view scrolls to keep it visible on screen:

Properties

ScrollView has the following properties:

  • Content – gets or sets the view to display in the ScrollView.
  • ContentSize – read-only, gets the size of the content, which has a width and height component. This is a bindable property
  • Orientation – This is a ScrollOrientation, which is an enumeration that can be set to Horizontal, Vertical, or Both.
  • ScrollX – read-only, gets the current scroll position in the X dimension.
  • ScrollY – read-only, gets the current scroll position in the Y dimension.

Methods

ScrollView provides a ScrollToAsync method, which can be used to scroll the view either using coordinates or by specifying a particular view that should be made visible.

When using coordinates, specify the x and y coordinates, along with a boolean indicating whether the scrolling should be animated:

scroll.ScrollToAsync(0, 150, true); //scrolls so that the position at 150px from the top is visible

scroll.ScrollToAsync(label, ScrollToPosition.Start, true); //scrolls so that the label is at the start of the list

When scrolling to a particular element, the ScrollToPosition enumeration specifes where in the view the element will appear:

  • Center – scrolls the element to the center of the visible portion of the view.
  • End – scrolls the element to the end of the visible portion of the view.
  • MakeVisible – scrolls the element so that it is visible within the view.
  • Start – scrolls the element to the start of the visible portion of the view.

The IsAnimated property specifies how the view will be scrolled. When set to true, a smooth animation will be used, rather than instantly moving the content into view.

Events

ScrollView exposes just one event, Scrolled. Scrolled is raised when the view has finished scrolling. The event handler for Scrolled takes ScrolledEventArgs, which has the ScrollX and ScrollY properties. The following demonstrates how to update a label with the current scroll position of a ScrollView:

Label label = new Label { Text = "Position: " };
ScrollView scroll = new ScrollView();
scroll.Scrolled += (object sender, ScrolledEventArgs e) => {
    label.Text = "Position: " + e.ScrollX + " x " + e.ScrollY;
};

Note that scroll positions may be negative, due to the bounce effect when scrolling at the end of a list.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.