PSPDFKit 5 Migration Guide
PSPDFKit 5 for Android is a major new release and includes many new features and a few breaking changes.
Opening Documents
The way to open documents has changed slightly. All the openDocument()
and openDocumentAsync()
methods that used to be in the PdfDocument
class moved to their own PdfDocumentLoader
class.
For example, this:
PdfDocument.openDocument(context, new DocumentSource(new AssetDataProvider("Guide-v4.pdf")));
becomes this:
PdfDocumentLoader.openDocument(context, new DocumentSource(new AssetDataProvider("Guide-v4.pdf")));
Bookmark Provider
BookmarkProvider
was converted to an interface and can no longer be instantiated. Instead, use PdfDocument#getBookmarkProvider()
to get an instance.
Furthermore, the prepareToSave()
method was removed since this is automatically handled by the framework and doesn’t need to be called manually. We also renamed the isDirty()
method to hasUnsavedChanges()
.
Form Provider
FormProvider
was converted to an interface and can no longer be instantiated. Instead, use PdfDocument#getFormProvider()
to get an instance.
Furthermore, we renamed the isDirty()
method to hasUnsavedChanges()
.
Document Metadata
DocumentPdfMetadata
and DocumentXmpMetadata
were converted to interfaces and can no longer be instantiated. Instead, use PdfDocument#getPdfMetadata()
and PdfDocument#getXmpMetadata()
to retrieve an instance.
Furthermore, the clearDirty()
method was removed since this is automatically handled by the framework and doesn’t need to be called manually. We also renamed the isDirty()
method to hasUnsavedChanges()
since that more accurately describes its function.
EventBus
With PSPDFKit 5, we got rid of EventBus
and all events and commands defined in Events
and Commands
:
-
Events.OnZoomScaleFactorChanged
was removed. UseDocumentListener#onDocumentZoomed()
instead. -
Events.OnPageChanged
was removed. UseDocumentListener#onPageChanged()
instead. -
Commands.ClearSelectedAnnotations
was removed. UsePdfFragment#clearSelectedAnnotations()
instead. -
Commands.SelectAnnotation
was removed. UsePdfFragment#setSelectedAnnotation()
instead. -
Commands.ExecuteAction
was removed. UsePdfFragment#executeAction()
instead. -
Commands.ShowPage
was removed. UsePdfFragment#setPageIndex()
instead. -
Commands.ToggleSystemBars
was removed. UsePdfActivity#setUserInterfaceVisible()
instead. -
Commands.SearchSelectedText
was removed. Use anOnSearchSelectedTextListener
set usingTextSelectionController#setOnSearchSelectedTextListener
instead. -
Commands.ShowAnnotationEditor
was removed. UseAnnotationCreationController#showAnnotationEditor()
orAnnotationEditingController#showAnnotationEditor()
instead. -
Commands.ToggleActionBarIconsVisibility
was removed. There is no replacement for this.
Changes to Resources
Starting with PSPDFKit 5, we hide resources (strings, IDs, drawables, dimensions, layouts) that are only for internal use. You will receive lint warnings if you try to use private resources, and you should stop using them as soon as possible since they might be removed without warning.
Changes to Theme Attributes
Some theme attributes were removed. These include the following:
-
pspdf__mainToolbarTextColor
,pspdf__mainToolbarTheme
, andpspdf__mainToolbarPopupTheme
. Usepspdf__textColor
,pspdf__toolbarTheme
, andpspdf__toolbarPopupTheme
in thepspdf__mainToolbarStyle
instead. -
pspdf__contextualToolbarBackground
andpspdf__contextualToolbarSubmenuBackground
. Usepspdf__backgroundColor
andpspdf__submenuBackgroundColor
in thepspdf__ContextualToolbarStyle
instead.
Refer to the Toolbar Styling guide for more information and examples of how to style toolbars using these new attributes.
Changes to Default Style Names
All built-in default styles were renamed to a consistent naming scheme. This means that:
-
All styles with the name scheme
pspdf__StyleName
defined instyles.xml
were renamed toPSPDFKit.StyleName
. -
All styles with the name scheme
PSPDFKit.Theme.Dark.StyleName
defined indark_theme.xml
were renamed toPSPDFKit.StyleName.Dark
. Some of these styles also had the suffixStyle
in their name, and these suffixes were dropped too.
For example, style pspdf__ThumbnailBar
was renamed to PSPDFKit.ThumbnailBar
, and PSPDFKit.Theme.Dark.ThumbnailBarStyle
was renamed to PSPDFKit.ThumbnailBar.Dark
.
Changes to Nullability Annotations
All methods with parameters annotated with @NonNull
now throw an IllegalArgumentException
when they receive null
as an argument.
Dropped Deprecated Fields and Methods
Here’s a list of other fields and methods we dropped:
-
PSPDFKit#updateInternalUIContext()
. -
DocumentDataStore
. -
com.pspdfkit.annotations.xfdf.XfdfFormatter
. Usecom.pspdfkit.document.formatters.XfdfFormatter
instead. -
InstantPdfFragment.newInstance(String, String, String, PdfConfiguration)
. UsenewInstance(String, String, PdfConfiguration)
instead. -
InstantPdfActivityIntentBuilder.fromInstantDocument(Context, String, String, String)
. UsefromInstantDocument(Context, String, String)
instead. -
InstantPdfActivity.showInstantDocument(Context, String, String, String, PdfActivityConfiguration)
. UseshowInstantDocument(Context, String, String, PdfActivityConfiguration)
instead. -
InstantDocumentDescriptor#getAuthenticationToken()
. UsegetJwt()
instead. -
InstantClient#openDocument(String, String)
. UseopenDocument(String)
instead. -
InstantClient#openDocumentAsync(String, String)
. UseopenDocumentAsync(String)
instead. -
InstantClient#getInstantDocumentDescriptor(String)
. UsegetInstantDocumentDescriptorForJwt(String)
instead. -
InstantPdfDocument#updateAuthenticationToken(String)
. UsereauthenticateWithJwt(String)
instead. -
InstantPdfDocument#updateAuthenticationTokenAsync(String)
. UsereauthenticateWithJwtAsync(String)
instead. -
InstantPdfDocument#setAutomaticSyncEnabled(boolean)
. UsesetListenToServerChanges(boolean)
andsetDelayForSyncingLocalChanges(long)
instead. -
AnnotationSyncCoordinator#setAutomaticSyncEnabled(boolean)
. UsesetListenToServerChanges(boolean)
andsetDelayForSyncingLocalChanges(long)
instead. -
AnnotationManager.OnAnnotationUpdatedListener
. UseAnnotationProvider.OnAnnotationUpdatedListener
instead. -
SignatureSignerDialog.show(FragmentManager, PdfDocument, SignatureFormField, Signer, DocumentSigningListener)
. Useshow(FragmentManager, Options, DocumentSigningListener)
instead. -
SignatureSignerDialog.show(FragmentManager, PdfDocument, SignatureFormField, Signer, BiometricSignatureData, DocumentSigningListener)
. Useshow(FragmentManager, Options, DocumentSigningListener)
instead. -
ComboBoxFormConfiguration.Builder#setSelectedIndexes(List)
. UsesetSelectedIndex(Integer)
instead. -
DocumentSharingProcessor
. UseDocumentSharingProviderProcessor#prepareDocumentForSharing(Context, PdfDocument, PdfProcessorTask, String)
instead. -
DocumentSharingProvider#deleteTemporaryFile(Context, Uri)
. UsedeleteFile(Context, Uri)
instead. -
PdfProcessorTask(PdfDocument)
. UsePdfProcessorTask.fromDocument(PdfDocument)
instead. -
PdfProcessorTask(NewPage)
. UsePdfProcessorTask.newPage(NewPage)
instead. -
Signer#signFormFieldAsync(SignatureFormField, KeyStore.PrivateKeyEntry, OutputStream)
. UsesignFormFieldAsync(SignatureFormField, BiometricSignatureData, OutputStream)
instead. -
Signer#signFormFieldAsync(SignatureFormField, KeyStore.PrivateKeyEntry, BiometricSignatureData, OutputStream)
. UsesignFormFieldAsync(SignatureFormField, BiometricSignatureData, OutputStream)
instead. -
Signer#signFormField(SignatureFormField, KeyStore.PrivateKeyEntry, OutputStream)
. UsesignFormField(SignatureFormField, BiometricSignatureData, OutputStream, OnSigningCompleteCallback)
instead. -
Signer#signFormField(SignatureFormField, KeyStore.PrivateKeyEntry, BiometricSignatureData, OutputStream)
. UsesignFormField(SignatureFormField, BiometricSignatureData, OutputStream, OnSigningCompleteCallback)
instead. -
MemorySigner#signFormFieldAsync(SignatureFormField, OutputStream)
. UsesignFormFieldAsync(SignatureFormField, BiometricSignatureData, OutputStream)
instead. -
MemorySigner#signFormField(SignatureFormField, OutputStream)
. UsesignFormField(SignatureFormField, BiometricSignatureData, OutputStream, OnSigningCompleteCallback)
instead. -
MemorySigner#getSigningKeyPair()
. -
PdfFragment.PARAM_DOCUMENT_PATHS
,PdfFragment.PARAM_IMAGE_DOCUMENT_PATH
,PdfFragment.PARAM_PASSWORDS
, andPdfFragment.PARAM_CONTENT_SIGNATURES
. -
PdfFragment#setCustomPdfSource(DataProvider, String)
. UsesetCustomPdfSource(DocumentSource)
instead. -
PdfFragment#setCustomPdfSources(List, List)
. UsesetCustomPdfSources(List)
instead. -
PdfFragment#[register/unregister]DrawableProvider()
. UsePdfFragment#[add/remove]DrawableProvider()
instead. -
PdfThumbnailGrid#[add/remove]OnDocumentEditingModeChangeListener()
. UseDocumentEditingManager#[add/remove]OnDocumentEditingModeChangeListener()
instead. -
PdfThumbnailGrid#[add/remove]OnDocumentEditingPageSelectionChangeListener()
. UseDocumentEditingManager#[add/remove]OnDocumentEditingPageSelectionChangeListener()
instead. -
AnnotationProvider#prepareForSave()
. This call is no longer necessary. -
AnnotationProvider#clearDirty()
. This call is no longer necessary. -
AnnotationProvider#isDirty()
. UsehasUnsavedChanges()
instead. -
PdfConfiguration#annotationReplyFeatureEnabled(boolean)
. UseannotationReplyFeatures(AnnotationReplyFeatures)
instead. -
PdfConfiguration#isAnnotationReplyFeatureEnabled()
. UsegetAnnotationReplyFeatures()
instead. -
PdfActivityConfiguration#annotationReplyFeatureEnabled(boolean)
. UseannotationReplyFeatures(AnnotationReplyFeatures)
instead. -
RichMediaExecuteAction#getScreenAnnotationPageIndex()
. -
RichMediaExecuteAction#getScreenAnnotationObjectNumber()
. UsegetRichMediaAnnotationObjectNumber()
instead. -
RenditionAction#getScreenAnnotationPageIndex()
.