public interface

PdfDocument

com.pspdfkit.document.PdfDocument
Known Indirect Subclasses

Class Overview

A PDF document. To create an instance use openDocument(Context, Uri) or related static methods on the PdfDocumentLoader class.

Summary

Nested Classes
@interface PdfDocument.PageRotation Indicates that the returned value is a page rotation. 
Constants
int NO_ROTATION Rotation value returned for pages that aren't rotated.
int ROTATION_180 Rotation value returned for pages that are rotated 180°.
int ROTATION_270 Rotation value returned for pages that are rotated 270°.
int ROTATION_90 Rotation value returned for pages that are rotated 90°.
Public Methods
abstract AnnotationProvider getAnnotationProvider()
Returns AnnotationProvider object which handles annotations contained in this document.
abstract BookmarkProvider getBookmarkProvider()
Returns BookmarkProvider object which handles bookmarks contained in this document.
abstract int getCharIndexAt(int pageIndex, float x, float y)
Return the index of the closest character whose rect intersects the given x and y coordinates.
abstract PdfDocumentCheckpointer getCheckpointer()
Returns PdfDocumentCheckpointer object which handles the checkpoint for the document.
abstract DocumentSaveOptions getDefaultDocumentSaveOptions()
Returns a default set of document save options which have same permissions, password and PDF version set as this document.
abstract DocumentSignatureInfo getDocumentSignatureInfo()
Returns information about digital signatures in this document.
abstract DocumentSource getDocumentSource()
Returns source of this document.
abstract List<DocumentSource> getDocumentSources()
Returns list of DocumentSources from which this document is loaded.
abstract EmbeddedFilesProvider getEmbeddedFilesProvider()
Returns EmbeddedFilesProvider object which handles embedded files contained in this document.
abstract FormProvider getFormProvider()
Returns FormProvider object which handles forms contained in this document.
abstract JavaScriptProvider getJavaScriptProvider()
Returns JavaScriptProvider object which handles JavaScript execution for this document.
abstract List<OutlineElement> getOutline()
Returns list of top-level (outline / table-of-contents) bookmarks.
abstract Single<List<OutlineElement>> getOutlineAsync()
Returns list of top-level (outline / table-of-contents) bookmarks, asynchronously.
abstract RectF getPageBox(int pageIndex, PdfBox box)
Returns rectangle describing one of the PDF page boxes.
abstract int getPageCount()
Returns number of pages in this document.
abstract Integer getPageIndexForPageLabel(String pageLabel, boolean partialMatching)
Gets the page index for the given page label.
abstract String getPageLabel(int pageIndex, boolean substituteWithPlainLabel)
Gets the page label.
abstract int getPageRotation(int pageIndex)
Returns a page rotation in degrees.
abstract Size getPageSize(int pageIndex)
Returns a page size in PDF points.
abstract String getPageText(int pageIndex, int start, int length)
Returns text content between two character indexes.
abstract String getPageText(int pageIndex)
Returns text content of the document page.
abstract String getPageText(int pageIndex, RectF rectF)
Returns text content inside given page rectangle.
abstract int getPageTextLength(int pageIndex)
Gets number of characters in text on the page.
abstract List<RectF> getPageTextRects(int pageIndex, int startIndex, int length)
Returns the rects of the range of characters on a page.
abstract List<RectF> getPageTextRects(int pageIndex, int startIndex, int length, boolean markupPadding)
Returns the rects of the range of characters on a page.
abstract DocumentPdfMetadata getPdfMetadata()
Returns metadata (title, author, creation date, ...) of this document, stored in the PDF document dictionary.
abstract PdfVersion getPdfVersion()
Returns current PDF version of the document.
abstract EnumSet<DocumentPermissions> getPermissions()
Returns set of currently applied permission flags on this document.
abstract int getRotationOffset(int pageIndex)
Returns the rotation offset applied to this page in degrees.
abstract String getTitle()
Returns a document title.
abstract String getUid()
This is the unique identifier for this document.
abstract DocumentXmpMetadata getXmpMetadata()
Returns document metadata stored in the XMP metadata entries included in the PDF file.
abstract boolean hasOutline()
Checks whether this document has outline / table of contents
abstract boolean hasPermission(DocumentPermissions permission)
Test document permission flags.
abstract void initPageCache()
Pre-fetches rotations, sizes and labels for all pages on a background thread.
abstract Completable initPageCacheAsync()
Pre-fetches rotations, sizes and labels for all pages on a background thread.
abstract void invalidateCache()
Invalidates render cache for images of the given document.
abstract void invalidateCacheForPage(int pageIndex)
Invalidates render cache for images of the given pageIndex of the document.
abstract boolean isAutomaticLinkGenerationEnabled()
abstract boolean isValidForEditing()
Returns true if the document is editable (is not compounded and comes from a supported source), false otherwise.
abstract boolean isWatermarkFilteringEnabled()
abstract Bitmap renderPageToBitmap(Context context, int pageIndex, int width, int height)
Renders page to a bitmap.
abstract Bitmap renderPageToBitmap(Context context, int pageIndex, int width, int height, PageRenderConfiguration configuration)
Renders page to a bitmap.
abstract Single<Bitmap> renderPageToBitmapAsync(Context context, int pageIndex, int width, int height, PageRenderConfiguration configuration)
Renders page to a bitmap.
abstract Single<Bitmap> renderPageToBitmapAsync(Context context, int pageIndex, int width, int height)
Renders page to a bitmap.
abstract void save(String path, DocumentSaveOptions saveOptions)
Saves the document even if it hasn't been changed.
abstract void save(String path)
Saves the document even if it hasn't been changed.
abstract Completable saveAsync(String path)
Saves the document even if it hasn't been changed.
abstract Completable saveAsync(String path, DocumentSaveOptions saveOptions)
Saves the document even if it hasn't been changed.
abstract boolean saveIfModified(DocumentSaveOptions saveOptions)
Saves the document to original location if it has been changed.
abstract boolean saveIfModified()
Saves the document to original location if it has been changed.
abstract boolean saveIfModified(String path)
Saves the document to passed location if it has been changed.
abstract boolean saveIfModified(String path, DocumentSaveOptions saveOptions)
Saves the document to passed location if it has been changed.
abstract Single<Boolean> saveIfModifiedAsync()
Saves the document back to original location if it has been changed.
abstract Single<Boolean> saveIfModifiedAsync(DocumentSaveOptions saveOptions)
Saves the document back to original location if it has been changed.
abstract Single<Boolean> saveIfModifiedAsync(String path, DocumentSaveOptions saveOptions)
Saves the document to passed location if it has been changed.
abstract Single<Boolean> saveIfModifiedAsync(String path)
Saves the document to passed location if it has been changed.
abstract void setAutomaticLinkGenerationEnabled(boolean enabled)
Enables or disables automatic link generation.
abstract void setRotationOffset(int pageRotation, int pageIndex)
Applies a temporary rotation to the specified page of this document.
abstract void setRotationOffsets(SparseIntArray pageRotations)
Applies a temporary rotation to the specified pages of this document.
abstract void setWatermarkTextFilteringEnabled(boolean enabled)
Enables or disables filtering of watermark text in text retrieval methods.
abstract boolean wasModified()
Returns true if this document was modified and should be saved to retain changes.

Constants

public static final int NO_ROTATION

Rotation value returned for pages that aren't rotated.

Constant Value: 0 (0x00000000)

public static final int ROTATION_180

Rotation value returned for pages that are rotated 180°.

Constant Value: 180 (0x000000b4)

public static final int ROTATION_270

Rotation value returned for pages that are rotated 270°.

Constant Value: 270 (0x0000010e)

public static final int ROTATION_90

Rotation value returned for pages that are rotated 90°.

Constant Value: 90 (0x0000005a)

Public Methods

public abstract AnnotationProvider getAnnotationProvider ()

Returns AnnotationProvider object which handles annotations contained in this document.

Returns
  • The annotation provider.

public abstract BookmarkProvider getBookmarkProvider ()

Returns BookmarkProvider object which handles bookmarks contained in this document.

Returns
  • The bookmark provider.

public abstract int getCharIndexAt (int pageIndex, float x, float y)

Return the index of the closest character whose rect intersects the given x and y coordinates.

Parameters
pageIndex Page number of the page, zero indexed.
x X coordinate in PDF point units (usually 1/72 of an inch).
y Y coordinate in PDF point units (usually 1/72 of an inch).
Returns
  • The index of the selected character (zero indexed) or -1 if no character was found at the given coordinates.

public abstract PdfDocumentCheckpointer getCheckpointer ()

Returns PdfDocumentCheckpointer object which handles the checkpoint for the document. May return null if checkpoint is not supported.

Returns

public abstract DocumentSaveOptions getDefaultDocumentSaveOptions ()

Returns a default set of document save options which have same permissions, password and PDF version set as this document.

Returns
  • Default set of document options that share properties with this document.

public abstract DocumentSignatureInfo getDocumentSignatureInfo ()

Returns information about digital signatures in this document.

Returns

public abstract DocumentSource getDocumentSource ()

Returns source of this document.

Returns

public abstract List<DocumentSource> getDocumentSources ()

Returns list of DocumentSources from which this document is loaded. A source can be either a file URI or a DataProvider. Only compound documents will have multiple sources.

Returns
  • a list of DocumentSources for this PdfDocument. If the document is a compound one (i.e. is read from multiple sources) it will have several sources, otherwise it the list will contain a single entry.

public abstract EmbeddedFilesProvider getEmbeddedFilesProvider ()

Returns EmbeddedFilesProvider object which handles embedded files contained in this document.

Returns
  • The embedded files provider.

public abstract FormProvider getFormProvider ()

Returns FormProvider object which handles forms contained in this document.

Returns
  • The form provider.

public abstract JavaScriptProvider getJavaScriptProvider ()

Returns JavaScriptProvider object which handles JavaScript execution for this document.

Returns
  • The JavaScript provider.

public abstract List<OutlineElement> getOutline ()

Returns list of top-level (outline / table-of-contents) bookmarks. Bookmarks are organized in a tree-like structure and can have children. Note that this may take a while and should not be called on the main thread. If you want a quick check for whether document has outline, use hasOutline().

Note: When this document is a compound document, calling this method will only ever return the outline of the first document source.

Returns
  • List of top-level bookmarks. If no outline elements exist, the returned list will be empty.

public abstract Single<List<OutlineElement>> getOutlineAsync ()

Returns list of top-level (outline / table-of-contents) bookmarks, asynchronously. Bookmarks are organized in a tree-like structure and can have children.

Note: When this document is a compound document, calling this method will only ever return the outline of the first document source.

Returns
  • Single emitting the list of top-level bookmarks or an empty list if no outline elements exist.

public abstract RectF getPageBox (int pageIndex, PdfBox box)

Returns rectangle describing one of the PDF page boxes. If the page box dimension is not present in the PDF document, it's considered to be as large as the actual page size from getPageSize(int).

Parameters
pageIndex Page number of the page to render, zero indexed.
box Box to retrieve for the page, from PdfBox.
Returns
  • Rectangle describing the page box in PDF coordinates.

public abstract int getPageCount ()

Returns number of pages in this document.

Returns
  • Number of pages in the PDF document.

public abstract Integer getPageIndexForPageLabel (String pageLabel, boolean partialMatching)

Gets the page index for the given page label.

Parameters
pageLabel The page label to search for.
partialMatching If false, the exact string will be searched for. Otherwise we will return the best match.
Returns
  • The index of the page with the page label or null.

public abstract String getPageLabel (int pageIndex, boolean substituteWithPlainLabel)

Gets the page label.

Parameters
pageIndex The index of the page.
substituteWithPlainLabel If true, and no page label exists for the given page, returns a string with the page number.
Returns
  • The page label of the page requests or null if not found.

public abstract int getPageRotation (int pageIndex)

Returns a page rotation in degrees.

Parameters
pageIndex Page index of the requested page, zero indexed.
Returns
  • Rotation of the page in degrees (clockwise).

public abstract Size getPageSize (int pageIndex)

Returns a page size in PDF points.

Parameters
pageIndex Page number of the page to render, zero indexed.
Returns
  • Size page size object.

public abstract String getPageText (int pageIndex, int start, int length)

Returns text content between two character indexes. Use getPageTextLength(int) to determine the number of characters on page.

Parameters
pageIndex 0-indexed page number.
start Index of first character in the range.
length Length of the range.
Returns
  • Text on the page between passed ranges.

public abstract String getPageText (int pageIndex)

Returns text content of the document page.

Parameters
pageIndex 0-indexed page number.
Returns
  • Text on the page.

public abstract String getPageText (int pageIndex, RectF rectF)

Returns text content inside given page rectangle.

Parameters
pageIndex 0-indexed page number.
rectF Page rectangle in the PDF coordinates.
Returns
  • Text on the page inside given page rect.

public abstract int getPageTextLength (int pageIndex)

Gets number of characters in text on the page.

Parameters
pageIndex 0-indexed page number.
Returns
  • Number of characters in page text.

public abstract List<RectF> getPageTextRects (int pageIndex, int startIndex, int length)

Returns the rects of the range of characters on a page.

Parameters
pageIndex Page number of the page, zero indexed.
startIndex Index of the starting character.
length Number of characters in sequence.
Returns
  • List of rects of the characters on page in PDF point (1/72 of an inch) units. May be an empty list if the character is not represented visually.

public abstract List<RectF> getPageTextRects (int pageIndex, int startIndex, int length, boolean markupPadding)

Returns the rects of the range of characters on a page.

Parameters
pageIndex Page number of the page, zero indexed.
startIndex Index of the starting character.
length Number of characters in sequence.
markupPadding Take the font height into account in the rects to make better suited for being displayed around the text.
Returns
  • List of rects of the characters on page in PDF point (1/72 of an inch) units. May be an empty list if the character is not represented visually.

public abstract DocumentPdfMetadata getPdfMetadata ()

Returns metadata (title, author, creation date, ...) of this document, stored in the PDF document dictionary.

Returns
  • PDF document metadata.

public abstract PdfVersion getPdfVersion ()

Returns current PDF version of the document.

Returns

public abstract EnumSet<DocumentPermissions> getPermissions ()

Returns set of currently applied permission flags on this document.

Returns
  • PDF document permission flags.

public abstract int getRotationOffset (int pageIndex)

Returns the rotation offset applied to this page in degrees.

Parameters
pageIndex Page index of the requested page, zero indexed.
Returns
  • Rotation offset of the page in degrees (clockwise).

public abstract String getTitle ()

Returns a document title. Resolved in this order:

  1. Document title from metadata
  2. Document title

Returns
  • Document title or null if no title is available.

public abstract String getUid ()

This is the unique identifier for this document. It will be created automatically based on the content sources.

Returns
  • Unique document identifier.

public abstract DocumentXmpMetadata getXmpMetadata ()

Returns document metadata stored in the XMP metadata entries included in the PDF file.

Returns
  • PDF document metadata stored in the XMP metadata entries.

public abstract boolean hasOutline ()

Checks whether this document has outline / table of contents

Returns
  • true when the document has outline, false if not.

public abstract boolean hasPermission (DocumentPermissions permission)

Test document permission flags.

Returns
  • true if permission flag is set on this document, false otherwise.

public abstract void initPageCache ()

Pre-fetches rotations, sizes and labels for all pages on a background thread. Caching will only be performed once (for the first caller). If you need a callback to be notified of when caching is done, use the async variant initPageCacheAsync() instead.

public abstract Completable initPageCacheAsync ()

Pre-fetches rotations, sizes and labels for all pages on a background thread. Caching will only be performed once (for the first subscriber).

Returns
  • A completable that will perform caching on a background thread once subscribed (only for the first subscriber). All subsequent subscribers will only receive the completion event as soon as the cache is built.

public abstract void invalidateCache ()

Invalidates render cache for images of the given document. Use this method if the document was changed externally and you need the rendered pages to be refreshed.

Note: this call may block for a while and should not be invoked on the main thread.

public abstract void invalidateCacheForPage (int pageIndex)

Invalidates render cache for images of the given pageIndex of the document. Use this method if a single page of the document became and needs to be re-rendered.

Note: this call may block for a while and should not be invoked on the main thread.

Parameters
pageIndex 0-based index of the page to refresh.

public abstract boolean isAutomaticLinkGenerationEnabled ()

Returns
  • true if automatic link generation is enabled.

public abstract boolean isValidForEditing ()

Returns true if the document is editable (is not compounded and comes from a supported source), false otherwise.

Returns
  • true if the document supports editing, false otherwise.

public abstract boolean isWatermarkFilteringEnabled ()

Returns
  • true if watermark filtering is enabled.

public abstract Bitmap renderPageToBitmap (Context context, int pageIndex, int width, int height)

Renders page to a bitmap.

Parameters
context Application context.
pageIndex Page number of the page to render, zero indexed.
width Bitmap width.
height Bitmap height.
Returns
  • Bitmap with rendered page.

public abstract Bitmap renderPageToBitmap (Context context, int pageIndex, int width, int height, PageRenderConfiguration configuration)

Renders page to a bitmap.

Parameters
context Application context.
pageIndex Page number of the page to render, zero indexed.
width Bitmap width.
height Bitmap height.
configuration Advanced configuration options.
Returns
  • Bitmap with rendered page.

public abstract Single<Bitmap> renderPageToBitmapAsync (Context context, int pageIndex, int width, int height, PageRenderConfiguration configuration)

Renders page to a bitmap.

Parameters
context Application context.
pageIndex Page number of the page to render, zero indexed.
width Bitmap width.
height Bitmap height.
configuration Advanced configuration options.
Returns
  • Single which returns rendered page when the process is done.

public abstract Single<Bitmap> renderPageToBitmapAsync (Context context, int pageIndex, int width, int height)

Renders page to a bitmap.

Parameters
context Application context.
pageIndex Page number of the page to render, zero indexed.
width Bitmap width.
height Bitmap height.
Returns
  • Single which returns rendered page when the process is done.

public abstract void save (String path, DocumentSaveOptions saveOptions)

Saves the document even if it hasn't been changed. Note that this may take a while and should not be called on the main thread.

Parameters
path Absolute filepath to the output document file.
saveOptions Save options for the document, may be null to use default set.
Throws
IOException

public abstract void save (String path)

Saves the document even if it hasn't been changed. Note that this may take a while and should not be called on the main thread.

Parameters
path Absolute filepath to the output document file.
Throws
IOException

public abstract Completable saveAsync (String path)

Saves the document even if it hasn't been changed.

Parameters
path Absolute filepath to the output document file.
Returns
  • Completable for the save process.

public abstract Completable saveAsync (String path, DocumentSaveOptions saveOptions)

Saves the document even if it hasn't been changed.

Parameters
path Absolute filepath to the output document file.
saveOptions Save options for the document.
Returns
  • Completable for the save process.

public abstract boolean saveIfModified (DocumentSaveOptions saveOptions)

Saves the document to original location if it has been changed. If there were no changes to the document, the document file will not be modified. Note that this may take a while and should not be called on the main thread.

Parameters
saveOptions Save options for the document.
Returns
  • true if the file was modified and changes were saved, false if there was nothing to save.
Throws
IOException

public abstract boolean saveIfModified ()

Saves the document to original location if it has been changed. If there were no changes to the document, the document file will not be modified. Note that this may take a while and should not be called on the main thread.

Returns
  • true if the file was modified and changes were saved. false if there was nothing to save.
Throws
IOException

public abstract boolean saveIfModified (String path)

Saves the document to passed location if it has been changed. If there were no changes to the document, the document file will not be modified. Note that this may take a while and should not be called on the main thread.

Parameters
path Absolute filepath to which to save the document.
Returns
  • true if the file was modified and changes were saved, false if there was nothing to save.
Throws
IOException

public abstract boolean saveIfModified (String path, DocumentSaveOptions saveOptions)

Saves the document to passed location if it has been changed. If there were no changes to the document, the document file will not be modified. Note that this may take a while and should not be called on the main thread.

Parameters
path Absolute filepath to which to save the document.
saveOptions Save options for the document.
Returns
  • true if the file was modified and changes were saved, false if there was nothing to save.
Throws
IOException

public abstract Single<Boolean> saveIfModifiedAsync ()

Saves the document back to original location if it has been changed. If there were no changes to the document, the document file will not be modified.

Returns
  • Single observable returning true if file was saved or false if there was no changes to be saved.

public abstract Single<Boolean> saveIfModifiedAsync (DocumentSaveOptions saveOptions)

Saves the document back to original location if it has been changed. If there were no changes to the document, the document file will not be modified.

Parameters
saveOptions Save options for the document.
Returns
  • Single observable returning true if file was saved or false if there was no changes to be saved.

public abstract Single<Boolean> saveIfModifiedAsync (String path, DocumentSaveOptions saveOptions)

Saves the document to passed location if it has been changed. If there were no changes to the document, the document file will not be modified.

Parameters
path Absolute filepath to which to save the document.
saveOptions Save options for the document, may be null to use default set.
Returns
  • Single observable returning true if file was saved or false if there was no changes to be saved.

public abstract Single<Boolean> saveIfModifiedAsync (String path)

Saves the document to passed location if it has been changed. If there were no changes to the document, the document file will not be modified.

Parameters
path Absolute filepath to which to save the document.
Returns
  • Single observable returning true if file was saved or false if there was no changes to be saved.

public abstract void setAutomaticLinkGenerationEnabled (boolean enabled)

Enables or disables automatic link generation. This will parse the PDF page text and automatically generate clickable links (and corresponding LinkAnnotation objects) for text that looks like a HTTP or a similar link.

Enabled by default.

Parameters
enabled true if link generation should be enabled, false otherwise.

public abstract void setRotationOffset (int pageRotation, int pageIndex)

Applies a temporary rotation to the specified page of this document. This will change the size reported by the document to match the new rotation. The document will not be modified by this. If you plan on applying a rotation to multiple pages use setRotationOffsets(SparseIntArray).

Parameters
pageRotation One of NO_ROTATION, ROTATION_90, ROTATION_180, ROTATION_270.
pageIndex The page to apply the rotation to.

public abstract void setRotationOffsets (SparseIntArray pageRotations)

Applies a temporary rotation to the specified pages of this document. This will change the size reported by the document to match the new rotation. The document will not be modified by this. If you plan on applying a rotation to a single page use setRotationOffset(int, int).

Parameters
pageRotations A SparseIntArray mapping the page index to the desired rotation. (One of NO_ROTATION, ROTATION_90, ROTATION_180, ROTATION_270)

public abstract void setWatermarkTextFilteringEnabled (boolean enabled)

Enables or disables filtering of watermark text in text retrieval methods. Note that this will not prevent the rendering of the watermark on the page.

Affects getPageText(int) (and overloads), getPageTextLength(int) and getPageTextRects(int, int, int).

Enabled by default.

public abstract boolean wasModified ()

Returns true if this document was modified and should be saved to retain changes.

Returns
  • true if this document was modified and should be saved.