Nutrient 5 migration guide

Nutrient Android SDK 5 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 Nutrient 5, we got rid of EventBus and all events and commands defined in Events and Commands:

• Events.OnZoomScaleFactorChanged was removed. Use DocumentListener#onDocumentZoomed() instead.
• Events.OnPageChanged was removed. Use DocumentListener#onPageChanged() instead.
• Commands.ClearSelectedAnnotations was removed. Use PdfFragment#clearSelectedAnnotations() instead.
• Commands.SelectAnnotation was removed. Use PdfFragment#setSelectedAnnotation() instead.
• Commands.ExecuteAction was removed. Use PdfFragment#executeAction() instead.
• Commands.ShowPage was removed. Use PdfFragment#setPageIndex() instead.
• Commands.ToggleSystemBars was removed. Use PdfActivity#setUserInterfaceVisible() instead.
• Commands.SearchSelectedText was removed. Use an OnSearchSelectedTextListener set using TextSelectionController#setOnSearchSelectedTextListener instead.
• Commands.ShowAnnotationEditor was removed. Use AnnotationCreationController#showAnnotationEditor() or AnnotationEditingController#showAnnotationEditor() instead.
• Commands.ToggleActionBarIconsVisibility was removed. There is no replacement for this.

Changes to resources

Starting with Nutrient 5, we hide resources(opens in a new tab) (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, and pspdf__mainToolbarPopupTheme. Use pspdf__textColor, pspdf__toolbarTheme, and pspdf__toolbarPopupTheme in the pspdf__mainToolbarStyle instead.
• pspdf__contextualToolbarBackground and pspdf__contextualToolbarSubmenuBackground. Use pspdf__backgroundColor and pspdf__submenuBackgroundColor in the pspdf__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 in styles.xml were renamed to PSPDFKit.StyleName.
• All styles with the name scheme PSPDFKit.Theme.Dark.StyleName defined in dark_theme.xml were renamed to PSPDFKit.StyleName.Dark. Some of these styles also had the suffix Style 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. Use com.pspdfkit.document.formatters.XfdfFormatter instead.
• InstantPdfFragment.newInstance(String, String, String, PdfConfiguration). Use newInstance(String, String, PdfConfiguration) instead.
• InstantPdfActivityIntentBuilder.fromInstantDocument(Context, String, String, String). Use fromInstantDocument(Context, String, String) instead.
• InstantPdfActivity.showInstantDocument(Context, String, String, String, PdfActivityConfiguration). Use showInstantDocument(Context, String, String, PdfActivityConfiguration) instead.
• InstantDocumentDescriptor#getAuthenticationToken(). Use getJwt() instead.
• InstantClient#openDocument(String, String). Use openDocument(String) instead.
• InstantClient#openDocumentAsync(String, String). Use openDocumentAsync(String) instead.
• InstantClient#getInstantDocumentDescriptor(String). Use getInstantDocumentDescriptorForJwt(String) instead.
• InstantPdfDocument#updateAuthenticationToken(String). Use reauthenticateWithJwt(String) instead.
• InstantPdfDocument#updateAuthenticationTokenAsync(String). Use reauthenticateWithJwtAsync(String) instead.
• InstantPdfDocument#setAutomaticSyncEnabled(boolean). Use setListenToServerChanges(boolean) and setDelayForSyncingLocalChanges(long) instead.
• AnnotationSyncCoordinator#setAutomaticSyncEnabled(boolean). Use setListenToServerChanges(boolean) and setDelayForSyncingLocalChanges(long) instead.
• AnnotationManager.OnAnnotationUpdatedListener. Use AnnotationProvider.OnAnnotationUpdatedListener instead.
• SignatureSignerDialog.show(FragmentManager, PdfDocument, SignatureFormField, Signer, DocumentSigningListener). Use show(FragmentManager, Options, DocumentSigningListener) instead.
• SignatureSignerDialog.show(FragmentManager, PdfDocument, SignatureFormField, Signer, BiometricSignatureData, DocumentSigningListener). Use show(FragmentManager, Options, DocumentSigningListener) instead.
• ComboBoxFormConfiguration.Builder#setSelectedIndexes(List). Use setSelectedIndex(Integer) instead.
• DocumentSharingProcessor. Use DocumentSharingProviderProcessor#prepareDocumentForSharing(Context, PdfDocument, PdfProcessorTask, String) instead.
• DocumentSharingProvider#deleteTemporaryFile(Context, Uri). Use deleteFile(Context, Uri) instead.
• PdfProcessorTask(PdfDocument). Use PdfProcessorTask.fromDocument(PdfDocument) instead.
• PdfProcessorTask(NewPage). Use PdfProcessorTask.newPage(NewPage) instead.
• Signer#signFormFieldAsync(SignatureFormField, KeyStore.PrivateKeyEntry, OutputStream). Use signFormFieldAsync(SignatureFormField, BiometricSignatureData, OutputStream) instead.
• Signer#signFormFieldAsync(SignatureFormField, KeyStore.PrivateKeyEntry, BiometricSignatureData, OutputStream). Use signFormFieldAsync(SignatureFormField, BiometricSignatureData, OutputStream) instead.
• Signer#signFormField(SignatureFormField, KeyStore.PrivateKeyEntry, OutputStream). Use signFormField(SignatureFormField, BiometricSignatureData, OutputStream, OnSigningCompleteCallback) instead.
• Signer#signFormField(SignatureFormField, KeyStore.PrivateKeyEntry, BiometricSignatureData, OutputStream). Use signFormField(SignatureFormField, BiometricSignatureData, OutputStream, OnSigningCompleteCallback) instead.
• MemorySigner#signFormFieldAsync(SignatureFormField, OutputStream). Use signFormFieldAsync(SignatureFormField, BiometricSignatureData, OutputStream) instead.
• MemorySigner#signFormField(SignatureFormField, OutputStream). Use signFormField(SignatureFormField, BiometricSignatureData, OutputStream, OnSigningCompleteCallback) instead.
• MemorySigner#getSigningKeyPair().
• PdfFragment.PARAM_DOCUMENT_PATHS, PdfFragment.PARAM_IMAGE_DOCUMENT_PATH, PdfFragment.PARAM_PASSWORDS, and PdfFragment.PARAM_CONTENT_SIGNATURES.
• PdfFragment#setCustomPdfSource(DataProvider, String). Use setCustomPdfSource(DocumentSource) instead.
• PdfFragment#setCustomPdfSources(List, List). Use setCustomPdfSources(List) instead.
• PdfFragment#[register/unregister]DrawableProvider(). Use PdfFragment#[add/remove]DrawableProvider() instead.
• PdfThumbnailGrid#[add/remove]OnDocumentEditingModeChangeListener(). Use DocumentEditingManager#[add/remove]OnDocumentEditingModeChangeListener() instead.
• PdfThumbnailGrid#[add/remove]OnDocumentEditingPageSelectionChangeListener(). Use DocumentEditingManager#[add/remove]OnDocumentEditingPageSelectionChangeListener() instead.
• AnnotationProvider#prepareForSave(). This call is no longer necessary.
• AnnotationProvider#clearDirty(). This call is no longer necessary.
• AnnotationProvider#isDirty(). Use hasUnsavedChanges() instead.
• PdfConfiguration#annotationReplyFeatureEnabled(boolean). Use annotationReplyFeatures(AnnotationReplyFeatures) instead.
• PdfConfiguration#isAnnotationReplyFeatureEnabled(). Use getAnnotationReplyFeatures() instead.
• PdfActivityConfiguration#annotationReplyFeatureEnabled(boolean). Use annotationReplyFeatures(AnnotationReplyFeatures) instead.
• RichMediaExecuteAction#getScreenAnnotationPageIndex().
• RichMediaExecuteAction#getScreenAnnotationObjectNumber(). Use getRichMediaAnnotationObjectNumber() instead.
• RenditionAction#getScreenAnnotationPageIndex().