UIPageViewController Class Reference

Inherits from
UIViewController : UIResponder : NSObject
Conforms to
NSCoding (UIViewController)
UIAppearanceContainer (UIViewController)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 5.0 and later.
Companion guide
View Controller Catalog for iOS
Declared in
UIPageViewController.h
Related sample code

Overview

A page view controller lets the user navigate between pages of content, where each page is managed by its own view controller object. Navigation can be controlled programmatically by your app or directly by the user using gestures. When navigating from page to page, the page view controller uses the transition that you specify to animate the change.

When defining a page view controller interface, you can provide the content view controllers one at a time (or two at a time, depending upon the spine position and double-sided state) or as-needed using a data source. When providing content view controllers one at a time, you use the setViewControllers:direction:animated:completion: method to set the current content view controllers. To support gesture-based navigation, you must provide your view controllers using a data source object.

The data source for a page view controller is responsible for providing the content view controllers on demand and must conform to the UIPageViewControllerDataSource protocol. The delegate object—an object that conforms to the UIPageViewControllerDelegate protocol—provides some appearance-related information and receives notifications about gesture-initiated transitions.

This class is generally used as-is but may be subclassed in iOS 6 and later.

Tasks

Creating Page View Controllers

Providing Content

Display Options

Properties

dataSource

The object that provides view controllers.

@property(nonatomic, assign) id<UIPageViewControllerDataSource> dataSource
Discussion

Methods of the data source are called in response to gesture-based navigation. If the value of this property is nil, then gesture-based navigation is disabled.

Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
UIPageViewController.h

delegate

The delegate object.

@property(nonatomic, assign) id<UIPageViewControllerDelegate> delegate
Discussion

Methods of the delegate are called in response to gesture-based navigation and orientation changes.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPageViewController.h

doubleSided

A Boolean value that indicates whether content appears on the back of pages.

@property(nonatomic, getter=isDoubleSided) BOOL doubleSided
Discussion

The default value for this property is NO.

If the back of pages has no content (the value is NO), then the content on the front of the page will partially show through to the back when turning pages.

If the spine is located in the middle, the value must be YES. Setting it to NO with the spine located in the middle raises an exception.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPageViewController.h

gestureRecognizers

An array of UIGestureRecognizer objects that are configured to handle user interaction. (read-only)

@property(nonatomic, readonly) NSArray *gestureRecognizers
Discussion

These gesture recognizers are initially attached to a view in the page view controller’s hierarchy. To change the region of the screen in which the user can navigate using gestures, they can be placed on another view.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPageViewController.h

navigationOrientation

The direction along which navigation occurs. (read-only)

@property(nonatomic, readonly) UIPageViewControllerNavigationOrientation navigationOrientation
Availability
  • Available in iOS 5.0 and later.
Declared In
UIPageViewController.h

spineLocation

The location of the spine. (read-only)

@property(nonatomic, readonly) UIPageViewControllerSpineLocation spineLocation
Discussion

The value of this property is set with the UIPageViewControllerOptionSpineLocationKey key when the page view controller is initialized, and can be changed by returning the new value from the pageViewController:spineLocationForInterfaceOrientation: method of the delegate.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPageViewController.h

transitionStyle

The style used to transition between view controllers. (read-only)

@property(nonatomic, readonly) UIPageViewControllerTransitionStyle transitionStyle
Discussion

The value of this property is set when the page view controller is initialized, and cannot be changed.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPageViewController.h

viewControllers

The view controllers displayed by the page view controller. (read-only)

@property(nonatomic, readonly) NSArray *viewControllers
Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIPageViewController.h

Instance Methods

initWithTransitionStyle:navigationOrientation:options:

Initializes a newly created page view controller.

- (id)initWithTransitionStyle:(UIPageViewControllerTransitionStyle)style navigationOrientation:(UIPageViewControllerNavigationOrientation)navigationOrientation options:(NSDictionary *)options
Parameters
style

The style for transitions between pages.

navigationOrientation

The orientation of the page-by-page navigation.

options

A dictionary of options. For keys, see “Options Keys.”

Return Value

The initialized page view controller.

Discussion

After initialization, use the setViewControllers:direction:animated:completion: method to set the initial view controllers.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPageViewController.h

setViewControllers:direction:animated:completion:

Sets the view controllers to be displayed.

- (void)setViewControllers:(NSArray *)viewControllers direction:(UIPageViewControllerNavigationDirection)direction animated:(BOOL)animated completion:(void (^)(BOOL finished))completion
Parameters
viewControllers

The view controller or view controllers to be displayed.

direction

The navigation direction.

animated

A Boolean value that indicates whether the transition is to be animated.

completion

A block to be called when the page-turn animation completes.

The block takes the following parameters:

finished

YES if the animation finished; NO if it was skipped.

Discussion

The view controllers passed to this method are those that will be visible after the animation has completed. Use a data source to provide additional view controllers to which users navigate.

If the transition style is UIPageViewControllerTransitionStylePageCurl, the view controllers to pass in the viewControllers parameter depends on the spine location and the value of the doubleSided property:

Spine location

Double sided

What to pass

UIPageViewControllerSpineLocationMid

YES

Pass the page to be displayed on the left and the page to be displayed on the right.

UIPageViewControllerSpineLocationMin or UIPageViewControllerSpineLocationMax

YES

Pass the front of the page to be displayed and the back of the previously-displayed page. The back is used for the page turning animation.

UIPageViewControllerSpineLocationMin or UIPageViewControllerSpineLocationMax

NO

Pass the front of the page to be displayed.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIPageViewController.h

Constants

Navigation Orientations

Orientations for page-turn transitions.

enum {
   UIPageViewControllerNavigationOrientationHorizontal = 0,
   UIPageViewControllerNavigationOrientationVertical = 1
};
typedef NSInteger UIPageViewControllerNavigationOrientation;
Constants
UIPageViewControllerNavigationOrientationHorizontal

Horizontal orientation, with pages turning left and right.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

UIPageViewControllerNavigationOrientationVertical

Vertical orientation, with pages turning up and down.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

Navigation Directions

Directions for page-turn transitions.

enum {
   UIPageViewControllerNavigationDirectionForward,
   UIPageViewControllerNavigationDirectionReverse
};
typedef NSInteger UIPageViewControllerNavigationDirection;
Constants
UIPageViewControllerNavigationDirectionForward

Navigation to the next page.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

UIPageViewControllerNavigationDirectionReverse

Navigation to the previous page.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

Discussion

For horizontal navigation, pages turn from the right side of the screen to the left as you navigate forward.

For vertical navigation, pages turn from the bottom of the screen to the top as you navigate forward.

Transition Styles

Styles for the page-turn transition.

enum {
   UIPageViewControllerTransitionStylePageCurl = 0
   UIPageViewControllerTransitionStyleScroll = 1
};
typedef NSInteger UIPageViewControllerTransitionStyle;
Constants
UIPageViewControllerTransitionStylePageCurl

Page curl transition style.

When the page curl transition style is specified, the page view controller displays a page-turning animation when transitioning between view controllers. If a data source is specified, the animation follows the user’s finger during a navigation gesture.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

UIPageViewControllerTransitionStyleScroll

Scrolling transition style.

When the page scrolling style is specified, the page view controller displays a page-scrolling animation when transitioning between view controllers. If a data source is specified, the animation follows the user’s finger during a navigation gesture.

Available in iOS 6.0 and later.

Declared in UIPageViewController.h.

Options Keys

Keys for the options dictionary.

NSString * const UIPageViewControllerOptionSpineLocationKey;
NSString * const UIPageViewControllerOptionInterPageSpacingKey;
Constants
UIPageViewControllerOptionSpineLocationKey

Location of the spine.

For possible values, see “Spine Locations.” A spine location is only valid if the transition style is UIPageViewControllerTransitionStylePageCurl.

If the transition style is UIPageViewControllerTransitionStylePageCurl, the default value for this property is UIPageViewControllerSpineLocationMin; otherwise, the default is UIPageViewControllerSpineLocationNone.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

UIPageViewControllerOptionInterPageSpacingKey

Space between pages, in points.

The value should be a CGFloat wrapped in an instance of NSNumber. The default value is zero. An inter-page spacing is only valid if the transition style is UIPageViewControllerTransitionStyleScroll.

Available in iOS 6.0 and later.

Declared in UIPageViewController.h.

Discussion

See also initWithTransitionStyle:navigationOrientation:options:.

Spine Locations

Locations for the spine.

enum {
   UIPageViewControllerSpineLocationNone = 0,
   UIPageViewControllerSpineLocationMin = 1,
   UIPageViewControllerSpineLocationMid = 2,
   UIPageViewControllerSpineLocationMax = 3
};
typedef NSInteger UIPageViewControllerSpineLocation;
Constants
UIPageViewControllerSpineLocationNone

No spine.

This spine location is not valid if the transition style is UIPageViewControllerTransitionStylePageCurl.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

UIPageViewControllerSpineLocationMin

Spine at the left or top edge of the screen.

One view controller is displayed at a time.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

UIPageViewControllerSpineLocationMid

Spine in the middle or the screen.

Two view controllers are displayed at a time.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

UIPageViewControllerSpineLocationMax

Spine at the right or bottom edge of the screen.

One view controller is displayed at a time.

Available in iOS 5.0 and later.

Declared in UIPageViewController.h.

Discussion

To set the spine location, wrap one of these constants in an NSNumber object and set it as the value for the UIPageViewControllerOptionSpineLocationKey key in the options dictionary passed to the initWithTransitionStyle:navigationOrientation:options: method.



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-12-13)

Did this document help you? Yes It's good, but... Not helpful...