The UIKit.UIScrollView class is a container that provides scrolling, zooming, and panning functionality of its content view. Because the UIKit.UIScrollView class provides out-of-the-box functionality for scrolling and paging, it is generally used as the basis for UIKit.UIViews whose content is larger than the UIKit.UIScrollView's UIView.Frame. The need for and range of scrolling is specified by the application developer setting the UIKit.UIScrollView's UIScrollView.ContentSize to a System.Drawing.SizeF greater than the UIKit.UIScrollView's UIView.Frame.

The most common ways to use the UIKit.UIScrollView are to either:

• Add a single large subview, generally with a UIView.Frame whose System.Drawing.RectangleF.Location is [0,0] and whose System.Drawing.SizeF is the same as the UIKit.UIScrollView's UIScrollView.ContentSize; or
• Arrange multiple subviews within the UIKit.UIScrollView's UIScrollView.ContentSize and use the UIKit.UIScrollView to scroll between them or, by setting UIScrollView.PagingEnabled to true, to page between them. This is often done in conjunction with a UIKit.UIPageControl; or
• Subclass UIKit.UIScrollView and extend it's functionality. In fact, the UIKit.UIScrollView is the base class of such commonly-used classes as UIKit.UITextField and UIKit.UITableView.

Using A Single Large Subview

The following image, drawn from the "Scroll View" demo in the "iOS Standard Controls" sample, illustrates the simplest use-case: a single large subview (in this case, a UIKit.UIImageView) whose image size matches the UIKit.UIScrollView's UIScrollView.ContentSize. The UIScrollView.ContentOffset of the UIKit.UIScrollView corresponds to the image pixel showing at the origin of the UIKit.UIImageView (e.g., System.Drawing.PointF [215, 145]). The UIScrollView.ContentSize of the UIKit.UIScrollView defines the scroll limits. When the UIScrollView.ContentSize is larger than the UIKit.UIScrollView's UIView.Frame, one gets scrolling behavior. If UIScrollView.ContentSize is not set or is set to too small a System.Drawing.RectangleF, one doesn't (however, UIScrollView.AlwaysBounceVertical and UIScrollView.AlwaysBounceHorizontal can be used to allow dragging even in this situation.)

As the following code shows, it's straightforward to create and use a UIKit.UIScrollView in this manner. The imageView is initialized from a file. The UIKit.UIScrollView's UIScrollView.ContentSize is set to the size of the image (which happens to be 512 x 512 pixels and thus large enough to require scrolling unless zoomed out) and the imageView is added as a subview.

The delegate for the UIScrollView.ViewForZoomingInScrollView property allows the UIKit.UIScrollView to automatically handle pinch-to-zoom gestures:

// create our scroll view
scrollView = new UIScrollView (
new RectangleF (0, 0, this.View.Frame.Width, this.View.Frame.Height - this.NavigationController.NavigationBar.Frame.Height));
this.View.AddSubview (scrollView);

// create our image view
imageView = new UIImageView (UIImage.FromFile ("Images/Icons/512_icon.png"));
scrollView.ContentSize = imageView.Image.Size;
scrollView.MaximumZoomScale = 3f;
scrollView.MinimumZoomScale = .1f;
scrollView.AddSubview (imageView);

scrollView.ViewForZoomingInScrollView += (UIScrollView sv) => { return imageView; };
                

The UIKit.UIScrollView tracks the location of the application-user's fingers and updates the UIKit.UIScrollView's UIScrollView.ContentSize and UIScrollView.ZoomScale as they drag, swipe, and make pinch-to-zoom gestures. The UIKit.UIScrollView draws the briefly-visible scroll-location indicators, shows the content clipped from its subviews, and animates the scrolling, panning, and zooming transitions. As the gesture or animation proceeds, the UIKit.UIScrollView adjusts the UIScrollView.ContentOffset and UIScrollView.ZoomScale appropriately and repeatedly fires the UIScrollView.Scrolled event.

Panning and Paging

The next image, from the "Page Control" demo in the iOS Standard Controls sample, illustrates multiple subviews aligned within the boundaries of the UIKit.UIScrollView's UIScrollView.ContentSize. The illustration shows the application in the middle of a swiping animation; portions of both the white and gray subviews are visible.

If UIScrollView.PagingEnabled is set to true or if the gesture attempts to scroll to an area outside the UIKit.UIScrollView's UIScrollView.ContentSize, at the end of the gesture the selected subview will "bounce" into alignment with the UIKit.UIScrollView's UIView.Frame.

It is up to the application developer to synchronize with the UIKit.UIPageControl if one is used. A common way to do this is to handle the UIKit.UIScrollView's UIScrollView.Scrolled event and change the model value that is observed by the UIKit.UIPageControl (or one can imperatively set the UIKit.UIPageControl's UIPageControl.CurrentPage).

In the paging demo, the UIView.Frames of the individual subviews and the UIScrollView.ContentSize of the UIKit.UIScrollView are calculated, aligned, and set using the following code, taken from the "iOS Standard Controls" sample:

// instantiate and add the controllers to our list
controllers.Add (new Controller_1 ());
controllers.Add (new Controller_2 ());
controllers.Add (new Controller_3 ());

for (int i = 0; i < controllers.Count; i++)
{
	// set their location and size, each one is moved to the 
	// right by the width of the previous
	RectangleF viewFrame = new RectangleF (
	scrlMain.Frame.Width * i,
	scrlMain.Frame.Y,
	scrlMain.Frame.Width,
	scrlMain.Frame.Height);
	controllers[i].View.Frame = viewFrame;

	// add the view to the scrollview
	scrlMain.AddSubview (controllers[i].View);
}

// set our scroll view content size (width = number of pages * scroll view width)
scrlMain.ContentSize = new SizeF (
scrlMain.Frame.Width * controllers.Count, scrlMain.Frame.Height);
                

Tap-To-Zoom

The "tap-to-zoom" gesture consists of the application user double-tapping the scrolling area. To enable this, the developer needs to create a UIKit.UITapGestureRecognizer, configure it for two taps, give it a unique ObjCRuntime.Selector, and add it to the UIKit.UIScrollView. Then, the developer has to implement a method with an Foundation.ExportAttribute configured to the Selector identifier.

The following code from the "Implement Tap-To-Zoom Recipe" shows the essential steps:

UITapGestureRecognizer doubletap = new UITapGestureRecognizer();
doubletap.NumberOfTapsRequired = 2; // double tap
doubletap.AddTarget (this, new ObjCRuntime.Selector("DoubleTapSelector"));
scrollView.AddGestureRecognizer(doubletap); // detect when the scrollView is double-tapped
//...etc...

[Foundation.Export("DoubleTapSelector")]
public void OnDoubleTap (UIGestureRecognizer sender) {
if (scrollView.ZoomScale >= 1)
   scrollView.SetZoomScale(0.25f, true);
else
   scrollView.SetZoomScale(2f, true);
}
                

Touch Delays Associated with UIScrollView

Because scrolling and zooming gestures can begin anywhere on the screen, the UIKit.UIScrollView intercepts touch events and waits briefly to see if the application user is making a scrolling or zooming gesture. This introduces a small delay but the default behavior can be customized by overriding the UIKit.UIScrollView's UIScrollView.TouchesShouldBegin and UIScrollView.TouchesShouldCancelInContentView methods.

Subview Frames

Although generally the UIView.Frames of the content UIKit.UIViews are aligned with the extent of the UIKit.UIScrollView's UIScrollView.ContentSize and each other, this is not a requirement. Setting the UIView.Frame so that it extends beyond the boundaries of the UIScrollView.ContentSize may make drawing geometry easier or more consistent. If, by misaligning subviews, one displays an area within the UIScrollView.ContentSize of the UIKit.UIScrollView that does not contain a UIKit.UIView, gestures for scrolling and zooming occurring in the blank area will not work: the application must have an underlying UIKit.UIView to get the expected behavior.

Some domains, such as maps and gameboards, may seem to suggest a design in which a UIKit.UIScrollView has a large number of tiled subviews. However, all subviews -- whether visible or not -- are rendered and this can be resource- and processor-intensive. In such cases, it is the application developer's responsibility to add or remove subviews appropriately.

Event Sequence

The following illustration shows the user actions and resulting UIKit.UIScrollView event sequence associated with a dragging or swiping gesture:

• The user touches the screen;
• The user begins dragging;
• The UIScrollView.DraggingStarted event is raised;
• As long as the user continues dragging...
• The UIScrollView.Scrolled event is raised repeatedly;
• The user raises their finger...
• The UIScrollView.WillEndDragging event is raised;
• The UIKIt.UIScrollView.DraggingEnded event is raised;
• The UIScrollView.DecelerationStarted event is raised;
• As long as the scrolling animation continues...
• The UIScrollView.Scrolled event is raised repeatedly;
• The UIScroll.DevelerationEnded event is raised.

The following illustration shows the user actions and resulting UIKit.UIScrollView event sequence associated with a pinch-to-zoom gesture:

• The user touches the screen with two fingers;
• The user begins the pinch-to-zoom gesture;
• The UIScrollView.ZoomingStarted event is raised;
• As long as the user continues pinching...
• The UIScrollView.Scrolled event is raised repeatedly because the zooming is effecting the origin of the displayed content;
• The UIScrollView.DidZoom event is raised repeatedly;
• The user raises their fingers...
• The UIScrollView.ZoomingEnded event is raised;
• The UIKIt.UIScrollView.Scrolled event is raised as the content view bounces into alignment;

State Preservation and Restoration

In iOS 6 or later, if the UIView.RestorationIdentifier property is set, on restoration the UIKit.UIScrollView's UIScrollView.ZoomScale, UIScrollView.ContentOffset, and UIScrollView.ContentInset properties will be restored.

Event-handling

The MonoTouch API supports two styles of event notification: the Objective-C style that uses a delegate class or the C# style using event notifications.

The C# style allows the user to add or remove event handlers at runtime by assigning to the events of properties of this class. Event handlers can be anyone of a method, an anonymous methods or a lambda expression. Using the C# style events or properties will override any manual settings to the Objective-C Delegate or UIScrollView.WeakDelegate settings.

The Objective-C style requires the user to create a new class derived from UIKit.UIScrollViewDelegate class and assign it to the UIScrollView.Delegate property. Alternatively, for low-level control, by creating a class derived from Foundation.NSObject which has every entry point properly decorated with an [Export] attribute (see Foundation.ExportAttribute). The instance of this object can then be assigned to the UIScrollView.WeakDelegate property.