Customizing PDF viewer styling on Android

To customize UI elements, Nutrient uses the standard Android style and theme system. When declaring a theme for your application, you can define the primary colors using the attributes colorPrimary, colorAccent, and colorPrimaryDark. All UI components of Nutrient (toolbars, views, dialogs, etc.) will use these colors to style the rest of the UI.

Out of the box, Nutrient comes with two predefined themes — PSPDFKit.Theme.Default and PSPDFKit.Theme.Dark — for the PdfActivity and all of its views. This guide describes how to tweak the default appearance to match the look of your app.

Defining a custom theme

Since Nutrient adheres to Android’s style and theme framework, you have full control over styling the appearance of all Nutrient components. The PdfActivity is built on top of the Android Compatibility Library v7, which means your theme has to inherit from Theme.AppCompat.

Furthermore, since PdfActivity uses a custom toolbar system, the decor action bar of the activity has to be deactivated. The easiest way to do this is to use the default Nutrient themes (PSPDFKit.Theme.Default and PSPDFKit.Theme.Dark) or Theme.AppCompat.NoActionBar as a parent theme.

1. Inside your app’s styles.xml, create a custom theme with Theme.AppCompat.NoActionBar as the parent. Or, to tweak the default style, a custom theme can inherit directly from PSPDFKit.Theme.Default or PSPDFKit.Theme.Dark as a parent:

   <style name="MyApp.PSPDFKitTheme" parent="PSPDFKit.Theme.Default">
       <item name="colorPrimary">@color/mymain_color</item>
       <item name="colorPrimaryDark">@color/mymain_color_dark</item>
       <item name="colorAccent">@color/mymain_color_accent</item>
   
       <!-- PSPDFKit comes with several styleable components. -->
       <item name="pspdf__inlineSearchStyle">@style/MyInlineSearch</item>
   </style>
   
   <style name="MyInlineSearch">
       <item name="pspdf__textColor">@color/my_inline_search_color</item>
   </style>

If you want to use a different parent theme, you can manually disable the default window decor action bar by setting windowActionBar to false and windowNoTitle to `true`.

2. Next, set your theme to the PdfActivity using the android:theme property inside your AndroidManifest.xml:

   <application>
       <activity android:name="com.pspdfkit.ui.PdfActivity"
                 android:theme="@style/MyApp.PSPDFKitTheme"/>
   </application>

A custom theme can be set either using the manifest or via PdfActivityConfiguration#Builder. In default mode, it can be set via PdfActivityConfiguration.Builder#theme(int), while in night theme mode, it can be set via PdfActivityConfiguration.Builder#themeDark(int). When a custom theme is set using the builder configuration, it overwrites the custom theme set in the manifest.

Nutrient resolves the used style values in the following order, using the first style found:

1. Styles provided by the custom theme (i.e. your MyApp.PSPDFKitTheme in the above example) set in the manifest for com.pspdfkit.ui.PdfActivity.

2. Default styles/internal Nutrient styles.

This means that Nutrient will use default values for all styles not covered under the current theme’s customization.

Available styles

Nutrient provides a large set of style attributes for both default and dark themes. This allows you to alter the appearance according to your needs. For a comprehensive usage example, have a look at DarkThemeExample and DarkThemeActivity inside the Catalog app.

Navigation history buttons styling

If you want to tweak the default appearance of the chevron icon color inside the navigation history buttons, you can use the pspdf__navigationHistoryIconColor attribute:

<style name="MyApp.Theme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="pspdf__navigationHistoryIconColor">@color/dark_icons_blue</item>
</style>

Toolbar styling

You can easily tweak the main toolbar style using the pspdf__mainToolbarStyle attribute of your theme:

<style name="MyApp.Theme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="pspdf__mainToolbarStyle">@style/MyApp.MainToolbarStyle</item>
</style>

<style name="MyApp.MainToolbarStyle">
    <item name="pspdf__backgroundColor">?colorPrimary</item>
    <item name="pspdf__textColor">@color/dark_icons_blue</item>

    <item name="pspdf__toolbarTheme">@style/ThemeOverlay.AppCompat.Dark.ActionBar</item>
    <item name="pspdf__toolbarPopupTheme">@style/ThemeOverlay.AppCompat.Light</item>
</style>

The following attributes can be modified for pspdf__mainToolbarStyle.

If you want to fully tweak the default appearance of the main toolbar, use the pspdf__toolbarTheme attribute to override the default theme used by the toolbar. Additionally, you can apply different themes used by toolbar popups with the pspdf__toolbarPopupTheme attribute of your theme.

If you want to tweak the default appearance of the icons inside the PdfActivity’s action bar, you can apply an icon style using the pspdf__actionBarIconsStyle attribute of your theme:

<style name="MyApp.Theme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="pspdf__actionBarIconsStyle">@style/MyApp.ActionBarIconsStyle</item>
</style>

<style name="MyApp.ActionBarIconsStyle">
    <item name="pspdf__iconsColor">@color/dark_icons_blue</item>
    <item name="pspdf__iconsColorActivated">@color/color_dark</item>
</style>

The following attributes can be modified for pspdf__actionBarIconsStyle.

Styling contextual toolbars

PSPDFKit uses custom contextual toolbars to present annotation editing, annotation creation, text selection, and document editing toolbars. To style contextual toolbars, use the pspdf__contextualToolbarStyle attribute of your theme:

<style name="MyApp.Theme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="pspdf__contextualToolbarStyle">@style/MyApp.ContextualToolbarStyle</item>
</style>

<style name="MyApp.ContextualToolbarStyle">
    <item name="pspdf__backgroundColor">?colorPrimaryDark</item>
    <item name="pspdf__submenuBackgroundColor">?colorPrimary</item>
    <item name="pspdf__iconsColor">@color/pspdf__color_white</item>
    <item name="pspdf__iconsColorActivated">@color/pspdf__color_white</item>
</style>

The following attributes can be modified for pspdf__contextualToolbarStyle. Note that some of them only have an effect when the toolbar is not docked at the top of the screen, but rather dragged to float vertically on the left or right side of the page.

Additionally, you can customize each of the toolbars with their own configuration, as shown below.

Annotation creation toolbar

<item name="pspdf__annotationCreationToolbarIconsStyle">@style/MyApp.Theme.AnnotationCreationToolbarIconsStyle</item>

Annotation editing toolbar

<item name="pspdf__annotationEditingToolbarIconsStyle">@style/MyApp.Theme.AnnotationEditingToolbarIconsStyle</item>

Text selection toolbar

<item name="pspdf__textSelectionToolbarIconsStyle">@style/MyApp.Theme.TextSelectionToolbarIconsStyle</item>

Document editing toolbar

<item name="pspdf__documentEditingToolbarIconsStyle">@style/MyApp.Theme.DocumentEditingToolbarIconsStyle</item>

Toolbar coordinator layout

The positioning and moving of contextual toolbars is handled by the ToolbarCoordinatorLayout, which can also be themed:

<item name="pspdf__toolbarCoordinatorLayoutStyle">@style/MyApp.Theme.ToolbarCoordinatorLayoutStyle</item>

Inline search

<item name="pspdf__inlineSearchStyle">@style/MyApp.InlineSearchStyle</item>

Modular search

<item name="pspdf__modularSearchStyle">@style/MyApp.ModularSearchStyle</item>

Note that pspdf__highlightBackgroundColor is used exclusively for highlighter styling inside the modular search view results list. If you want to change the search result highlighting color when displaying search results in the document view, refer to the highlighter customization section of the text search guide.

Thumbnail bar

<item name="pspdf__thumbnailBarStyle">@style/MyApp.ThumbnailBarStyle</item>

Scrollable thumbnail bar

<item name="pspdf__scrollableThumbnailBarStyle">@style/MyApp.ScrollableThumbnailBarStyle</item>

Thumbnail grid

<item name="pspdf__thumbnailGridStyle">@style/MyApp.ThumbnailGridStyle</item>

Outline view

<item name="pspdf__outlineViewStyle">@style/MyApp.OutlineStyle</item>

Document

<item name="pspdf__documentViewStyle">@style/MyApp.DocumentViewStyle</item>

Annotations

Use this to style the appearance of PDF annotations:

<item name="pspdf__annotationStyle">@style/MyApp.AnnotationStyle</item>

Annotation hints

Use this to style the appearance of PDF annotation hints:

<item name="pspdf__annotationNoteHinterStyle">@style/MyApp.AnnotationHintsStyle</item>

Search result highlighter

This defines styling for the search result highlighter:

<item name="pspdf__searchResultHighlighterStyle">@style/MyApp.SearchResultHighlighterStyle</item>

Link annotation Highlighter

This defines styling for the link annotations highlighter:

<item name="pspdf__linkAnnotationHighlighterStyle">@style/MyApp.LinkAnnotationHighlighterStyle</item>

Text selection

<item name="pspdf__textSelectionStyle">@style/MyApp.TextSelectionStyle</item>

Password view

<item name="pspdf__passwordViewStyle">@style/MyApp.PasswordViewStyle</item>

Signature layout

<item name="pspdf__passwordViewStyle">@style/MyApp.SignatureLayoutStyle</item>

Property inspector

<item name="pspdf__propertyInspectorStyle">@style/MyApp.PropertyInspectorStyle</item>

The modal dialog style is set inside the previously mentioned pspdf__propertyInspectorStyle via:

<item name="pspdf__modalDialogStyle">@style/MyApp.ModalDialog.PropertyInspector</item>

Action menu

This is used for styling the bottom action menu (pops up when sharing a document, for example):

<item name="pspdf__actionMenuStyle">@style/MyApp.ActionMenuStyle</item>

Stamp picker

<item name="pspdf__stampPickerStyle">@style/MyApp.StampPickerStyle</item>

Sharing dialog

<item name="pspdf__sharingDialogStyle">@style/MyApp.SharingDialogStyle</item>

New page dialog

<item name="pspdf__newPageDialogStyle">@style/MyApp.NewPageDialogStyle</item>

Settings mode picker Items

This is used for styling settings mode picker items:

<item name="pspdf__settingsModePickerItemStyle">@style/MyApp.SettingsModePickerItemStyle</item>

Settings mode line separator

This is used for styling the line separator between settings mode picker items:

<item name="pspdf__settingsModeLineSeparatorStyle">@style/MyApp.SettingsModeLineSeparatorStyle</item>

Attributes: Style it with all the regular Android attributes for styling views. To get a horizontal line, use android:layoutWidth="match_parent" and android:layoutHeight="1dp".

Document view

This accepts a style defining View attributes for modifying the appearance of scrollbars:

<item name="pspdf__documentViewStyle">@style/MyApp.DocumentViewStyle</item>

Form selection

<item name="pspdf__formSelectionStyle">@style/MyApp.FormSelectionStyle</item>

Form Editing bar

<item name="pspdf__formEditingBarStyle">@style/MyApp.FormEditingBarStyle</item>

Popup Toolbar

This is used for styling popup toolbars (e.g. when text is selected or when pasting elements):

<item name="pspdf__popupToolbarStyle">@style/MyApp.PopupToolbarStyle</item>

Tab bar

This is used for styling the tab bar that allows you to switch between different documents:

<item name="pspdf__tabBarStyle">@style/MyApp.TabBarStyle</item>

Annotation selection layout

Use this to style the appearance of the annotation selection layout:

<item name="pspdf__annotationSelectionStyle">@style/MyApp.AnnotationSelection</item>

When a scale handle drawable is set to null and the pspdf__scaleHandleColor is set to Color.TRANSPARENT, the scale handle will not be operational. When a drawable is set for a scale handle together with a color other than transparent, the drawable will take precedence over the color. When a background drawable is set by pspdf__backgroundDrawable together with pspdf__borderColor, the drawable will take precedence over the color.

When setting custom drawables for scale handles, some configurations may produce unwanted results when resizing the annotation selection layout. Make sure to test your custom drawable configuration thoroughly.

Measurement tools

Use the following to style the appearance of the Measurement Tools attributes:

<item name="pspdf__measurementToolsStyle">@style/MyApp.MeasurementTools</item>