PSPDFKit 4 Migration Guide for Android | Easy Transition Instructions
PSPDFKit 4 for Android is a major new release and includes many new features and a few breaking changes.
Removed Optionals
We’ve removed our com.pspdfkit.utilities.Optional
class that was used when returning objects that may or may not have a value. It has been replaced with the RxJava 2 Maybe
class, which is a reactive type that either returns a value in onSuccess()
, simply completes in onComplete()
, or throws an error in onError()
. This is much more convenient to use.
For example, this:
@NonNull public Optional<Annotation> getAnnotation(int pageIndex, int objectNumber) @NonNull public Observable<Optional<Annotation>> getAnnotationAsync(int pageIndex, int objectNumber)
becomes this:
@Nullable public Annotation getAnnotation(int pageIndex, int objectNumber) @NonNull public Maybe<Annotation> getAnnotationAsync(int pageIndex, int objectNumber)
Here is the full list of modified methods:
-
AnnotationProvider#getAnnotationAsync(int, int)
fromObservable<Optional<Annotation>>
toMaybe<Annotation>
. -
AnnotationProvider#getAnnotation(int, int)
fromOptional<Annotation>
to@Nullable Annotation
. -
FormProvider#getFormElementForAnnotationAsync()
fromObservable<Optional<FormElement>>
toMaybe<FormElement>
. -
FormProvider#getFormElementForAnnotation()
fromOptional<FormElement>
to@Nullable FormElement
. -
FormProvider#getFormFieldWithFullyQualifiedNameAsync()
fromObservable<Optional<FormElement>>
toMaybe<FormElement>
. -
FormProvider#getFormFieldWithFullyQualifiedName()
fromOptional<FormElement>
to@Nullable FormElement
. -
FormProvider#getFormElementWithNameAsync()
fromObservable<Optional<FormElement>>
toMaybe<FormElement>
. -
FormProvider#getFormElementWithName()
fromOptional<FormElement>
to@Nullable FormElement
. -
WidgetAnnotation#getFormElementAsync()
fromObservable<Optional<FormElement>>
toMaybe<FormElement>
. -
WidgetAnnotation#getFormElement()
fromOptional<FormElement>
to@Nullable FormElement
.
New Android SDK Version
We’ve updated our SDK to fully support Android 8.0 Oreo. In order to ensure that everything works as expected, it is required that you update the compileSdkVersion
in the build.gradle
of your application to 26
. We also increased the minimum required version to Android 4.4 KitKat (API Level 19), so you also need to update your minSdkVersion
to 19
.
If you are using Kotlin in your application, this change will require that you update all your findViewById
calls.
For example, this:
val textView = findViewById(R.id.textview) as TextView
becomes this:
val textView: TextView = findViewById(R.id.textview)
If you are still using Java, Android Studio will remind you to remove the cast.
For example, this:
TextView textView = (TextView) findViewById(R.id.textview);
becomes this:
TextView textView = findViewById(R.id.textview);
Updated Dependencies
We’ve updated RxJava to 2.1.3
. If you’re using the recommended Maven repository approach to add PSPDFKit to your project, you don’t have to do anything; the dependency will be updated automatically.
If you’re not using our Maven repository, make sure to update dependencies to the new version:
implementation 'io.reactivex.rxjava2:rxjava:2.1.3'
ProGuard Rules
There is no longer a need to specify additional ProGuard rules since PSPDFKit uses consumersProguardFiles
to keep ProGuard from obfuscating the required symbols. For more information, please check our ProGuard section in the guides.
Unified Naming for Listeners
We’ve cleaned up all inconsistent names of callbacks and their management methods in order to unify our APIs and be consistent with Android framework styles.
Here is the full list of changes:
-
Renamed
DownloadDocumentTask.DownloadedFileCallback
toDownloadDocumentTask.OnFileDownloadedListener
. -
Renamed
ExtractAssetTask.OnDocumentExtractedCallback
toExtractAssetTask.OnDocumentExtractedListener
. -
Renamed
InstantPdfDocument#registerInstantDocumentListener
toInstantPdfDocument#addInstantDocumentListener
. -
Renamed
InstantPdfDocument#unregisterInstantDocumentListener
toInstantPdfDocument#removeInstantDocumentListener
. -
Renamed
InstantPdfFragment#registerInstantDocumentListener
toInstantPdfFragment#addInstantDocumentListener
. -
Renamed
InstantPdfFragment#unregisterInstantDocumentListener
toInstantPdfFragment#removeInstantDocumentListener
. -
Renamed
OnAnnotationProviderUpdatedListener#onAnnotationDeleted
toOnAnnotationProviderUpdatedListener#onAnnotationRemoved
. -
Renamed
AnnotationProvider.OnAnnotationProviderUpdatedListener
toAnnotationProvider.OnAnnotationUpdatedListener
. -
Renamed
AnnotationProvider#registerOnAnnotationProviderUpdatedListener
toAnnotationProvider#addOnAnnotationUpdatedListener
. -
Renamed
AnnotationProvider#unregisterOnAnnotationProviderUpdatedListener
toAnnotationProvider#removeOnAnnotationUpdatedListener
. -
Renamed
ActionResolver#registerDocumentActionListener
toActionResolver#addDocumentActionListener
. -
Renamed
ActionResolver#unregisterDocumentActionListener
toActionResolver#removeDocumentActionListener
. -
Renamed
NewPageFactory.OnNewPageReadyCallback
toNewPageFactory.OnNewPageReadyListener
. -
Renamed
PdfLibrary#registerLibraryIndexingListener
toPdfLibrary#addLibraryIndexingListener
. -
Renamed
PdfLibrary#unregisterLibraryIndexingListener
toPdfLibrary#removeLibraryIndexingListener
. -
Renamed
FormProvider#registerOnFormFieldUpdatedListener
toFormProvider#addOnFormFieldUpdatedListener
. -
Renamed
FormProvider#unregisterOnFormFieldUpdatedListener
toFormProvider#removeOnFormFieldUpdatedListener
. -
Renamed
FormProvider#registerOnFormTabOrderUpdatedListener
toFormProvider#addOnFormTabOrderUpdatedListener
. -
Renamed
FormProvider#unregisterOnFormTabOrderUpdatedListener
toFormProvider#removeOnFormTabOrderUpdatedListener
. -
Renamed
FormProvider#registerOnTextFormFieldUpdatedListener
toFormProvider#addOnTextFormFieldUpdatedListener
. -
Renamed
FormProvider#unregisterOnTextFormFieldUpdatedListener
toFormProvider#removeOnTextFormFieldUpdatedListener
. -
Renamed
FormProvider#registerOnButtonFormFieldUpdatedListener
toFormProvider#addOnButtonFormFieldUpdatedListener
. -
Renamed
FormProvider#unregisterOnButtonFormFieldUpdatedListener
toFormProvider#removeOnButtonFormFieldUpdatedListener
. -
Renamed
FormProvider#registerOnChoiceFormFieldUpdatedListener
toFormProvider#addOnChoiceFormFieldUpdatedListener
. -
Renamed
FormProvider#unregisterOnChoiceFormFieldUpdatedListener
toFormProvider#removeOnChoiceFormFieldUpdatedListener
. -
Renamed
DefaultDocumentEditorListener.UriValidationCallback
toDefaultDocumentEditorListener.UriValidationListener
. -
Renamed
PdfDocumentEditorListenerCallback
toOnFileWriteCompleteListener
. -
Renamed
PSPDFKitViews#setDocumentEditorListener
toPSPDFKitViews#setPdfDocumentEditorListener
. -
Renamed
PdfFragment#registerDocumentListener
toPdfFragment#addDocumentListener
. -
Renamed
PdfFragment#unregisterDocumentListener
toPdfFragment#removeDocumentListener
. -
Renamed
PdfFragment#registerDocumentScrollListener
toPdfFragment#addDocumentScrollListener
. -
Renamed
PdfFragment#unregisterDocumentScrollListener
toPdfFragment#removeDocumentScrollListener
. -
Renamed
PdfOutlineView.OnAnnotationTappedListener
toPdfOutlineView.OnAnnotationTapListener
and itsonAnnotationTapped
method toonAnnotationTap
. -
Renamed
PdfOutlineView.OnOutlineElementTappedListener
toPdfOutlineView.OnOutlineElementTapListener
and itsonOutlineElementTapped
method toonOutlineElementTap
. -
Renamed
PdfOutlineView#setOnAnnotationTappedListener
toPdfOutlineView#setOnAnnotationTapListener
. -
Renamed
PdfOutlineView#setOnOutlineElementTappedListener
toPdfOutlineView#setOnOutlineElementTapListener
. -
Renamed
PdfThumbnailGrid#setDocumentEditorListener
toPdfThumbnailGrid#setPdfDocumentEditorListener
. -
Renamed
PdfThumbnailGrid#registerDocumentEditingModeChangeListener
toPdfThumbnailGrid#addOnDocumentEditingModeChangeListener
. -
Renamed
PdfThumbnailGrid#unregisterDocumentEditingModeChangeListener
toPdfThumbnailGrid#removeOnDocumentEditingModeChangeListener
. -
Renamed
PdfThumbnailGrid#registerDocumentEditingPageSelectionChangeListener
toPdfThumbnailGrid#addOnDocumentEditingPageSelectionChangeListener
. -
Renamed
PdfThumbnailGrid#unregisterDocumentEditingPageSelectionChangeListener
toPdfThumbnailGrid#removeOnDocumentEditingPageSelectionChangeListener
. -
Renamed
ActionMenu#registerActionMenuListener
toActionMenu#addActionMenuListener
. -
Renamed
ActionMenu#unregisterActionMenuListener
toActionMenu#removeActionMenuListener
. -
Renamed
FormEditingBar#registerFormEditingBarLifecycleListener
toFormEditingBar#addOnFormEditingBarLifecycleListener
. -
Renamed
FormEditingBar#unregisterFormEditingBarLifecycleListener
toFormEditingBar#removeOnFormEditingBarLifecycleListener
. -
Renamed
PropertyInspectorCoordinatorLayoutController#registerPropertyInspectorLifecycleListener
toPropertyInspectorCoordinatorLayoutController#addPropertyInspectorLifecycleListener
. -
Renamed
PropertyInspectorCoordinatorLayoutController#unregisterPropertyInspectorLifecycleListener
toPropertyInspectorCoordinatorLayoutController#removePropertyInspectorLifecycleListener
. -
Renamed
BookmarkViewAdapter#registerBookmarkChangeListener
toBookmarkViewAdapter#addBookmarkListener
. -
Renamed
BookmarkViewAdapter#unregisterBookmarkChangeLister
toBookmarkViewAdapter#removeBookmarkListener
. -
Renamed
OnModeChangedListener#OnPageTransitionChanged
toOnModeChangedListener#OnScrollModeChange
. -
Renamed
OnModeChangedListener#OnScrollDirectionChanged
toOnModeChangedListener#OnScrollDirectionChange
. -
Renamed
OnModeChangedListener#OnPageLayoutChanged
toOnModeChangedListener#OnPageLayoutChange
. -
Renamed
OnModeChangedListener#OnThemeChanged
toOnModeChangedListener#OnThemeChange
. -
Renamed
OnModeChangedListener#OnScreenTimeoutChanged
toOnModeChangedListener#OnScreenTimeoutChange
. -
Renamed
AnnotationManager#registerAnnotationSelectedListener
toAnnotationManager#addOnAnnotationSelectedListener
. -
Renamed
AnnotationManager#unregisterAnnotationSelectedListener
toAnnotationManager#removeOnAnnotationSelectedListener
. -
Renamed
AnnotationManager#registerAnnotationDeselectedListener
toAnnotationManager#addOnAnnotationDeselectedListener
. -
Renamed
AnnotationManager#unregisterAnnotationDeselectedListener
toAnnotationManager#removeOnAnnotationDeselectedListener
. -
Renamed
AnnotationManager#registerAnnotationUpdatedListener
toAnnotationManager#addOnAnnotationUpdatedListener
. -
Renamed
AnnotationManager#unregisterAnnotationUpdatedListener
toAnnotationManager#removeOnAnnotationUpdatedListener
. -
Renamed
AnnotationManager#registerAnnotationCreationModeChangeListener
toAnnotationManager#addOnAnnotationCreationModeChangeListener
. -
Renamed
AnnotationManager#unregisterAnnotationCreationModeChangeListener
toAnnotationManager#removeOnAnnotationCreationModeChangeListener
. -
Renamed
AnnotationManager#registerAnnotationCreationModeSettingsChangeListener
toAnnotationManager#addOnAnnotationCreationModeSettingsChangeListener
. -
Renamed
AnnotationManager#unregisterAnnotationCreationModeSettingsChangeListener
toAnnotationManager#removeOnAnnotationCreationModeSettingsChangeListener
. -
Renamed
AnnotationManager#registerAnnotationEditingModeChangeListener
toAnnotationManager#addOnAnnotationEditingModeChangeListener
. -
Renamed
AnnotationManager#unregisterAnnotationEditingModeChangeListener
toAnnotationManager#removeOnAnnotationEditingModeChangeListener
. -
Renamed
DocumentEditingManager#registerDocumentEditingModeChangeListener
toDocumentEditingManager#addOnDocumentEditingModeChangeListener
. -
Renamed
DocumentEditingManager#unregisterDocumentEditingModeChangeListener
toDocumentEditingManager#removeOnDocumentEditingModeChangeListener
. -
Renamed
DocumentEditingManager#registerDocumentEditingPageSelectionChangeListener
toDocumentEditingManager#addOnDocumentEditingPageSelectionChangeListener
. -
Renamed
DocumentEditingManager#unregisterDocumentEditingPageSelectionChangeListener
toDocumentEditingManager#removeOnDocumentEditingPageSelectionChangeListener
. -
Renamed
FormManager#registerFormElementSelectedListener
toFormManager#addOnFormElementSelectedListener
. -
Renamed
FormManager#unregisterFormElementSelectedListener
toFormManager#removeOnFormElementSelectedListener
. -
Renamed
FormManager#registerFormElementDeselectedListener
toFormManager#addOnFormElementDeselectedListener
. -
Renamed
FormManager#unregisterFormElementDeselectedListener
toFormManager#removeOnFormElementDeselectedListener
. -
Renamed
FormManager#registerFormElementUpdatedListener
toFormManager#addOnFormElementUpdatedListener
. -
Renamed
FormManager#unregisterFormElementUpdatedListener
toFormManager#removeOnFormElementUpdatedListener
. -
Renamed
FormManager#registerFormElementEditingModeChangeListener
toFormManager#addOnFormElementEditingModeChangeListener
. -
Renamed
FormManager#unregisterFormElementEditingModeChangeListener
toFormManager#removeOnFormElementEditingModeChangeListener
. -
Renamed
FormManager#registerFormElementClickedListener
toFormManager#addOnFormElementClickedListener
. -
Renamed
FormManager#unregisterFormElementClickedListener
toFormManager#removeOnFormElementClickedListener
. -
Renamed
TextSelectionManager#registerTextSelectionModeChangeListener
toTextSelectionManager#addOnTextSelectionModeChangeListener
. -
Renamed
TextSelectionManager#unregisterTextSelectionModeChangeListener
toTextSelectionManager#removeOnTextSelectionModeChangeListener
. -
Renamed
TextSelectionManager#registerTextSelectionChangeListener
toTextSelectionManager#addOnTextSelectionChangeListener
. -
Renamed
TextSelectionManager#unregisterTextSelectionChangeListener
toTextSelectionManager#removeOnTextSelectionChangeListener
. -
Changed
ContextualToolbar#setToolbarCoordinatorController
to accept@Nullable ToolbarCoordinatorLayoutController
so that you can clear it by passingnull
. -
Removed
ContextualToolbar#removeToolbarCoordinatorController
; useContextualToolbar#setToolbarCoordinatorController(null)
instead. -
Changed
ContextualToolbar#setOnMenuItemClickListener
to accept@Nullable OnMenuItemClickListener
so that you can clear it by passingnull
. -
Removed
ContextualToolbar#removeOnMenuItemClickListener
; useContextualToolbar#setOnMenuItemClickListener(null)
instead. -
Changed
ContextualToolbar#setOnMenuItemLongClickListener
to accept@Nullable OnMenuItemLongClickListener
so that you can clear it by passingnull
. -
Removed
ContextualToolbar#removeOnMenuItemClickListener
; useContextualToolbar#setOnMenuItemLongClickListener(null)
instead. -
Deprecated
AnnotationManager.OnAnnotationUpdatedListener
, useAnnotationProvider.OnAnnotationUpdatedListener
instead.
Dropped Deprecated Fields and Methods
Here is the full list of what we’ve dropped:
-
Removed
PdfActivityConfiguration.Builder#diskCacheSize()
,PdfConfiguration.Builder#diskCacheSize()
— disk cache is not supported. -
Removed
PdfDocument#getUri()
andPdfDocument#getUriList()
. -
Removed
PdfYouTubeActivity#ARG_YOUTUBE_URL
; use#ARG_MEDIA_URI
for passingMediaUri
objects through intent. -
Removed
PdfMediaDialog#ARG_URI
; use#ARG_MEDIA_URI
for passingMediaUri
objects through intent. -
Removed
PrintOptions(PdfProcessorTask.AnnotationProcessingMode, ..)
constructors; usePrintOptions(boolean, ..)
instead. -
Removed
PdfFragment#enterAnnotationCreationMode(AnnotationType)
; useenterAnnotationCreationMode(AnnotationTool)
instead. -
Removed
PdfFragment#clearTextSelection()
; useexitCurrentlyActiveMode()
instead. -
Removed
PdfFragment#setTextSelection()
; useenterTextSelectionMode()
instead. -
Removed
DocumentSharingManager#generateDocumentName()
; usegetTitle()
instead.
Renamed HUD Terminology to User Interface
We’ve replaced the term HUD in our codebase with “user interface” and applied proper camel casing on symbol names:
-
Renamed
HudViewMode
enum toUserInterfaceViewMode
, and all its values begin withUSER_INTERFACE
now. -
Renamed
getHudViewMode()
togetUserInterfaceViewMode()
onPdfActivityConfiguration
,PdfActivity
, andPdfActivityApi
. Its new return type is nowUserInterfaceViewMode
. -
Renamed
setHudViewMode(HudViewMode)
tosetUserInterfaceViewMode(UserInterfaceViewMode)
onPdfActivityConfiguration
,PdfActivity
, andPdfActivityApi
. -
Renamed
HudViewMode
toUserInterfaceViewMode
onPdfActivityConfiguration.Builder
.
Supplementary Changes
This last section is for changes that don’t apply to a specific section:
-
Replaced
AnnotationType
withAnnotationTool
inAnnotationPreferencesManager
methods. -
Changed the thickness property type of
AnnotationCreationController
fromint
tofloat
.
You can see the full list of changes in the Android changelog.