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).

    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).

    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, else false.

  • 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, else false.

  • 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 the PDFViewController 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, otherwise true.

    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.