Appearance Styling


In order to seamlessly integrate PSPDFKit into your application, you will likely want to adjust some of the appearance settings of the framework UI elements. PSPDFKit was designed to be very flexible in this regard and offers a wide variety of appearance centric properties and customization hooks.

Tint color

PSPDFKit conforms to the standard UIView tintColor inherence scheme and will automatically adopt your application's global tint color. You can set the desired PSPDFKit tintColor by setting the tintColor property on your key window, or any other common superview of PSPDFKit view components. You are also free to set the tintColor property on any of the PSPDFKit UIView subclasses, either by setting the instance property directly or using the UIAppearance protocol.

Status bar

PSPDFKit was designed with view controller based status bar appearance in mind. In order to get the correct status bar appearance and behaviors for PSPDFKit view controllers, ensure the UIViewControllerBasedStatusBarAppearance flag in your app's Info.plist is set. (This is the default behavior, some old products might have set this to NO, in that case you first need to update your application.)

Note: When the application root view controller is a UINavigationController instance, the status bar appearance is deferred by the barStyle property of the navigation controller's navigationBar. Therefore, if you show PSPDFViewController in a UINavigationController, be sure to correctly set the navigation bar barStyle in order to get the desired status bar style.

UIAppearance

The recommended and easiest way to style PSDFKit to your liking is using the UIAppearance protocol. PSPDFKit instance properties that were designed to be used with UIAppearance are marked with the standard UI_APPEARANCE_SELECTOR qualifier.

Note: It is important that you apply UIAppearance settings early in your application (or view controller) lifecycle. The appearance settings should be in place before viewDidLoad: is called. This is especially true for iOS 8.1 and later.

UINavigationBar and UIToolbar styling

One of the most likely candidates for appearance customization are UINavigationBar and UIToolbar. If you are already setting the appearance of either of those using UIAppearance selectors in your app, than PSPDFKit will automatically inherit those settings.

Applying default styles to UINavigationBar and UIToolbar directly might however have the unwanted side effect of also leaking certain appearance styles to system provided view controllers (like MFMailComposeViewController). Thus we recommended that you instead limit the UINavigationBar and UIToolbar customization to your application only. In order to achieve the same for PSPDFKit, you can limit the appearance customization to instances inside PSPDFNavigationController. PSPDFNavigationController is a simple UINavigationController subclass that adds some additional features and is used throughout PSPDFKit. If you're presenting PSPDFViewController inside a UINavigationController (the most common case), you might want to use PSPDFNavigationController to ease styling. If you're using your own UINavigationController or embedding PSPDFViewController in another view controller, it will be your responsibility to style the container controller and use correct appearance bounding for UINavigationBar and UIToolbar.

UINavigationBar and UIToolbar in popovers

By default PSPDFKit removes any custom tinting on UINavigationBar and UIToolbar instances, contained inside a PSPDFNavigationController that is presented as a popover presentation. This ensures that the bars seamlessly blend with the default popover background view. We achieve this by setting UIAppearance properties on UINavigationBar and UIToolbar using the container syntax. In the process we set both the tintColor and barTintColor to nil and barStyle to UIBarStyleDefault.

If you want to override this behavior, you can do so in your initialization code, using the following appearance proxies.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
let navBarPopoverAppearance = UINavigationBar.appearance()
// iOS 10+ only, see http://stackoverflow.com/questions/24136874/appearancewhencontainedin-in-swift
// let navBarPopoverAppearance = UINavigationBar.appearance(whenContainedInInstancesOf:([PSPDFNavigationController.self, UIPopoverPresentationController.self]))
// e.g.
// navBarPopoverAppearance.tintColor = UIColor.red
// navBarPopoverAppearance.barTintColor = UIColor.white
let toolBarPopoverAppearance = UIToolbar.appearance()
// iOS 10+ only, see http://stackoverflow.com/questions/24136874/appearancewhencontainedin-in-swift
// let toolBarPopoverAppearance = UIToolbar.appearance(whenContainedInInstancesOf:([PSPDFNavigationController.self, UIPopoverPresentationController.self]))
// e.g.
// toolBarPopoverAppearance.tintColor = UIColor.red
// toolBarPopoverAppearance.barTintColor = UIColor.white
Copy
1
2
3
4
5
6
7
8
UINavigationBar *navBarPopoverAppearance = [UINavigationBar appearanceWhenContainedIn:PSPDFNavigationController.class, UIPopoverPresentationController.class, nil];
// e.g.
// navBarPopoverAppearance.tintColor = UIColor.redColor;
// navBarPopoverAppearance.barTintColor = UIColor.whiteColor
UIToolbar *toolBarPopoverAppearance = [UIToolbar appearanceWhenContainedIn:PSPDFNavigationController.class, UIPopoverPresentationController.class, nil];
// e.g.
// toolBarPopoverAppearance.tintColor = UIColor.redColor;
// toolBarPopoverAppearance.barTintColor = UIColor.whiteColor;

Basic appearance customization example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
let mainColor = UIColor(white: 0.2, alpha: 1)
let secondaryColor = UIColor.white
// Global (the window reference should be set by the application delegate early in the app lifecycle)
keyWindow.tintColor = mainColor;
// Navigation bar and tool bar customization. We're limiting appearance customization to instances that are
// inside PSPDFNavigationController, so we don't affect the appearance of certain system controllers.
let navBar = UINavigationBar.appearance(whenContainedInInstancesOf: [PSPDFNavigationController.self]);
let toolBar = UIToolbar.appearance(whenContainedInInstancesOf: [PSPDFNavigationController.self]);
navBar.barTintColor = mainColor
navBar.tintColor = secondaryColor
// Make sure we're getting a light title and status bar
navBar.barStyle = .black
toolBar.barTintColor = mainColor
toolBar.tintColor = secondaryColor
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
UIColor *mainColor = [UIColor colorWithWhite:0.2f alpha:1.f];
UIColor *secondaryColor = [UIColor whiteColor];
// Global (the window reference should be set by the application delegate early in the app lifecycle)
self.keyWindow.tintColor = mainColor;
// Navigation bar and tool bar customization. We're limiting appearance customization to instances that are
// inside PSPDFNavigationController, so we don't affect the appearance of certain system controllers.
UINavigationBar *navBar = [UINavigationBar appearanceWhenContainedIn:PSPDFNavigationController.class, nil];
UIToolbar *toolBar = [UIToolbar appearanceWhenContainedIn:PSPDFNavigationController.class, nil];
[navBar setBarTintColor:mainColor];
[navBar setTintColor:secondaryColor];
// Make sure we're getting a light title and status bar
[navBar setBarStyle:UIBarStyleBlack];
[toolBar setBarTintColor:mainColor];
[toolBar setTintColor:secondaryColor];

For a live example, please take a look at -[PSCatalogViewController applyCatalogAppearanceUsingCustomTinting:] in the PSPDFKit catalog.

Annotation toolbar

PSPDFAnnotationToolbar (and its superclass PSPDFFlexibleToolbar, will attempt to automatically set its appearance parameters to match those of the overlaid (main) UINavigationBar. In case those are not appropriate, or if further customization is required, you can use the appearance properties defined in PSPDFFlexibleToolbar to adjust the toolbar styling (using the UIAppearance protocol or setting the property values directly).

The following is an example of how to customize just the annotation toolbar appearance (changing it from the default inferred appearance).

Copy
1
2
3
let annotationToolbar = PSPDFAnnotationToolbar.appearance()
annotationToolbar.barTintColor = .white
annotationToolbar.tintColor = UIColor(white: 0.2, alpha: 1)
Copy
1
2
3
PSPDFAnnotationToolbar *annotationToolbar = [PSPDFAnnotationToolbar appearance];
[annotationToolbar setBarTintColor:[UIColor whiteColor]];
[annotationToolbar setTintColor:[UIColor colorWithWhite:0.2f alpha:1.f]];

We can also adjust the selected style by adding the following.

Copy
1
2
annotationToolbar.selectedBackgroundColor = UIColor(white: 0.8, alpha: 1)
annotationToolbar.selectedTintColor = UIColor(white: 0.2, alpha: 1)
Copy
1
2
[annotationToolbar setSelectedBackgroundColor:[UIColor colorWithWhite:0.8f alpha:1.f]];
[annotationToolbar setSelectedTintColor:[UIColor colorWithWhite:0.2f alpha:1.f]];

Further Reading Material

Was this page helpful? We're happy to answer any questions.