PSPDFKit 3.1 Migration Guide

This article provides a set of guidelines for migrating from version 3.0 to version 3.1 of PSPDFKit for Android. If you’re upgrading from a version earlier than 3.0, please review the Android 3 Migration Guide first.

Removed Theming-Based Configuration Classes

With 3.1, we unified the way developers can apply custom styles to PSPDFKit components. While it was previously possible to define styles using a set of configuration classes, we dropped this API with 3.1, replacing it with the recommended approach of using Android’s style and theming system.

Here is the list of dropped configuration classes with links to migration steps:

Annotation Editing Configuration

AnnotationEditingConfiguration and its builder were dropped, and all of its runtime properties were moved to PdfConfiguration. Below you’ll find the required steps for migrating your app if you previously used AnnotationEditingConfiguration.

You can add these as a custom style to your theme and choose pspdf__AnnotationSelection as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__annotationSelectionStyle">@style/AppTheme.AnnotationSelectionStyle</item>
</style>

<style name="AppTheme.AnnotationSelectionStyle" parent="pspdf__AnnotationSelection">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__borderColor">@color/pspdf__annotation_selection_border</item>
    <item name="pspdf__borderWidth">@dimen/pspdf__annotation_selection_border_width</item>
    <item name="pspdf__scaleHandleColor">@color/pspdf__annotation_selection_scalehandle</item>
    <item name="pspdf__editHandleColor">@color/pspdf__annotation_selection_edithandle</item>
    <item name="pspdf__padding">@dimen/pspdf__annotation_selection_padding</item>
    <item name="pspdf__guideLineWidth">@dimen/pspdf__annotation_selection_guide_line_width</item>
    <item name="pspdf__guideLineColor">@color/pspdf__annotation_selection_guide_line_color</item>
    <item name="pspdf__guideLineIncrease">@dimen/pspdf__annotation_selection_guide_line_increase</item>
</style>

Annotation Render Configuration

AnnotationRenderConfiguration and its builder were dropped. Below you’ll find the required steps for migrating your app if you previously used AnnotationRenderConfiguration.

  • The excludedAnnotationTypes() property was moved one level up to PdfConfiguration (and is also available via PdfActivityConfiguration).

  • Properties that tweak the annotation rendering were moved to the style system and can be set by applying a custom style to the pspdf__annotationStyle attribute of your theme. Here’s a list of 3.0 properties and the corresponding style attributes inside pspdf__annotationStyle:

    • setLinkAnnotationBackgroundColor()pspdf__linkAnnotationBackgroundColor

    • setLinkAnnotationBorderColor()pspdf__linkAnnotationBorderColor

    • setLinkAnnotationHighlightBackgroundColor()pspdf__linkAnnotationHighlightBackgroundColor

    • setLinkAnnotationHighlightBorderColor()pspdf__linkAnnotationHighlightBorderColor

You can add these as a custom style to your theme and choose pspdf__Annotation as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__annotationStyle">@style/AppTheme.AnnotationStyle</item>
</style>

<style name="AppTheme.AnnotationStyle" parent="pspdf__Annotation">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__linkAnnotationBackgroundColor">@color/pspdf__color_link_annotation_background</item>
    <item name="pspdf__linkAnnotationBorderColor">@color/pspdf__color_link_annotation_border</item>
    <item name="pspdf__linkAnnotationHighlightBackgroundColor">@color/pspdf__color_link_annotation_highlight_background</item>
    <item name="pspdf__linkAnnotationHighlightBorderColor">@color/pspdf__color_link_annotation_highlight_border</item>
</style>

Form Editing Configuration

FormEditingConfiguration and its builder were dropped. Below you’ll find the required steps for migrating your app if you previously used FormEditingConfiguration.

  • The enableFormEditing() and disableFormEditing() properties were moved one level up to PdfConfiguration (and are also available via PdfActivityConfiguration).

  • Properties that tweak the style of form editing were moved to the style system and can be set by applying a custom style to the pspdf__formSelectionStyle attribute of your theme. Here’s a list of 3.0 properties and the corresponding style attributes inside pspdf__formSelectionStyle:

    • highlightColor()pspdf__highlightColor

You can add these as a custom style to your theme and choose pspdf__FormSelection as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__formSelectionStyle">@style/AppTheme.FormSelectionStyle</item>
</style>

<style name="AppTheme.FormSelectionStyle" parent="pspdf__FormSelection">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__highlightColor">@color/pspdf__form_highlight_color</item>
</style>

Action Bar Icon Theming

ActionBarIconsThemeConfiguration and its builder were dropped. All of its style properties can be set by applying a custom style to the pspdf__actionBarIconsStyle attribute of the used theme. Below is a complete list of properties and configuration classes that were removed, along with their respective counterpart style attributes inside pspdf__actionBarIconsStyle:

  • setIconsColor()pspdf__iconsColor

  • setIconsColorActivated()pspdf__iconsColorActivated

  • setEditAnnotationsIcon()pspdf__editAnnotationsIcon

  • setEditAnnotationsIconActivated()pspdf__editAnnotationsIconActivated

  • setOutlineIcon()pspdf__outlineIcon

  • setOutlineIconActivated()pspdf__outlineIconActivated

  • setSearchIcon()pspdf__searchIcon

  • setSearchIconActivated()pspdf__searchIconActivated

  • setThumbnailGridIcon()pspdf__gridIcon

  • setThumbnailGridIconActivated()pspdf__gridIconActivated

  • setPrintIcon()pspdf__printIcon

  • setShareIcon()pspdf__shareIcon

You can add these as a custom style to your theme and choose pspdf__ActionBarIcons as a parent, which will provide all the defaults. You can then selectively tweak the default style:

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

<style name="AppTheme.ActionBarIconsStyle" parent="pspdf__ActionBarIcons">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <!-- Icons normal. -->
    <item name="pspdf__iconsColor">#ff0000</item>
    <item name="pspdf__outlineIcon">@drawable/pspdf__ic_outline</item>
    <item name="pspdf__searchIcon">@drawable/pspdf__ic_search</item>
    <item name="pspdf__gridIcon">@drawable/pspdf__ic_thumbnails</item>
    <item name="pspdf__editAnnotationsIcon">@drawable/pspdf__ic_edit_annotations</item>
    <!-- Icons activated. -->
    <item name="pspdf__iconsColorActivated">#ffff00</item>
    <item name="pspdf__outlineIconActivated">@drawable/pspdf__ic_outline</item>
    <item name="pspdf__searchIconActivated">@drawable/pspdf__ic_search</item>
    <item name="pspdf__gridIconActivated">@drawable/pspdf__ic_thumbnails_active</item>
    <item name="pspdf__editAnnotationsIconActivated">@drawable/pspdf__ic_edit_annotations</item>
    <!-- Stateless icons. -->
    <item name="pspdf__shareIcon">@drawable/pspdf__ic_share</item>
    <item name="pspdf__printIcon">@drawable/pspdf__ic_print</item>
</style>

Document Theme Configuration

DocumentThemeConfiguration and its builder were dropped. Below you’ll find the required steps for migrating your app if you previously used DocumentThemeConfiguration.

  • backgroundColor can now be set via PdfFragment#setBackgroundColor() or configured in your theme with the pspdf__backgroundColor attribute.

  • Properties that tweak the style of search results highlighting were moved to the style system and can be set by applying a custom style to the pspdf__searchResultHighlighterStyle attribute of your theme. Here’s a list of 3.0 properties and the corresponding style attributes inside pspdf__searchResultHighlighterStyle:

  • searchResultBackgroundColor()pspdf__searchResultBackgroundColor

  • searchResultBorderColor()pspdf__searchResultBorderColor

  • searchResultBorderWidth()pspdf__searchResultBorderWidth

  • searchResultPadding()pspdf__searchResultPadding.

  • searchResultAnnotationPadding()pspdf__searchResultAnnotationPadding

  • searchResultAnimationPadding()pspdf__searchResultAnimationPadding

  • searchResultCornerRadiusToHeightRatio()pspdf__searchResultCornerRadiusToHeightRatio

  • searchResultMinCornerRadius()pspdf__searchResultCornerRadiusMin

  • searchResultMaxCornerRadius()pspdf__searchResultCornerRadiusMax

You can add these as a custom style to your theme and choose pspdf__SearchResultHighlighter as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__backgroundColor">@color/pspdf__color_gray_light</item>
    <item name="pspdf__searchResultHighlighterStyle">@style/AppTheme.SearchResultHighlighterStyle</item>
</style>

<style name="AppTheme.SearchResultHighlighterStyle" parent="pspdf__SearchResultHighlighter">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__searchResultBackgroundColor">@color/pspdf__color_highlight</item>
    <item name="pspdf__searchResultBorderColor">@color/pspdf__border_color_highlight</item>
    <item name="pspdf__searchResultBorderWidth">@dimen/pspdf__search_result_border_width</item>
    <item name="pspdf__searchResultPadding">@dimen/pspdf__search_result_padding</item>
    <item name="pspdf__searchResultAnnotationPadding">@dimen/pspdf__search_result_annotation_padding</item>
    <item name="pspdf__searchResultAnimationPadding">@dimen/pspdf__search_result_animation_padding</item>
    <item name="pspdf__searchResultCornerRadiusToHeightRatio">@dimen/pspdf__search_result_corner_radius_to_height_ratio</item>
    <item name="pspdf__searchResultCornerRadiusMin">@dimen/pspdf__search_result_min_corner_radius</item>
    <item name="pspdf__searchResultCornerRadiusMax">@dimen/pspdf__search_result_max_corner_radius</item>
</style>

Thumbnail Bar Theme Configuration

ThumbnailBarThemeConfiguration and its builder were dropped. Properties that tweak the style of the thumbnail bar were moved to the style system.

Static Thumbnail Bar

For the default static thumbnail bar, apply a custom style to the pspdf__ThumbnailBarStyle attribute of your theme. Here’s a list of 3.0 properties and the corresponding style attributes inside pspdf__ThumbnailBarStyle:

  • setBackgroundColor()pspdf__backgroundColor

  • setThumbnailWidth()pspdf__thumbnailWidth

  • setThumbnailHeight()pspdf__thumbnailHeight

  • setThumbnailBorderColor()pspdf__thumbnailBorderColor

You can add these as a custom style to your theme and choose pspdf__ThumbnailBar as a parent, which will provide all the defaults. You can then selectively tweak the default style.

Scrollable Thumbnail Bar

For the scrollable thumbnail bar, use attributes from the pspdf__ScrollableThumbnailBar attribute set (specified by the theme attribute pspdf__scrollableThumbnailBarStyle). Here’s a list of 3.0 properties and the corresponding style attributes inside the pspdf__ScrollableThumbnailBarStyle:

  • setBackgroundColor()pspdf__backgroundColor

  • setThumbnailWidth()pspdf__thumbnailWidth

  • setThumbnailHeight()pspdf__thumbnailHeight

  • setThumbnailBorderColor()pspdf__thumbnailBorderColor

  • setThumbnailSelectedBorderColor()pspdf__thumbnailSelectedBorderColor

You can add these as a custom style to your theme and choose pspdf__ScrollableThumbnailBar as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__thumbnailBarStyle">@style/AppTheme.ThumbnailBarStyle</item>
    <item name="pspdf__scrollableThumbnailBarStyle">@style/AppTheme.ScrollableThumbnailBarStyle</item>
</style>

<style name="AppTheme.ThumbnailBarStyle" parent="pspdf__ThumbnailBar">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__backgroundColor">?colorPrimary</item>
    <item name="pspdf__thumbnailWidth">@dimen/pspdf__thumbnail_width</item>
    <item name="pspdf__thumbnailHeight">@dimen/pspdf__thumbnail_height</item>
    <item name="pspdf__thumbnailBorderColor">@color/pspdf__color_black</item>
</style>

<style name="AppTheme.ScrollableThumbnailBarStyle" parent="pspdf__ScrollableThumbnailBar">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__backgroundColor">@android:color/transparent</item>
    <item name="pspdf__thumbnailWidth">@dimen/pspdf__scrollable_thumbnail_width</item>
    <item name="pspdf__thumbnailHeight">@dimen/pspdf__scrollable_thumbnail_height</item>
    <item name="pspdf__thumbnailBorderColor">@color/pspdf__color_black</item>
    <item name="pspdf__thumbnailSelectedBorderColor">@color/pspdf__color</item>
</style>

Thumbnail Grid Theme Configuration

ThumbnailGridThemeConfiguration and its builder were dropped. All of its style properties can be set by applying a custom style to the pspdf__thumbnailGridStyle attribute of the used theme. Below is a complete list of properties and configuration classes that were removed, along with their respective counterpart style attributes inside the pspdf__thumbnailGridStyle:

  • setBackgroundColor()pspdf__backgroundColor

  • setItemLabelTextStyle()pspdf__itemLabelTextStyle

  • setItemLabelBackground()pspdf__itemLabelBackground

You can add these as a custom style to your theme and choose pspdf__ThumbnailGrid as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__thumbnailGridStyle">@style/AppTheme.ThumbnailGridStyle</item>
</style>

<style name="AppTheme.ThumbnailGridStyle" parent="pspdf__ThumbnailGrid">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__backgroundColor">@color/pspdf__color_gray_light</item>
    <item name="pspdf__itemLabelTextStyle">@style/pspdf__ThumbnailGridItemLabelDefStyle</item>
    <item name="pspdf__itemLabelBackground">@drawable/pspdf__grid_list_label_background</item>
</style>

Password View Theme Configuration

PasswordViewThemeConfiguration and its builder were dropped. All of its style properties can be set by applying a custom style to the pspdf__passwordViewStyle attribute of the used theme. Below is a complete list of properties and configuration classes that were removed, along with their respective counterpart style attributes inside the pspdf__passwordViewStyle:

  • setColor()pspdf__color

  • setHintColor()pspdf__hintColor

  • setFloatingHintColor()pspdf__floatingHintColor

  • setErrorColor()pspdf__errorColor

  • setIconResourceId()pspdf__icon

  • setIconTintingEnabled()pspdf__iconTintingEnabled

You can add these as a custom style to your theme and choose pspdf__PasswordView as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__passwordViewStyle">@style/AppTheme.PasswordViewStyle</item>
</style>

<style name="AppTheme.PasswordViewStyle" parent="pspdf__PasswordView">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__color">@color/pspdf__color_dark</item>
    <item name="pspdf__hintColor">@color/pspdf__color_gray</item>
    <item name="pspdf__floatingHintColor">@color/pspdf__color_dark</item>
    <item name="pspdf__errorColor">@color/pspdf__color_error</item>
    <item name="pspdf__icon">@drawable/pspdf__ic_lock</item>
    <item name="pspdf__iconTintingEnabled">true</item>
</style>

Inline Search Theme Configuration

InlineSearchThemeConfiguration and its builder were dropped. All of its style properties can be set by applying a custom style to the pspdf__inlineSearchStyle attribute of the used theme. Below is a complete list of properties and configuration classes that were removed, along with their respective counterpart style attributes inside the pspdf__inlineSearchStyle:

  • setBackgroundColor()pspdf__backgroundColor

  • setBorderColor()pspdf__borderColor

  • setBorderWidth()pspdf__borderWidth

  • setTextColor()pspdf__textColor

  • setHintTextColor()pspdf__hintTextColor

  • setNavigationTextColor()pspdf__navigationTextColor

  • setPrevIconDrawable()pspdf__prevIconDrawable

  • setNextIconDrawable()pspdf__nextIconDrawable

  • setPrevIconColorTint()pspdf__prevIconColorTint

  • setNextIconColorTint()pspdf__nextIconColorTint

  • setBackIconColorTint()pspdf__backIconColorTint

You can add these as a custom style to your theme and choose pspdf__SearchViewInline as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__inlineSearchStyle">@style/AppTheme.SearchViewInlineStyle</item>
</style>

<style name="AppTheme.SearchViewInlineStyle" parent="pspdf__SearchViewInline">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__backgroundColor">@android:color/transparent</item>
    <item name="pspdf__borderColor">@color/pspdf__color_white</item>
    <item name="pspdf__borderWidth">1dp</item>
    <item name="pspdf__textColor">@color/pspdf__color_white</item>
    <item name="pspdf__hintTextColor">@color/pspdf__color_white_hint</item>
    <item name="pspdf__navigationTextColor">@color/pspdf__color_white</item>
    <item name="pspdf__prevIconDrawable">@drawable/pspdf__ic_chevron_left_white</item>
    <item name="pspdf__nextIconDrawable">@drawable/pspdf__ic_chevron_right_white</item>
    <item name="pspdf__prevIconColorTint">@color/pspdf__color_white</item>
    <item name="pspdf__nextIconColorTint">@color/pspdf__color_white</item>
    <item name="pspdf__backIconColorTint">@color/pspdf__color_white</item>
</style>

Modular Search Theme Configuration

ModularSearchThemeConfiguration and its builder were dropped. All of its style properties can be set by applying a custom style to the pspdf__modularSearchStyle attribute of the used theme. Below is a complete list of properties and configuration classes that were removed, along with their respective counterpart style attributes inside the pspdf__modularSearchStyle:

  • setBackgroundColor()pspdf__backgroundColor

  • setInputFieldTextColor()pspdf__inputFieldTextColor

  • setInputFieldHintColor()pspdf__inputFieldHintColor

  • setInputFieldBackgroundColor()pspdf__inputFieldBackgroundColor

  • setSeparatorColor()pspdf__separatorColor

  • setListItemBackgroundColor()pspdf__listItemBackgroundColor

  • setListItemTitleColor()pspdf__listItemTitleColor

  • setListItemSubtitleColor()pspdf__listItemSubtitleColor

  • setListItemSelector()pspdf__listItemSelector

  • setHighlightBackgroundColor()pspdf__highlightBackgroundColor

  • setHighlightTextColor()pspdf__highlightTextColor

You can add these as a custom style to your theme and choose pspdf__SearchViewModular as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__modularSearchStyle">@style/AppTheme.SearchViewModularStyle</item>
</style>

<style name="AppTheme.SearchViewModularStyle" parent="pspdf__SearchViewModular">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__backgroundColor">@color/pspdf__color_white</item>
    <item name="pspdf__inputFieldTextColor">@color/pspdf__color_gray_dark</item>
    <item name="pspdf__inputFieldHintColor">@color/pspdf__color_gray</item>
    <item name="pspdf__inputFieldBackgroundColor">@android:color/transparent</item>
    <item name="pspdf__separatorColor">@color/pspdf__color_gray_light</item>
    <item name="pspdf__listItemBackgroundColor">@android:color/transparent</item>
    <item name="pspdf__listItemTitleColor">@color/pspdf__color_gray</item>
    <item name="pspdf__listItemSubtitleColor">@color/pspdf__color_gray_dark</item>
    <item name="pspdf__listItemSelector">@null</item>
    <item name="pspdf__highlightBackgroundColor">@color/pspdf__color_highlight</item>
    <item name="pspdf__highlightTextColor">@color/pspdf__color_black</item>
</style>

Outline Theme Configuration

OutlineThemeConfiguration and its builder were dropped. All of its style properties can be set by applying a custom style to the pspdf__outlineViewStyle attribute of the used theme. Below is a complete list of properties and configuration classes that were removed, along with their respective counterpart style attributes inside the pspdf__outlineViewStyle:

  • setBackgroundColor()pspdf__backgroundColor

  • setListItemSelector()pspdf__listItemSelector

  • setDefaultTextColor()pspdf__defaultTextColor

  • setTabIndicatorColor()pspdf__tabIndicatorColor

  • setBookmarksBarBackgroundColor()pspdf__bookmarksBarBackgroundColor

  • setBookmarksBarIconColor()pspdf__bookmarksBarIconColor

  • setBookmarksAddIcon()pspdf__bookmarksAddIcon

  • setBookmarksEditIcon()pspdf__bookmarksEditIcon

  • setBookmarksDoneIcon()pspdf__bookmarksDoneIcon

  • setBookmarksDeleteIcon()pspdf__bookmarksDeleteIcon

  • setBookmarksDeleteIconColor()pspdf__bookmarksDeleteIconColor

  • setBookmarksDeleteBackgroundColor()pspdf__bookmarksDeleteBackgroundColor

You can add these as a custom style to your theme and choose pspdf__OutlineView as a parent, which will provide all the defaults. You can then selectively tweak the default style:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    ...
    <item name="pspdf__outlineViewStyle">@style/AppTheme.OutlineViewStyle</item>
</style>

<style name="AppTheme.OutlineViewStyle" parent="pspdf__OutlineView">
    <!-- These are the defaults inherited from the parent style. Tweak them as you like! -->
    <item name="pspdf__backgroundColor">@color/pspdf__color_white</item>
    <item name="pspdf__listItemSelector">@null</item>
    <item name="pspdf__defaultTextColor">@color/pspdf__color_black</item>
    <item name="pspdf__tabIndicatorColor">?colorAccent</item>
    <item name="pspdf__bookmarksBarBackgroundColor">?colorPrimary</item>
    <item name="pspdf__bookmarksBarIconColor">@color/pspdf__color_white</item>
    <item name="pspdf__bookmarksAddIcon">@drawable/pspdf__ic_add</item>
    <item name="pspdf__bookmarksEditIcon">@drawable/pspdf__ic_edit</item>
    <item name="pspdf__bookmarksDoneIcon">@drawable/pspdf__ic_done</item>
    <item name="pspdf__bookmarksDeleteIcon">@drawable/pspdf__ic_delete</item>
    <item name="pspdf__bookmarksDeleteIconColor">@android:color/white</item>
    <item name="pspdf__bookmarksDeleteBackgroundColor">@color/pspdf__color_error</item>
</style>