PSPDFDocumentViewController
Objective-C
@interface PSPDFDocumentViewController : UIViewController <PSPDFOverridable>
Swift
class PDFDocumentViewController : UIViewController, Overridable
The document view controller is the starting point for visualizing a document on screen. It groups all the UI that deals with showing documents on screen and controls the view hierarchy and the layout.
The Layout
The main way of controlling how a layout looks is through PSPDFDocumentViewLayout
.
While PSPDFKit provides you with a set of default layouts such as a continuous
scrolling layout, a paginated scroll per spread layout and a curl based layout,
layouts are meant to be fully customizable so you can adopt PSPDFKit to your design
perfectly.
To customize a design you can start by changing properties on a design provided
by PSPDFKit. If this is not enough, PSPDFDocumentViewLayout
and its subclasses
provide various levels of entry points to best fit what your desired outcome is.
You can either subclass PSPDFContinuousScrollingLayout
or PSPDFScrollPerSpreadLayout
if you want a layout similar to these two but only need a couple of tweaks. If
you want to have more control but your layout still follows the general idea of
a layout that scrolls in a single direction, either vertically or horizontally,
PSPDFStackViewLayout
, gives you a lot of control while covering the basics and
a couple of convenience methods that make your life easier. This should be enough
control for almost all designs. However if your design is very specific, we also
give you the same base class all of our own layouts use: PSPDFDocumentViewLayout
.
With this layout you need to do everything on your own but there should be pretty
much no limitations on what to do with it.
To get you started with implementing your own layout, check out the documentation
for PSPDFDocumentViewLayout
.
The Hierarchy
The document view hierarchy can be seen in the following diagram.
╔═══════════════════════════╗ ┌───────────────────────────┐
║ DocumentViewController ║ │ PSPDFDocumentViewLayout │
║ ║────────▶│ │
╚═══════════════════════════╝ └───────────────────────────┘
┌───────────────────────────┐
│ UIScrollView │
│ (scrolling & zooming) │◀───┐ Depending on
└───────────────────────────┘ │ spreadBasedZooming either
┌───────────────────────────┐ ├──── one of these scroll views
│ UIScrollView │ │ is responsible for zooming
│ (zooming) │◀───┘ the content.
└───────────────────────────┘
╔═══════════════════════════╗
║ SpreadView ║
║ ║
╚═══════════════════════════╝
╔═══════════════════════════╗
║ PageView ║
║ ║
╚═══════════════════════════╝
┌─────────────────────────────────────────────────────────────────┐
│ ═══ Subclassable │
└─────────────────────────────────────────────────────────────────┘
Continuous Spread Index
Usually you should prefer the integer based spreadIndex
APIs. The spreadIndex
is less complex and does the necessary conversion to the continuous spread index
for you. However there are use cases where you need floating point precision for
the current scrolling position.
The continuousSpreadIndex
maps the spreads of the document on to the viewport
in a size independent way. That means that no matter what size a spread is displayed
on and also no matter what other spread sizes are already known of a document,
the continuous spread index remains stable. E.g. a continuous spread index of 2.5
will always refer to the center of spread 2.
In the places where a continuous spread index is related to a certain position
in the view hierarchy, it is related to the center of the current viewport. So
if you call continuousSpreadIndex
you will receive the continuous spread index
that is currently shown at the center of the document view controller’s view.
If you implement your own custom layout and this layout does not build on top of
PSPDFStackViewLayout
, you may need to deal with the continuous spread index though
and do calculations between the continuous spread index and the content offset
yourself. For that it is important how the function of the continuous spread index
looks. It is a monotonically increasing function over all spreads of a document.
Its valid range is [0, spreadCount)
. Note that it is monotonically, but not strictly
monotonically increasing. The spaces between spread are not considered to be a
part of a spread, therefore in this area, the continuous spread index does not
change. E.g. spread 2 has a range of [2, 3)
, then there is the inter-item spacing
between spread 2 and 3 where the continuous spread index is 3 and only when you
start scrolling into spread 3, the continuous spread index starts increasing again
in the range of [3, 4)
for this spread.
3.0 ─│ ╱
│ ╱
│ ╱ This diagram shows how the continuous spread index
│ ╱ is calculated over the spreads. In the gap between
2.0 ─│ ╱─╱ two spreads, the continuous spread index is not
│ ╱ changing.
│ ╱
│ ╱ Inside each spread, the continuous spread index is
1.0 ─│ ╱─╱ linear in the range [i, i+1).
│ ╱
│ ╱
│╱
╳────────────────
┌───┐ ┌───┐ ┌───┐
│ │ │ │ │ │
│ 0 │ │ 1 │ │ 2 │
│ │ │ │ │ │
└───┘ └───┘ └───┘
-
Unavailable
Not the designated initializer
Undocumented
Declaration
Objective-C
PSPDF_DEFAULT_VIEWCONTROLLER_INIT_UNAVAILABLE
-
Unavailable
Not the designated initializer
Undocumented
Declaration
Objective-C
PSPDF_DEFAULT_VIEWCONTROLLER_INIT_UNAVAILABLE
-
Unavailable
Not the designated initializer
Undocumented
Declaration
Objective-C
PSPDF_DEFAULT_VIEWCONTROLLER_INIT_UNAVAILABLE
-
Unavailable
Not the designated initializer
Undocumented
Declaration
Objective-C
PSPDF_DEFAULT_VIEWCONTROLLER_INIT_UNAVAILABLE
-
The delegate to be used to receive updates about spread views, spread changes and other document view controller related events.
Declaration
Objective-C
@property (nonatomic, weak) id<PSPDFDocumentViewControllerDelegate> _Nullable delegate;
Swift
weak var delegate: PDFDocumentViewControllerDelegate? { get set }
-
The layout being used to render the current document.
Changing the layout will cause the view to refresh with the new layout without any animation.
Declaration
Objective-C
@property (nonatomic) PSPDFDocumentViewLayout *_Nonnull layout;
Swift
var layout: PSPDFDocumentViewLayout { get set }
-
The spread index that should be displayed by the view controller.
A spread describes a collection of continuous pages that are grouped in a logical container from the layout. E.g. if you have a book, when the book is open you will always see two pages next to each other. These two pages build one spread. If you have a stack of loose paper on the other hand, you always only see one page, so a spread only consists of one page in that example.
This property is key value observable.
Setting the spread index will be ignored if the document is not valid (e.g. locked).
See
PSPDFSpreadView
Declaration
Objective-C
@property (nonatomic) NSInteger spreadIndex;
Swift
var spreadIndex: Int { get set }
-
Sets the spread index of a document either in an animated way or without animating.
See
-setSpreadIndex:
Declaration
Objective-C
- (void)setSpreadIndex:(NSInteger)spreadIndex animated:(BOOL)animated;
Swift
func setSpreadIndex(_ spreadIndex: Int, animated: Bool)
Parameters
spreadIndex
The index of the spread you want to become visible.
animated
Whether or not you want the scrolling to be animated.
-
Scrolls so the specified spread is visible in the document view either in an animated way or without animating.
Note
The
position
parameter is only applicable if the view controller view is already loaded and only for continuous (non paginated) scrolling.Declaration
Objective-C
- (void)scrollToSpreadAtIndex:(NSInteger)spreadIndex scrollPosition:(PSPDFSpreadScrollPosition)position animated:(BOOL)animated;
Swift
func scrollToSpread(at spreadIndex: Int, scrollPosition position: PSPDFSpreadScrollPosition, animated: Bool)
Parameters
spreadIndex
The destination spread index.
position
The position of the spread in the document view viewport.
animated
Whether the scrolling should be animated or not.
-
The continuous spread index that should be displayed by the view controller.
A spread describes a collection of continuous pages that are grouped in a logical container from the layout. E.g. if you have a book, when the book is open you will always see two pages next to each other. These two pages build one spread. If you have a stack of loose paper on the other hand, you always only see one page, so a spread only consists of one page in that example.
The continuous spread index is relative to the center of the view’s viewport, so to center a spread in the scroll view, you need to set the continuous spread view to the spreads center. E.g. when you want to have spread index 2 centered on screen you need to set the continuous spread index to 2.5.
If you are not interested in the inter-spread offset, there are integer based methods available as well to read and modify the spread index. If you do not need the inter-spread granularity, the integer based methods should be preferred.
This property is key value observable.
Setting the continuous spread index will be ignored if the document is not valid (e.g. locked).
See
PSPDFSpreadView
See
spreadIndex
Declaration
Objective-C
@property (nonatomic) CGFloat continuousSpreadIndex;
Swift
var continuousSpreadIndex: CGFloat { get set }
-
Sets the continuous spread index of a document either in an animated way or without animating.
See
-setSpreadIndex:
Declaration
Objective-C
- (void)setContinuousSpreadIndex:(CGFloat)continuousSpreadIndex animated:(BOOL)animated;
Swift
func setContinuousSpreadIndex(_ continuousSpreadIndex: CGFloat, animated: Bool)
Parameters
continuousSpreadIndex
The index of the spread you want to become visible.
animated
Whether or not you want the scrolling to be animated.
-
Scrolls to the next spread based on the current
spreadIndex
value.Declaration
Objective-C
- (BOOL)scrollToNextSpreadAnimated:(BOOL)animated;
Swift
func scrollToNextSpread(animated: Bool) -> Bool
Parameters
animated
true
if the transition should be animated,false
otherwise.Return Value
true
if the transition was successful,false
otherwise (e.g. if we are already on the last spread). -
Scrolls to the previous spread based on the current
spreadIndex
value.Declaration
Objective-C
- (BOOL)scrollToPreviousSpreadAnimated:(BOOL)animated;
Swift
func scrollToPreviousSpread(animated: Bool) -> Bool
Parameters
animated
true
if the transition should be animated,false
otherwise.Return Value
true
if the transition was successful,false
otherwise (e.g. if we are already on the first spread). -
Scrolls to the “next” viewport, preserving zoom scale.
Declaration
Objective-C
- (BOOL)scrollToNextViewportAnimated:(BOOL)animated;
Swift
func scrollToNextViewport(animated: Bool) -> Bool
Parameters
animated
Specifies whether the scroll should be animated.
Return Value
true
if the scroll occurred, elsefalse
. -
Scrolls to the “previous” viewport, preserving zoom scale.
Declaration
Objective-C
- (BOOL)scrollToPreviousViewportAnimated:(BOOL)animated;
Swift
func scrollToPreviousViewport(animated: Bool) -> Bool
Parameters
animated
Specifies whether the scroll should be animated.
Return Value
true
if the scroll occurred, elsefalse
. -
Switches to a particular spread index and then zooms to a given rect on that page.
If you want to show a particular part of a document initially (before the view hierarchy has been set up) then use
applyViewState(_:animateIfPossible:)
on thePDFViewController
instead of this method.Declaration
Objective-C
- (void)zoomToPDFRect:(CGRect)pdfRect forPageAtIndex:(NSInteger)pageIndex animated:(BOOL)animated;
Swift
func zoom(toPDFRect pdfRect: CGRect, forPageAt pageIndex: Int, animated: Bool)
Parameters
pdfRect
The rect that should be zoomed on in PDF coordinates. If this is
CGRectNull
, the full page will be visible.pageIndex
The page index of the page on which the given
pdfRect
should be zoomed to.animated
true
if the change and zoom should be animated,false
otherwise. -
Controls whether the user can scroll through a document or not
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite, getter=isScrollEnabled) BOOL scrollEnabled;
Swift
var isScrollEnabled: Bool { get set }
-
Controls whether the user can zoom inside a document or not
Declaration
Objective-C
@property (nonatomic, getter=isZoomEnabled) BOOL zoomEnabled;
Swift
var isZoomEnabled: Bool { get set }
-
Controls whether the view responsible for scrolling should always bounce. If the layout is a directional layout (i.e. it inherits from
PSPDFStackViewLayout
), bouncing only occurs in the direction of the layout.Defaults to
false
.Declaration
Objective-C
@property (nonatomic) BOOL alwaysBounce;
Swift
var alwaysBounce: Bool { get set }
-
The boolean value that indicates whether the view responsible for scrolling should show scroll indicators or not.
Default:
false
if the layout uses spread-based zooming, otherwisetrue
.Declaration
Objective-C
@property (nonatomic) BOOL showsScrollIndicator;
Swift
var showsScrollIndicator: Bool { get set }
-
The spread views that are currently visible, ordered by their spread index.
Declaration
Objective-C
@property (nonatomic, copy, readonly) NSArray<PSPDFSpreadView *> *_Nonnull visibleSpreadViews;
Swift
var visibleSpreadViews: [PSPDFSpreadView] { get }
-
Asks the document view controller for a currently visible page view at the given location.
Declaration
Objective-C
- (nullable PSPDFPageView *)visiblePageViewAtPoint:(CGPoint)point;
Swift
func visiblePageView(at point: CGPoint) -> PSPDFPageView?
Return Value
A page view that is currently visible at the given location, or
nil
if there is none.