diff --git a/.eslintignore b/.eslintignore new file mode 100644 index 000000000..c99b88c6e --- /dev/null +++ b/.eslintignore @@ -0,0 +1,8 @@ +# Build +lib + +# Auto-gen Docs +docs + +# Example folder +example \ No newline at end of file diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 000000000..ef6bd0e69 --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,26 @@ +{ + "env": { + "es2021": true + }, + "extends": [ + "standard" + ], + "parser": "@typescript-eslint/parser", + "parserOptions": { + "ecmaVersion": 12, + "sourceType": "module" + }, + "rules": { + "max-len":["error", { "code": 100, "ignoreUrls": true }], + "no-trailing-spaces": "off", + "quotes": "off", + "@typescript-eslint/no-unused-vars": "off", + "semi": "off", + "quote-props": ["error", "consistent"], + "prettier/prettier": "off", + "no-use-before-define": "off", + "padded-blocks": "off", + "react-native/no-inline-styles": "off", + "import/export": "off" + } +} diff --git a/.github/workflows/jsBuilder.yml b/.github/workflows/jsBuilder.yml index 0130e1ec9..2092cf604 100644 --- a/.github/workflows/jsBuilder.yml +++ b/.github/workflows/jsBuilder.yml @@ -15,15 +15,16 @@ jobs: fetch-depth: 0 # otherwise, you will failed to push refs to dest repo. ref: ${{ github.event.pull_request.head.sha }} # checks out the branch being merged into `master` - - name: Install dependencies - run: | - npm i - - name: Node setup uses: actions/setup-node@v2 with: - node-version: '16' + node-version: '14' cache: 'npm' + cache-dependency-path: 'package.json' + + - name: Install dependencies + run: | + npm i - name: Build JavaScript files run: | # Change line to your build script command. diff --git a/.gitignore b/.gitignore index 65869cc81..12045823a 100644 --- a/.gitignore +++ b/.gitignore @@ -50,4 +50,4 @@ example/android/app/src/main/assets/index.android.bundle example/android/app/src/main/assets/index.android.bundle.meta # Build -/lib \ No newline at end of file +/lib diff --git a/.npmignore b/.npmignore index ba0fcd823..f4299aaa6 100644 --- a/.npmignore +++ b/.npmignore @@ -46,4 +46,7 @@ buck-out/ *.keystore example/android/app/src/main/assets/index.android.bundle -example/android/app/src/main/assets/index.android.bundle.meta \ No newline at end of file +example/android/app/src/main/assets/index.android.bundle.meta + +# Auto-gen Docs +docs diff --git a/API.md b/API.md deleted file mode 100644 index b44ae34c4..000000000 --- a/API.md +++ /dev/null @@ -1,3540 +0,0 @@ -# PDFTron React Native API - -## TypeScript - -PDFTron React Native supports TypeScript. Since not all customers use the language, the typings used in this document will be described using normal JavaScript types. For TypeScript users, type information is automatically provided while coding, and exact type aliases and constants used in our custom typings can be found in [AnnotOptions](src/AnnotOptions) and [Config](src/Config) source folders. - -## RNPdftron - -RNPdftron contains static methods for global library initialization, configuration, and utility methods. - -### initialize -Initializes PDFTron SDK with your PDFTron commercial license key. You can run PDFTron in demo mode by passing an empty string. - -Parameters: - -Name | Type | Description ---- | --- | --- -licenseKey | string | your PDFTron license key - -```js -RNPdftron.initialize('your_license_key'); -``` - -### enableJavaScript -Enables JavaScript for PDFTron SDK, by default it is enabled. - -Parameters: - -Name | Type | Description ---- | --- | --- -enabled | bool | whether to enable or disable JavaScript - -```js -RNPdftron.enableJavaScript(true); -``` - -### getVersion -Gets the current PDFNet version. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -version | string | current PDFNet version - -```js -RNPdftron.getVersion().then((version) => { - console.log("Current PDFNet version:", version); -}); -``` - -### getPlatformVersion -Gets the version of current platform (Android/iOS). - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -platformVersion | string | current platform version (Android/iOS) - -```js -RNPdftron.getPlatformVersion().then((platformVersion) => { - console.log("App currently running on:", platformVersion); -}); -``` - -### getSystemFontList -Gets the font list available on the OS (Android only). -This is typically useful when you are mostly working with non-ascii characters in the viewer. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -fontList | string | the font list available on Android - -```js -RNPdftron.getSystemFontList().then((fontList) => { - console.log("OS font list:", fontList); -}); -``` - -### clearRubberStampCache -Clear the information and bitmap cache for rubber stamps (Android only). -This is typically useful when the content of rubber stamps has been changed in the viewer. - -Returns a promise. - -```js -RNPdftron.clearRubberStampCache().then(() => { - console.log("Rubber stamp cache cleared"); -}); -``` - -### encryptDocument -Encrypts (password-protect) a document (must be a PDF). **Note**: This function does not lock the document it cannot be used it while the document is opened in the viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -file path | string | the local file path to the file -password | string | the password you would like to set -current password | string | the current password, use empty string if no password - -Returns a promise. - -Example: - -```js -RNPdftron.encryptDocument("/sdcard/Download/new.pdf", "1111", "").then(() => { - console.log("done password"); -}); -``` - -### pdfFromOffice -Generates a PDF from an Office document. - -Parameters: - -Name | Type | Description ---- | --- | --- -docxPath | string | the local file path to the Office file - -Optional Parameters: - -Name | Type | Description ---- | --- | --- -applyPageBreaksToSheet | boolean | Whether we should split Excel workheets into pages so that the output resembles print output. -displayChangeTracking | boolean | If this option is true, will display office change tracking markup present in the document (i.e, red strikethrough of deleted content and underlining of new content). -excelDefaultCellBorderWidth | double | Cell border width for table cells that would normally be drawn with no border. -excelMaxAllowedCellCount | int | Conversion will throw an exception if the number of cells in a Microsoft Excel document is above the set MaxAllowedCellCount. -locale | string | ISO 639-1 code of the current system locale. For example: 'en-US', 'ar-SA', 'de-DE', etc. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -resultPdfPath | string | the local file path to the generated PDF - -The user is responsible for cleaning up the temporary file that is generated. - -Example: - -```js -// With options -RNPdftron.pdfFromOffice("/sdcard/Download/red.xlsx", - { - applyPageBreaksToSheet: true, - displayChangeTracking: true, - excelDefaultCellBorderWidth: 1, - excelMaxAllowedCellCount: 250000, - locale: 'en-US' - }) -.then((resultPdfPath) => { - console.log(resultPdfPath); -}); - -// Without options -RNPdftron.pdfFromOffice("/sdcard/Download/red.xlsx", null).then((resultPdfPath) => { - console.log(resultPdfPath); -}); -``` - -### pdfFromOfficeTemplate -Generates a PDF using a template in the form of an Office document and replacement data in the form of a JSON object. -For more information please see our [template guide](https://www.pdftron.com/documentation/core/guides/generate-via-template/). - -Parameters: - -Name | Type | Description ---- | --- | --- -docxPath | string | the local file path to the template file -json | object | the replacement data in the form of a JSON object - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -resultPdfPath | string | the local file path to the generated PDF - -The user is responsible for cleaning up the temporary file that is generated. - -Example: - -```js -RNPdftron.pdfFromOfficeTemplate("/sdcard/Download/red.docx", json).then((resultPdfPath) => { - console.log(resultPdfPath); -}); -``` - -#### exportAsImage -Export a PDF page to an image format defined in [`Config.ExportFormat`](./src/Config/Config.ts). - -Unlike DocumentView.exportAsImage, this method is static and should only be called *before* a `DocumentView` instance has been created or else unexpected behaviour can occur. This method also takes a local file path to the desired PDF. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | int | the page to be converted; if the value does not refer to a valid page number, the file path will be undefined -dpi | double | the output image resolution -exportFormat | string | one of [`Config.ExportFormat`](./src/Config/Config.ts) constants -filePath | string | local file path to pdf - -Returns a Promise. - -Name | Type | Description ---- | --- | --- -resultImagePath | string | the temp path of the created image, user is responsible for clean up the cache - -```js -RNPdftron.exportAsImage(1, 92, Config.ExportFormat.BMP, "/sdcard/Download/red.pdf").then((resultImagePath) => { - console.log('export', resultImagePath); -}); -``` - -## DocumentView - Props - -A React component for displaying documents of different types such as PDF, docx, pptx, xlsx and various image formats. - -### Open a Document - -#### document -string, required - -The path or url to the document. - -Example: - -```js - -``` - -#### password -string, optional - -The password of the document, if any. - -Example: - -```js - -``` - -#### isBase64String -bool, optional, defaults to false - -If true, [`document`](#document) prop will be treated as a base64 string. If it is not the base64 string of a pdf file, [`base64FileExtension`](#base64FileExtension) is required. - -When viewing a document initialized with a base64 string (i.e. a memory buffer), a temporary file is created on Android and iOS. - -```js - -``` - -#### base64FileExtension -string, required if using base64 string of a non-pdf file, defaults to ".pdf" - -The file extension for the base64 string in [`document`](#document), if [`isBase64String`](#isBase64String) is true. - -```js - -``` - -#### documentExtension -string, optional, defaults to the extension in the [`document`](#document) prop. - -Used for specifying the extension of the document to be loaded. - -```js - -``` - -For iOS, please use the following podspec in your `Podfile`: https://nightly-pdftron.s3-us-west-2.amazonaws.com/stable/2021-12-01/9.1/cocoapods/xcframeworks/pdfnet/2021-12-01_stable_rev78714.podspec - - -#### customHeaders -object, optional - -Defines custom headers to use with HTTP/HTTPS requests. - -```js - -``` - -#### readOnly -bool, optional, defaults to false - -Defines whether the viewer is read-only. If true, the UI will not allow the user to change the document. - -```js - -``` -#### defaultEraserType -one of the [`Config.EraserType`](./src/Config/Config.ts) constants, optional - -Sets the default eraser tool type. Value only applied after a clean install. - -Eraser Type | Description ---- | --- -`annotationEraser` | Erases everything as an object; if you touch ink, the entire object is erased. -`hybrideEraser` | Erases ink by pixel, but erases other annotation types as objects. -`inkEraser` | Erases ink by pixel only. Android only. - -```js - -``` - -#### exportPath -string, optional - -Sets the folder path for all save options, this defaults to the app cache path. Android only. -Example: - -```js - -``` - -#### openUrlPath -string, optional - -Sets the cache folder used to cache PDF files opened using a http/https link, this defaults to the app cache path. Android only. -Example: - -```js - -``` - -#### saveStateEnabled -bool, optional, default to true - -Sets whether to remember the last visited page and zoom for a document if it gets opened again. -Example: - -```js - -``` - -#### openSavedCopyInNewTab -bool, optional, default to true, Android only. - -Sets whether the new saved file should open after saving. -Example: - -```js - -``` - -#### onDocumentLoaded -function, optional - -This function is called when the document finishes loading. - -Parameters: - -Name | Type | Description ---- | --- | --- -path | string | File path that the document has been saved to - -```js - { - console.log('The document has finished loading:', path); - }} -/> -``` - -#### onDocumentError -function, optional - -This function is called when document opening encounters an error. - -Parameters: - -Name | Type | Description ---- | --- | --- -error | string | Error message produced - -```js - { - console.log('Error occured during document opening:', error); - }} -/> -``` - -### UI Customization - -#### disabledElements -array of [`Config.Buttons`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines buttons to be disabled for the viewer. - -```js - -``` - -#### disabledTools -array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines tools to be disabled for the viewer. - -```js - -``` - -#### onToolChanged -function, optional - -This function is called when the current tool changes to a new tool - -Parameters: - -Name | Type | Description ---- | --- | --- -previousTool | string | the previous tool (one of the [`Config.Tools`](./src/Config/Config.ts) constants or "unknown tool"), representing the tool before change -tool | string | the current tool (one of the [`Config.Tools`](./src/Config/Config.ts) constants or "unknown tool"), representing the current tool - -```js - { - console.log('Tool has been changed from', previousTool, 'to', tool); - }} -/> -``` - -#### rememberLastUsedTool -boolean, optional, defaults to true, Android only - -Defines whether the last tool used in the current viewer session will be the tool selected upon starting a new viewer session. - -Example: - -```js - -``` - -#### leadingNavButtonIcon -string, optional - -The file name of the icon to be used for the leading navigation button. The button will use the specified icon if it is valid, and the default icon otherwise. - -Example: - -```js - -``` - -**Note**: to add the image file to your application, please follow the steps below: - -##### Android -1. Add the image resource to the drawable directory in [`example/android/app/src/main/res`](./example/android/app/src/main/res). For details about supported file types and potential compression, check out [here](https://developer.android.com/guide/topics/graphics/drawables#drawables-from-images). - -demo-android - -2. Now you can use the image in the viewer. For example, if you add `button_close.png` to drawable, you could use `'button_close'` in leadingNavButtonIcon. - -##### iOS -1. After pods has been installed, open the `.xcworkspace` file for this application in Xcode (in this case, it's [`example.xcworkspace`](./example/ios/example.xcworkspace)), and navigate through the list below. This would allow you to add resources, in this case, an image, to your project. -- "Project navigator" -- "example" (or the app name) -- "Build Phases" -- "Copy Bundle Resources" -- "+". - -demo-ios - -2. Now you can use the image in the viewer. For example, if you add `button_open.png` to the bundle, you could use `'button_open.png'` in leadingNavButtonIcon. - - -#### showLeadingNavButton -bool, optional, defaults to true - -Defines whether to show the leading navigation button. - -```js - -``` - -#### onLeadingNavButtonPressed -function, optional - -This function is called when the leading navigation button is pressed. - -```js - { - console.log('The leading nav has been pressed'); - }} -/> -``` - -#### overflowMenuButtonIcon -String, optional - -The file name of the icon to be used as the overflow menu button. The button will use the specified icon if it is valid, and the default icon otherwise. - -**Note**: to add the image file to your application, follow the steps under the Note section of [`leadingNavButtonIcon`](#leadingNavButtonIcon). - -Example: - -```js - -``` - -#### documentSliderEnabled -bool, optional, defaults to true - -Defines whether the document slider of the viewer is enabled. - -```js - -``` - -#### hideViewModeItems -array of [`Config.ViewModePickerItem`](./src/Config/Config.ts) constants, optional, defaults to none. - -Defines view mode items to be hidden in the view mode dialog. - -```js - -``` - -#### tabletLayoutEnabled -bool, optional, defaults to true - -Defines whether the tablet layout should be used on tablets. Otherwise uses the same layout as phones. Android only. - -```js - -``` - -#### downloadDialogEnabled -bool, optional, defaults to true - -Defines whether the download dialog should be shown. Android only. - -```js - -``` - -### Toolbar Customization - -#### topToolbarEnabled -bool, optional, defaults to true - -Deprecated. Use [`hideTopAppNavBar`](#hideTopAppNavBar) prop instead. - -#### bottomToolbarEnabled -bool, optional, defaults to true - -Defines whether the bottom toolbar of the viewer is enabled. - -```js - -``` - -#### annotationToolbars -array of [`Config.DefaultToolbars`](./src/Config/Config.ts) constants or custom toolbar objects, optional, defaults to none - -Defines custom toolbars. If passed in, the default toolbars will no longer appear. -It is possible to mix and match with default toolbars. See example below: - -```js -const myToolItem = { - [Config.CustomToolItemKey.Id]: 'add_page', - [Config.CustomToolItemKey.Name]: 'Add page', - [Config.CustomToolItemKey.Icon]: 'ic_add_blank_page_white', -}; - -const myToolbar = { - [Config.CustomToolbarKey.Id]: 'myToolbar', - [Config.CustomToolbarKey.Name]: 'myToolbar', - [Config.CustomToolbarKey.Icon]: Config.ToolbarIcons.FillAndSign, - [Config.CustomToolbarKey.Items]: [Config.Tools.annotationCreateArrow, Config.Tools.annotationCreateCallout, myToolItem, Config.Buttons.undo] -}; - - -``` - -#### onAnnotationToolbarItemPress -function, optional - -This function is called when a custom toolbar tool item is clicked - -Parameters: - -Name | Type | Description ---- | --- | --- -id | string | the `Config.CustomToolItemKey.Id` defined in the tool - -```js - { - console.log('toolbar item press: ' + id); - }} -/> - -``` - -#### hideDefaultAnnotationToolbars -array of [`Config.DefaultToolbars`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines which default annotation toolbars should be hidden. Note that this prop should be used when [`annotationToolbars`](#annotationToolbars) is not defined. - -```js - -``` - -#### hideAnnotationToolbarSwitcher -bool, optional, defaults to false - -Defines whether to show the toolbar switcher in the top toolbar. - -```js - -``` - -#### initialToolbar -one of the [`Config.DefaultToolbars`](./src/Config/Config.ts) constants or the `id` of a custom toolbar object, optional, defaults to none - -Defines which [`annotationToolbar`](#annotationToolbars) should be selected when the document is opened. - -```js - -``` - -#### hideTopToolbars -bool, optional, defaults to false - -Defines whether to hide both the top app nav bar and the annotation toolbar. - -```js - -``` - -#### hideTopAppNavBar -bool, optional, defaults to false - -Defines whether to hide the top navigation app bar. - -```js - -``` - -#### hideToolbarsOnTap -bool, optional, defaults to true - -Defines whether an unhandled tap in the viewer should toggle the visibility of the top and bottom toolbars. When false, the top and bottom toolbar visibility will not be toggled and the page content will fit between the bars, if any. - -```js - -``` - -#### topAppNavBarRightBar -array of [`Config.Buttons`](./src/Config/Config.ts) constants, optional, only the tabs, search, view mode, thumbnails, outline, undo, share, reflow, edit pages, save copy, print, file attachment, layers, digital signatures and close buttons are supported on Android - -Customizes the right bar section of the top app nav bar. If passed in, the default right bar section will not be used. - -```js - -``` - -#### bottomToolbar -array of [`Config.Buttons`](./src/Config/Config.ts) constants, optional, only the outline list, thumbnail list, share, view mode, search, and reflow buttons are supported on Android - -Defines a custom bottom toolbar. If passed in, the default bottom toolbar will not be used. - -```js - -``` - -#### padStatusBar -bool, optional, defaults to false, android only - -Defines whether the viewer will add padding to take account of the system status bar. - -```js - -``` - -### Layout - -#### fitMode -one of the [`Config.FitMode`](./src/Config/Config.ts) constants, optional, default value is `Config.FitMode.FitWidth` - -Defines the fit mode (default zoom level) of the viewer. - -```js - -``` - -#### layoutMode -one of the [`Config.LayoutMode`](./src/Config/Config.ts) constants, optional, default value is `Config.LayoutMode.Continuous` - -Defines the layout mode of the viewer. - -```js - -``` - -#### onLayoutChanged -function, optional - -This function is called when the layout of the viewer has been changed. - -```js - { - console.log('Layout has been updated.'); - }} -/> -``` - -### Page - -#### initialPageNumber -number, optional - -Defines the initial page number that viewer displays when the document is opened. Note that page numbers are 1-indexed. - -```js - -``` - -#### pageNumber -number, optional - -Defines the currently displayed page number. Different from [`initialPageNumber`](#initialPageNumber), changing this prop value at runtime will change the page accordingly. - -```js - -``` - -#### pageChangeOnTap -bool, optional, defaults to true - -Defines whether the viewer should change pages when the user taps the edge of a page, when the viewer is in a horizontal viewing mode. - -```js - -``` - -#### pageIndicatorEnabled -bool, optional, defaults to true - -Defines whether to show the page indicator for the viewer. - -```js - -``` - -#### keyboardShortcutsEnabled -bool, optional, defaults to true - -Defines whether the keyboard shortcuts of the viewer are enabled. - -```js - -``` - -#### onPageChanged -function, optional - -This function is called when the page number has been changed. - -Parameters: - -Name | Type | Description ---- | --- | --- -previousPageNumber | int | the previous page number -pageNumber | int | the current page number - -```js - { - console.log('Page number changes from', previousPageNumber, 'to', pageNumber); - }} -/> -``` - -#### onPageMoved -function, optional - -This function is called when a page has been moved in the document. - -Parameters: - -Name | Type | Description ---- | --- | --- -previousPageNumber | int | the previous page number -pageNumber | int | the current page number - -```js - { - console.log('Page moved from', previousPageNumber, 'to', pageNumber); - }} -/> -``` - -#### onPagesAdded -function, optional - -This function is called when pages are added to the document. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumbers | array | An array of the page numbers that were added to the document - -```js - { - console.log('Pages added:', pageNumbers); - }} -/> -``` - -### Zoom - -#### onZoomChanged -function, optional - -This function is called when the zoom scale has been changed. - -Parameters: - -Name | Type | Description ---- | --- | --- -zoom | double | the current zoom ratio of the document - -```js - { - console.log('Current zoom ratio is', zoom); - }} -/> -``` - -#### onZoomFinished -function, optional - -This function is called when a zooming has been finished. For example, if zoom via gesture, this is called on gesture release. - -Parameters: - -Name | Type | Description ---- | --- | --- -zoom | double | the current zoom ratio of the document - -```js - { - console.log('Current zoom ratio is', zoom); - }} -``` - -### Scroll - -#### horizontalScrollPos -number, optional - -Defines the horizontal scroll position in the current document viewer. - -```js - -``` - -#### verticalScrollPos -number, optional - -Defines the vertical scroll position in the current document viewer. - -```js - -``` - -#### onScrollChanged -function, optional - -This function is called when the scroll position has been changed. - -Parameters: - -Name | Type | Description ---- | --- | --- -horizontal | number | the horizontal position of the scroll -vertical | number | the vertical position of the scroll - -```js - { - console.log('Current scroll position is', horizontal, 'horizontally, and', vertical, 'vertically.'); - }} -``` - -#### hideScrollbars -bool, optional, iOS only, defaults to false - -Determines whether scrollbars will be hidden on the viewer. - -```js - -``` - -### Reflow - -#### imageInReflowEnabled -bool, optional, defaults to true, will be available on iOS in version 9.1.2 and greater - -Whether to show images in reflow mode. - -```js - -``` - -#### reflowOrientation -one of the [`Config.ReflowOrientation`](./src/Config/Config.ts) constants, optional, defaults to the viewer's scroll direction. - -Sets the scrolling direction of the reflow control. - -```js - -``` - -### Annotation Menu - -#### hideAnnotationMenu -array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines annotation types that will not show in the annotation (long-press) menu. - -```js - -``` - -#### annotationMenuItems -array of [`Config.AnnotationMenu`](./src/Config/Config.ts) constants, optional, default contains all the items - -Defines the menu items that can show when an annotation is selected. - -```js - -``` - -#### overrideAnnotationMenuBehavior -array of [`Config.AnnotationMenu`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines the menu items that will skip default behavior when pressed. They will still be displayed in the annotation menu, and the function [`onAnnotationMenuPress`](#onAnnotationMenuPress) will be called where custom behavior can be implemented. - -```js - -``` - -#### onAnnotationMenuPress -function, optional - -This function is called when an annotation menu item passed in to [`overrideAnnotationMenuBehavior`](#overrideAnnotationMenuBehavior) is pressed. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotationMenu | string | One of [`Config.AnnotationMenu`](./src/Config/Config.ts) constants, representing which item has been pressed -annotations | array | An array of `{id: string, pageNumber: number, type: string, screenRect: object, pageRect: object}` objects.

`id` is the annotation identifier and `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`. Both rects are represented with `{x1: number, y1: number, x2: number, y2: number, width: number, height: number}` objects. - -```js - { - console.log('Annotation menu item', annotationMenu, 'has been pressed'); - annotations.forEach(annotation => { - console.log('The id of selected annotation is', annotation.id); - console.log('The page number of selected annotation is', annotation.pageNumber); - console.log('The type of selected annotation is', annotation.type); - console.log('The screenRect of selected annotation is', annotation.screenRect); - console.log('The pageRect of selected annotation is', annotation.pageRect); - }); - }} -/> -``` - -### Long Press Menu - -#### longPressMenuEnabled -bool, optional, defaults to true - -Defines whether to show the popup menu of options when the user long presses on text or blank space on the document. - -```js - -``` - -#### longPressMenuItems -array of [`Config.LongPressMenu`](./src/Config/Config.ts) constants, optional, default contains all the items - -Defines menu items that can show when long press on text or blank space. - -```js - -``` - -#### overrideLongPressMenuBehavior -array of [`Config.LongPressMenu`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines the menu items on long press that will skip default behavior when pressed. They will still be displayed in the long press menu, and the function [`onLongPressMenuPress`](#onLongPressMenuPress) will be called where custom behavior can be implemented. - -```js - -``` - -#### onLongPressMenuPress -function, optional - -This function is called if the pressed long press menu item is passed in to [`overrideLongPressMenuBehavior`](#overrideLongPressMenuBehavior) - -Parameters: - -Name | Type | Description ---- | --- | --- -longPressMenu | string | One of [`Config.LongPressMenu`](./src/Config/Config.ts) constants, representing which item has been pressed -longPressText | string | the selected text if pressed on text, empty otherwise - -```js - { - console.log('Long press menu item', longPressMenu, 'has been pressed'); - if (longPressText !== '') { - console.log('The selected text is', longPressText); - } - }} -/> -``` - -### Custom Behavior - -#### overrideBehavior -array of [`Config.Actions`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines actions that will skip default behavior, such as external link click. The function [`onBehaviorActivated`](#onBehaviorActivated) will be called where custom behavior can be implemented, whenever the defined actions occur. - -```js - -``` - -#### onBehaviorActivated -function, optional - -This function is called if the activated behavior is passed in to [`overrideBehavior`](#overrideBehavior) - -Parameters: - -Name | Type | Description ---- | --- | --- -action | string | One of [`Config.Actions`](./src/Config/Config.ts) constants, representing which action has been activated -data | object | A JSON object that varies depending on the action - -Data param table: - -Action | Data param ---- | --- -[`Config.Actions.linkPress`](./src/Config/Config.ts) | `{url: string}` -[`Config.Actions.stickyNoteShowPopUp`](./src/Config/Config.ts) | `{id: string, pageNumber: number, type: string, screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. Type is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`. - -```js - { - console.log('Activated action is', action); - if (action === Config.Actions.linkPress) { - console.log('The external link pressed is', data.url); - } else if (action === Config.Actions.stickyNoteShowPopUp) { - console.log('Sticky note has been activated, but it would not show a pop up window.'); - } - }} -/> -``` - -### Multi-tab - -#### multiTabEnabled -bool, optional, defaults to false - -Defines whether viewer will use tabs in order to have more than one document open simultaneously (like a web browser). Changing the [`document`](#document) prop value will cause a new tab to be opened with the associated file. - -```js - -``` - -#### tabTitle -string, optional, default is the file name - -Set the tab title if [`multiTabEnabled`](#multiTabEnabled) is true. - -```js - -``` - -#### maxTabCount -number, optional, defaults to unlimited - -Sets the limit on the maximum number of tabs that the viewer could have at a time. Open more documents after reaching this limit will overwrite the old tabs. - -```js - -``` - -#### onTabChanged -function, optional - -The function is activated when a tab is changed. - -Please note that this API is meant for tab-specific changes. If you would like to know when the document finishes loading instead, see the [`onDocumentLoaded`](#onDocumentLoaded) event. - -Parameters: - -Name | Type | Description ---- | --- | --- -currentTab | string | The file path of current tab's document - - -```js - { - console.log("The current tab is ", currentTab); - }} -/> -``` - -### Collaboration - -#### collabEnabled -bool, optional, defaults to false - -Defines whether to enable realtime collaboration. If true then `currentUser` must be set as well for collaboration mode to work. Feature set may vary between local and collaboration mode. - -```js - -``` - -#### currentUser -string, required if [`collabEnabled`](#collabEnabled) is set to true - -Defines the current user. Created annotations will have their title (author) set to this string. - -```js - -``` - -#### currentUserName -string, optional - -Defines the current user name. Will set the user name only if [`collabEnabled`](#collabEnabled) is true and [`currentUser`](#currentUser) is defined. This should be used only if you want the user's display name to be different than the annotation's title/author (in the case that `currentUser` is an ID rather than a human-friendly name.) - -```js - -``` - -#### annotationManagerEditMode -one of the [`Config.AnnotationManagerEditMode`](./src/Config/Config.js) constants, optional, default value is `Config.AnnotationManagerEditMode.Own` - -Sets annotation manager edit mode when [`collabEnabled`](#collabEnabled) is true. - -Mode | Description ---- | --- -`Config.AnnotationManagerEditMode.Own` | In this mode, you can edit only your own changes -`Config.AnnotationManagerEditMode.All` | In this mode, you can edit everyone's changes - -```js - -``` - -#### annotationManagerUndoMode -one of the [`Config.AnnotationManagerUndoMode`](./src/Config/Config.js) constants, optional, default value is `Config.AnnotationManagerUndoMode.Own` - -Sets annotation manager undo mode when [`collabEnabled`](#collabEnabled) is true. - -Mode | Description ---- | --- -`Config.AnnotationManagerUndoMode.Own` | In this mode, you can undo only your own changes -`Config.AnnotationManagerUndoMode.All` | In this mode, you can undo everyone's changes - -```js - -``` - -#### replyReviewStateEnabled -boolean, optional, Android only, defaults to true - -Defines whether to show an annotation's reply review state. - -```js - -``` - -### Annotations - -#### annotationPermissionCheckEnabled -bool, optional, defaults to false - -Defines whether an annotation's permission flags will be respected when it is selected. For example, a locked annotation can not be resized or moved. - -```js - -``` - -#### annotationAuthor -string, optional - -Defines the author name for all annotations created on the current document. Exported xfdfCommand will include this piece of information. - -```js - -``` - -#### continuousAnnotationEditing -bool, optional, defaults to true - -If true, the active annotation creation tool will remain in the current annotation creation tool. Otherwise, it will revert to the "pan tool" after an annotation is created. - -```js - -``` - -#### inkMultiStrokeEnabled -bool, optional, defaults to true - -If true, ink tool will use multi-stroke mode. Otherwise, each stroke is a new ink annotation. - -```js - -``` - -#### selectAnnotationAfterCreation -bool, optional, defaults to true - -Defines whether an annotation is selected after it is created. On iOS, this functions for shape and text markup annotations only. - -```js - -``` - -#### onExportAnnotationCommand -function, optional - -This function is called if a change has been made to annotations in the current document. Unlike [`onAnnotationChanged`](#onAnnotationChanged), this function has an XFDF command string as its parameter. If you are modifying or deleting multiple annotations, then on Android the function is only called once, and on iOS it is called for each annotation. - - -Parameters: - -Name | Type | Description ---- | --- | --- -action | string | the action that occurred (add, delete, modify) -xfdfCommand | string | an xfdf string containing info about the edit -annotations | array | an array of annotation data. When collaboration is enabled data comes in the format `{id: string}`, otherwise the format is `{id: string, pageNumber: number, type: string}`. In both cases, the data represents the annotations that have been changed. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants - -**Known Issues**
-On iOS, there is currently a bug that prevents the last XFDF from being retrieved when modifying annotations while collaboration mode is enabled. - -```js - { - console.log('Annotation edit action is', action); - console.log('The exported xfdfCommand is', xfdfCommand); - annotations.forEach((annotation) => { - console.log('Annotation id is', annotation.id); - if (!this.state.collabEnabled) { - console.log('Annotation pageNumber is', annotation.pageNumber); - console.log('Annotation type is', annotation.type); - } - }); - }} - collabEnabled={this.state.collabEnabled} - currentUser={'Pdftron'} -/> -``` - -#### onAnnotationsSelected -function, optional - -This function is called when an annotation(s) is selected. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotations | array | array of annotation data in the format `{id: string, pageNumber: number, type: string, screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`, representing the selected annotations. Type is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`. - -```js - { - annotations.forEach(annotation => { - console.log('The id of selected annotation is', annotation.id); - console.log('It is in page', annotation.pageNumber); - console.log('Its type is', annotation.type); - }); - }} -/> -``` - -#### onAnnotationChanged -function, optional - -This function is called if a change has been made to an annotation(s) in the current document. - -Note: When an annotation is flattened, it also gets deleted, so both [`onAnnotationChanged`](#onAnnotationChanged) and [`onAnnotationFlattened`](#onAnnotationFlattened) are called. - -Parameters: - -Name | Type | Description ---- | --- | --- -action | string | the action that occurred (add, delete, modify) -annotations | array | array of annotation data in the format `{id: string, pageNumber: number, type: string}`, representing the annotations that have been changed. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants - -```js - { - console.log('Annotation edit action is', action); - annotations.forEach(annotation => { - console.log('The id of changed annotation is', annotation.id); - console.log('It is in page', annotation.pageNumber); - console.log('Its type is', annotation.type); - }); - }} -/> -``` - -#### onAnnotationFlattened -function, optional - -This function is called if an annotation(s) has been flattened in the current document. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotations | array | array of annotation data in the format `{id: string, pageNumber: number, type: string}`, representing the annotations that have been changed. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `id`s returned via the event listener can be null. - -```js - { - annotations.forEach(annotation => { - console.log('The id of changed annotation is', annotation.id); - console.log('It is in page', annotation.pageNumber); - console.log('Its type is', annotation.type); - }); - }} -/> -``` - -#### onFormFieldValueChanged -function, optional - -This function is called if a change has been made to form field values. - -Parameters: - -Name | Type | Description ---- | --- | --- -fields | array | array of field data in the format `{fieldName: string, fieldType: string, fieldValue: any}`, representing the fields that have been changed - -```js - { - fields.forEach(field => { - console.log('The name of the changed field is', field.fieldName); - console.log('The type of the changed field is', field.fieldType); - console.log('The value of the changed field is', field.fieldValue); - }); - }} -/> -``` - -#### annotationsListEditingEnabled -bool, optional, default value is true - -If document editing is enabled, then this value determines if the annotation list is editable. - - -```js - -``` - -#### disableEditingByAnnotationType -array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none. - -Defines annotation types that cannot be edited after creation. - -```js - -``` - -#### excludedAnnotationListTypes -array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none - -Defines types to be excluded from the annotation list. -Example use: - -```js - -``` - -### Bookmark - -#### onBookmarkChanged -function, optional - -This function is called if a change has been made to user bookmarks. - -Parameters: - -Name | Type | Description ---- | --- | --- -bookmarkJson | string | the list of current bookmarks in JSON format - -```js - { - console.log('Bookmarks have been changed. Current bookmark collection is', bookmarkJson); - }} -/> -``` - -#### userBookmarksListEditingEnabled -bool, optional, default value is true - -Defines whether the bookmark list can be edited. If the viewer is readonly then bookmarks on Android are -still editable but are saved to the device rather than the PDF. - -```js - -``` - -### Signature - -#### signSignatureFieldsWithStamps -bool, optional, defaults to false - -Defines whether signature fields will be signed with image stamps. -This is useful if you are saving XFDF to remote source. - -```js - -``` - -#### showSavedSignatures -bool, optional, defaults to true - -Defines whether to show saved signatures for re-use when using the signing tool. - -```js - -``` - -#### storeNewSignature -bool, optional, defaults to true. - -Defines whether to store new signatures when using the signing tool. - -```js - -``` - -#### photoPickerEnabled -bool, optional, defaults to true. Android only. - -Defines whether to show the option to pick images in the signature dialog. - -```js - -``` - -### Thumbnail Browser - -#### hideThumbnailFilterModes -array of [`Config.ThumbnailFilterMode`](./src/Config/Config.ts) constants, optional - -Defines filter modes that should be hidden in the thumbnails browser. - -```js - -``` - -#### thumbnailViewEditingEnabled -bool, optional, defaults to true - -Defines whether user can modify the document using the thumbnail view (eg add/remove/rotate pages). - -```js - -``` - -### Text Selection - -#### onTextSearchStart -function, optional - -This function is called immediately before a text search begins, either through user actions, or function calls such as [`findText`](#findText). - -```js - { - console.log('Text search has started'); - }} -/> -``` - -#### onTextSearchResult -function, optional - -This function is called after a text search is finished or canceled. - -Parameters: - -Name | Type | Description ---- | --- | --- -found | bool | whether a result is found. If no, it could be caused by not finding a matching result in the document, invalid text input, or action cancellation (user actions or [`cancelFindText`](#cancelFindText)) -textSelection | object | the text selection, in the format `{html: string, unicode: string, pageNumber: number, quads: [[{x: number, y: number}, {x: number, y: number}, {x: number, y: number}, {x: number, y: number}], ...]}`. If no such selection could be found, this would be null - -quads indicate the quad boundary boxes for the selection, which could have a size larger than 1 if selection spans across different lines. Each quad have 4 points with x, y coordinates specified in number, representing a boundary box. The 4 points are in counter-clockwise order, though the first point is not guaranteed to be on lower-left relatively to the box. - -```js - { - if (found) { - console.log('Found selection on page', textSelection.pageNumber); - for (let i = 0; i < textSelection.quads.length; i ++) { - const quad = textSelection.quads[i]; - console.log('selection boundary quad', i); - for (const quadPoint of quad) { - console.log('A quad point has coordinates', quadPoint.x, quadPoint.y); - } - } - } - }} -/> -``` - -### Others - -#### useStylusAsPen -bool, optional, defaults to true - -Defines whether a stylus should act as a pen when in pan mode. If false, it will act as a finger. - -```js - -``` - -#### followSystemDarkMode -bool, optional, Android and iOS 13+ only, defaults to true - -Defines whether the UI will appear in a dark color when the system is dark mode. If false, it will use viewer setting instead. - -```js - -``` - -#### autoSaveEnabled -bool, optional, defaults to true - -Defines whether document is automatically saved by the viewer. - -```js - -``` - -#### autoResizeFreeTextEnabled -bool, optional, defaults to false - -Defines whether to automatically resize the bounding box of free text annotations when editing. - -```js - -``` - -#### restrictDownloadUsage -bool, optional, defaults to false - -Defines whether to restrict data usage when viewing online PDFs. - -```js - -``` - -### Navigation - -#### pageStackEnabled -bool, optional, defaults to true, Android only - -Deprecated. Use the [`showQuickNavigationButton`](#showQuickNavigationButton) prop instead. - -Defines whether the page stack navigation buttons will appear in the viewer. - -```js - -``` - -#### showQuickNavigationButton -bool, optional, defaults to true - -Defines whether the quick navigation buttons will appear in the viewer. - -```js - -``` - -#### showNavigationListAsSidePanelOnLargeDevices -bool, optional, defaults to true on Android and false on iOS - -Defines whether the navigation list will be displayed as a side panel on large devices such as iPads and tablets. - -```js - -``` - -#### onUndoRedoStateChanged -function, optional - -This function is called when the state of the current document's undo/redo stack has been changed. - -```js - { - console.log("Undo/redo stack state changed"); - }} -/> -``` - -## DocumentView - Methods - -### Document - -#### getDocumentPath -Returns the path of the current document. If [`isBase64String`](#isBase64String) is true, this would be the path to the temporary pdf file converted from the base64 string in [`document`](#document). - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -path | string | the document path - -```js -this._viewer.getDocumentPath().then((path) => { - console.log('The path to current document is: ' + path); -}); -``` - -#### saveDocument -Saves the current document. If [`isBase64String`](#isBase64String) is true, this would be the base64 string encoded from the temporary pdf file, which is created from the base64 string in [`document`](#document). - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -filePath | string | the location of the saved document, or the base64 string of the pdf in the case of base64 - -```js -this._viewer.saveDocument().then((filePath) => { - console.log('saveDocument:', filePath); -}); -``` - -### UI Customization - -#### setColorPostProcessMode -Sets the color post processing transformation mode for the viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -colorPostProcessMode | string | color post processing transformation mode, should be a [`Config.ColorPostProcessMode`](./src/Config/Config.ts) constant - -```js -this._viewer.setColorPostProcessMode(Config.ColorPostProcessMode.NightMode); -``` - -#### setColorPostProcessColors -Sets the white and black color for the color post processing transformation. - -Parameters: - -Name | Type | Description ---- | --- | --- -whiteColor | object | the white color for the color post processing transformation, in the format `{red: number, green: number, blue: number}`. `alpha` could be optionally included (only Android would apply alpha), and all numbers should be in range [0, 255] -blackColor | object | the black color for the color post processing transformation, in the same format as whiteColor - -```js -const whiteColor = {"red": 0, "green": 0, "blue": 255}; -const blackColor = {"red": 255, "green": 0, "blue": 0}; -this._viewer.setColorPostProcessColors(whiteColor, blackColor); -``` - -### Annotation Tools - -#### setToolMode -Sets the current tool mode. - -Returns a Promise. - -Parameters: - -Name | Type | Description ---- | --- | --- -toolMode | string | One of [`Config.Tools`](./src/Config/Config.ts) constants, representing to tool mode to set - -```js -this._viewer.setToolMode(Config.Tools.annotationCreateFreeHand).then(() => { - // done switching tools -}); -``` - -#### commitTool -Commits the current tool, only available for multi-stroke ink and poly-shape. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -committed | bool | true if either ink or poly-shape tool is committed, false otherwise - -```js -this._viewer.commitTool().then((committed) => { - // committed: true if either ink or poly-shape tool is committed, false otherwise -}); -``` - -### Page - -#### getPageCount -Gets the current page count of the document. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -pageCount | int | the current page count of the document - -```js -this._viewer.getPageCount().then((pageCount) => { - console.log('pageCount', pageCount); -}); -``` - -#### setCurrentPage -Sets current page of the document. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | integer | the page number to be set as the current page; 1-indexed - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -success | bool | whether the setting process was successful - -```js -this._viewer.setCurrentPage(4).then((success) => { - if (success) { - console.log("Current page is set to 4."); - } -}); -``` - -#### gotoPreviousPage -Go to the previous page of the document. If on first page, it would stay on first page. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -success | bool | whether the setting process was successful (no change due to staying in first page counts as being successful) - -```js -this._viewer.gotoPreviousPage().then((success) => { - if (success) { - console.log("Go to previous page."); - } -}); -``` - -#### gotoNextPage -Go to the next page of the document. If on last page, it would stay on last page. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -success | bool | whether the setting process was successful (no change due to staying in last page counts as being successful) - -```js -this._viewer.gotoNextPage().then((success) => { - if (success) { - console.log("Go to next page."); - } -}); -``` - -#### gotoFirstPage -Go to the first page of the document. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -success | bool | whether the setting process was successful - -```js -this._viewer.gotoFirstPage().then((success) => { - if (success) { - console.log("Go to first page."); - } -}); -``` - -#### gotoLastPage -Go to the last page of the document. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -success | bool | whether the setting process was successful - -```js -this._viewer.gotoLastPage().then((success) => { - if (success) { - console.log("Go to last page."); - } -}); -``` - -#### showGoToPageView -Opens a go-to page dialog. If the user inputs a valid page number into the dialog, the viewer will go to that page. - -Returns a Promise. - -```js -this._viewer.showGoToPageView(); -``` - -#### getPageCropBox -Gets the crop box for specified page as a JSON object. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | integer | the page number for the target crop box. It is 1-indexed - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -cropBox | object | an object with information about position (`x1`, `y1`, `x2` and `y2`) and size (`width` and `height`) - -```js -this._viewer.getPageCropBox(1).then((cropBox) => { - console.log('bottom-left coordinate:', cropBox.x1, cropBox.y1); - console.log('top-right coordinate:', cropBox.x2, cropBox.y2); - console.log('width and height:', cropBox.width, cropBox.height); -}); -``` - -#### getVisiblePages -Gets the visible pages in the current viewer as an array. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -visiblePages | array | a list of visible pages in the current viewer - -```js -this._viewer.getVisiblePages().then((visiblePages) => { - for (const page of visiblePages) { - console.log('page', page, 'is visible.') - } -}); -``` - -#### getPageRotation -Gets the rotation value of all pages in the current document. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -pageRotation | number | the rotation degree of all pages, one of 0, 90, 180 or 270 (clockwise). - -```js -this._viewer.getPageRotation().then((pageRotation) => { - console.log('The current page rotation degree is' + pageRotation); -}); -``` - -#### rotateClockwise -Rotates all pages in the current document in clockwise direction (by 90 degrees). - -Returns a Promise. - -```js -this._viewer.rotateClockwise(); -``` - -#### rotateCounterClockwise -Rotates all pages in the current document in counter-clockwise direction (by 90 degrees). - -Returns a Promise. - -```js -this._viewer.rotateCounterClockwise(); -``` - -#### showRotateDialog -Displays a rotate dialog. Android only. - -The dialog allows users to rotate pages of the opened document by 90, 180 and 270 degrees. It also displays a thumbnail of the current page at the selected rotation angle. - -Returns a Promise. - -```js -this._viewer.showRotateDialog(); -``` - -### Import/Export Annotations - -#### importAnnotationCommand -Imports remote annotation command to local document. Can be used in both local and collaboration mode. - -Parameters: - -Name | Type | Description ---- | --- | --- -xfdfCommand | string | the XFDF command string -initialLoad | bool | whether this is for initial load. Will be false by default - -Returns a Promise. - -```js -const xfdfCommand = ''; -this._viewer.importAnnotationCommand(xfdfCommand); - -``` - -#### importAnnotations -Imports XFDF annotation string to the current document. - -`importAnnotations` should only be used in local mode. To import annotations in collaboration mode, use [`importAnnotationCommand`](#importAnnotationCommand). - -Parameters: - -Name | Type | Description ---- | --- | --- -xfdf | string | annotation string in XFDF format for import - -Returns a Promise. - -```js -const xfdf = '\n\n\t\n\t\t\n\t\n\t\t\n\t\n\t\n'; -this._viewer.importAnnotations(xfdf); -``` - -#### exportAnnotations -Extracts XFDF from the current document. - -Parameters: - -Name | Type | Description ---- | --- | --- -options | object | key: annotList, type: array. If specified, annotations with the matching id and pageNumber will be exported; otherwise, all annotations in the current document will be exported. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -xfdf | string | annotation string in XFDF format - -Without options: - -```js -this._viewer.exportAnnotations().then((xfdf) => { - console.log('XFDF for all annotations:', xfdf); -}); -``` - -With options: - -```js -// annotList is an array of annotation data in the format {id: string, pageNumber: int} -const annotations = [{id: 'annot1', pageNumber: 1}, {id: 'annot2', pageNumber: 3}]; -this._viewer.exportAnnotations({annotList: annotations}).then((xfdf) => { - console.log('XFDF for 2 specified annotations', xfdf); -}); -``` - -### Annotations - -#### flattenAnnotations -Flattens the forms and (optionally) annotations in the current document. - -Parameters: - -Name | Type | Description ---- | --- | --- -formsOnly | bool | Defines whether only forms are flattened. If false, all annotations will be flattened - -Returns a Promise. - -```js -// flatten forms and annotations in the current document. -this._viewer.flattenAnnotations(false); -``` - -#### deleteAnnotations -Deletes the specified annotations in the current document. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotations | array | Defines which annotation to be deleted. Each element is in the format {id: string, pageNumber: int} - -Returns a Promise. - -```js -// delete annotations in the current document. -this._viewer.deleteAnnotations([ - { - id: 'annotId1', - pageNumber: 1, - }, - { - id: 'annotId2', - pageNumber: 2, - } -]); -``` - -#### selectAnnotation -Selects the specified annotation in the current document. - -Parameters: - -Name | Type | Description ---- | --- | --- -id | string | the id of the target annotation -pageNumber | integer | the page number where the targe annotation is located. It is 1-indexed - -Returns a Promise. - -```js -// select annotation in the current document. -this._viewer.selectAnnotation('annotId1', 1); -``` - -#### setFlagsForAnnotations -Sets flags for specified annotations in the current document. The `flagValue` controls whether a flag will be set to or removed from the annotation. - -Note: the old function `setFlagForAnnotations` is deprecated. Please use this one. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotationFlagList | array | A list of annotation flag operations. Each element is in the format {id: string, pageNumber: int, flag: One of [`Config.AnnotationFlags`](./src/Config/Config.ts) constants, flagValue: bool} - -Returns a Promise. - -```js -// Set flag for annotations in the current document. -this._viewer.setFlagsForAnnotations([ - { - id: 'annotId1', - pageNumber: 1, - flag: Config.AnnotationFlags.noView, - flagValue: true - }, - { - id: 'annotId2', - pageNumber: 5, - flag: Config.AnnotationFlags.lockedContents, - flagValue: false - } -]); -``` - -#### setPropertiesForAnnotation -Sets properties for specified annotation in the current document, if it is valid. - -Note: the old function `setPropertyForAnnotation` is deprecated. Please use this one. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotationId | string | the unique id of the annotation -pageNumber | integer | the page number where annotation is located. It is 1-indexed -propertyMap | object | an object containing properties to be set. Available properties are listed below - -Properties in propertyMap: - -Name | Type | Markup exclusive | Example ---- | --- | --- | --- -rect | object | no | {x1: 1, y1: 2, x2: 3, y2: 4} -contents | string | no | "contents" -subject | string | yes | "subject" -title | string | yes | "title" -contentRect | object | yes | {x1: 1, y1: 2, x2: 3, y2: 4} -customData | object | no | {key: value} -strokeColor | object | no | {red: 255, green: 0, blue: 0} - -Returns a promise. - -```js -// Set properties for annotation in the current document. -this._viewer.setPropertiesForAnnotation('Pdftron', 1, { - rect: { - x1: 1.1, // left - y1: 3, // bottom - x2: 100.9, // right - y2: 99.8 // top - }, - contents: 'Hello World', - subject: 'Sample', - title: 'set-prop-for-annot', - customData: { - key1: 'value1', - key2: 'value2', - key3: 'value3' - }, - strokeColor: { - "red": 255, - "green": 0, - "blue": 0 - } -}); -``` - -#### getPropertiesForAnnotation -Gets properties for specified annotation in the current document, if it is valid. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotationId | string | the unique id of the annotation -pageNumber | integer | the page number where annotation is located. It is 1-indexed - -Available Properties: - -Name | Type | Markup exclusive | Example ---- | --- | --- | --- -rect | object | no | {x1: 1, y1: 1, x2: 2, y2: 2, width: 1, height: 1} -contents | string | no | "Contents" -subject | string | yes | "Subject" -title | string | yes | "Title" -contentRect | object | yes | {x1: 1, y1: 1, x2: 2, y2: 2, width: 1, height: 1} -strokeColor | object | no | {red: 255, green: 0, blue: 0} - -Returns a promise. - -Promise Parameters: - -Name | Type | Description | Example ---- | --- | --- | --- -propertyMap | object | the non-null properties of the annotation | `{contents: 'Contents', strokeColor: {red: 255, green: 0, blue: 0}, rect: {x1: 1, y1: 1, x2: 2, y2: 2, width: 1, height: 1}}` - -```js -// Get properties for annotation in the current document. -this._viewer.getPropertiesForAnnotation('Pdftron', 1).then((properties) => { - if (properties) { - console.log('Properties for annotation: ', properties); - } -}) -``` - -#### setDrawAnnotations -Sets whether all annotations and forms should be rendered. This method affects the viewer and does not change the document. - -Unlike [setVisibilityForAnnotation](#setVisibilityForAnnotation), this method is used to show and hide all annotations and forms in the viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -drawAnnotations | bool | whether all annotations and forms should be rendered - -Returns a promise. - -```js -this._viewer.setDrawAnnotations(false); -``` - -#### setVisibilityForAnnotation -Sets visibility for specified annotation in the current document, if it is valid. Note that if [`drawAnnotations`](#drawAnnotations) is set to false in the viewer, this function would not render the annotation even if visibility is true. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotationId | string | the unique id of the annotation -pageNumber | integer | the page number where annotation is located. It is 1-indexed -visibility | bool | whether the annotation should be visible - -Returns a promise. - -```js -this._viewer.setVisibilityForAnnotation('Pdftron', 1, true); -``` - -#### setHighlightFields -Enables or disables highlighting form fields. It is disabled by default. - -Parameters: - -Name | Type | Description ---- | --- | --- -highlightFields | bool | whether form fields should be highlighted - -```js -this._viewer.setHighlightFields(true); -``` - - -#### getAnnotationAtPoint -Gets an annotation at the (x, y) position in screen coordinates, if any. - -Parameters: - -Name | Type | Description ---- | --- | --- -x | integer | the x-coordinate of the point -y | integer | the y-coordinate of the point -distanceThreshold | double | maximum distance from the point (x, y) to the annotation for it to be considered a hit (in dp) -minimumLineWeight | double | For very thin lines, it is almost impossible to hit the actual line. This specifies a minimum line thickness (in screen coordinates) for the purpose of calculating whether a point is inside the annotation or not (in dp) - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -annotation | object | the annotation found in the format of `{id: string, pageNumber: number, type: string, screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`. - -```js -this._viewer.getAnnotationAtPoint(167, 287, 100, 10).then((annotation) => { - if (annotation) { - console.log('Annotation found at point (167, 287) has id:', annotation.id); - } -}) -``` - -#### getAnnotationListAt -Gets the list of annotations at a given line in screen coordinates. Note that this is not an area selection. It should be used similar to [`getAnnotationAtPoint`](#getAnnotationAtPoint), except that this should be used when you want to get multiple annotations which are overlaying with each other. - -Parameters: - -Name | Type | Description ---- | --- | --- -x1 | integer | the x-coordinate of an endpoint on the line -y1 | integer | the y-coordinate of an endpoint on the line -x2 | integer | the x-coordinate of the other endpoint on the line, usually used as a threshold -y2 | integer | the y-coordinate of the other endpoint on the line, usually used as a threshold - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -annotations | array | list of annotations at the target line, each in the format of `{id: string, pageNumber: number, type: string, screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`. - -```js -this._viewer.getAnnotationListAt(0, 0, 200, 200).then((annotations) => { - for (const annotation of annotations) { - console.log('Annotation found at line has id:', annotation.id); - } -}) -``` - -#### getAnnotationsOnPage -Gets the list of annotations on a given page. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | integer | the page number where annotations are located. It is 1-indexed - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -annotations | array | list of annotations on the target page, each in the format of `{id: string, pageNumber: number, type: string, screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`. - -```js -this._viewer.getAnnotationsOnPage(2).then((annotations) => { - for (const annotation of annotations) { - console.log('Annotation found on page 2 has id:', annotation.id); - } -}) -``` - -#### getCustomDataForAnnotation -Gets an annotation's `customData` property. - -Parameters: - -Name | Type | Description ---- | --- | --- -annotationId | string | the unique id of the annotation -pageNumber | integer | the page number where annotation is located. It is 1-indexed -key | string | the unique key associated with the `customData` property - -Returns a Promise. - -Promise Parameters: -Name | Type | Description ---- | --- | --- -value | string | the `customData` property associated with the given key - -```js -this._viewer.setPropertiesForAnnotation("annotation1", 2, { - customData: { - data: "Nice annotation" - } -}).then(() => { - this._viewer.getCustomDataForAnnotation("annotation1", 2, "data").then((value) => { - console.log(value === "Nice annotation"); - }) -}) -``` - -#### setFlagForFields -Sets a field flag value on one or more form fields. - -Parameters: - -Name | Type | Description ---- | --- | --- -fields | array | list of field names for which the flag should be set -flag | int | flag to be set. Number should be a [`Config.FieldFlags`](./src/Config/Config.ts) constant -value | bool | value to set for flag - -Returns a Promise. - -```js -this._viewer.setFlagForFields(['First Name', 'Last Name'], Config.FieldFlags.ReadOnly, true); -``` - -#### setValuesForFields -Sets field values on one or more form fields. - -Note: the old function `setValueForFields` is deprecated. Please use this one instead. - -Parameters: - -Name | Type | Description ---- | --- | --- -fieldsMap | object | map of field names and values which should be set - -Returns a Promise. - -```js -this._viewer.setValuesForFields({ - 'textField1': 'Test', - 'textField2': 1234, - 'checkboxField1': true, - 'checkboxField2': false, - 'radioButton1': 'Yes', - 'radioButton2': 'No' -}); -``` - -#### getField -Get type and value information of a field using its name. - -Parameters: - -Name | Type | Description ---- | --- | --- -fieldName | string | name of the field - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -field | object | an object with information key `fieldName`, `fieldValue` (undefined for fields with no values) and `fieldType`(one of button, checkbox, radio, text, choice, signature and unknown), or undefined if such field does not exist - -```js -this._viewer.getField('someFieldName').then((field) => { - if (field !== undefined) { - console.log('field name:', field.fieldName); - console.log('field value:', field.fieldValue); - console.log('field type:', field.fieldType); - } -}); -``` - -#### openAnnotationList -Displays the annotation tab of the existing list container. If this tab has been disabled, the method does nothing. - -Returns a Promise. - -```js -this._viewer.openAnnotationList(); -``` - -#### openThumbnailsView -Display a page thumbnails view. - -This view allows users to navigate pages of a document. If [`thumbnailViewEditingEnabled`](#thumbnailViewEditingEnabled) is true, the user can also manipulate the document, including add, remove, re-arrange, rotate and duplicate pages. - -Returns a Promise. - -```js -this._viewer.openThumbnailsView(); -``` - -### Toolbar - -#### setCurrentToolbar -Sets the current [`annotationToolbar`](#annotationToolbars) for the viewer. - -Returns a Promise. - -Parameters: - -Name | Type | Description ---- | --- | --- -toolbar | string | the toolbar to enable. Should be one of the [`Config.DefaultToolbars`](./src/Config/Config.ts) constants or the `id` of a custom toolbar object. - -```js -this._viewer.setCurrentToolbar(Config.DefaultToolbars.Insert).then(() => { - // done switching toolbar -}); -``` - -### Navigation - -#### handleBackButton -Handles the back button in search mode. Android only. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -handled | bool | whether the back button is handled successfully - -```js -this._viewer.handleBackButton().then((handled) => { - if (!handled) { - BackHandler.exitApp(); - } -}); -``` - -### Bookmark - -#### importBookmarkJson -Imports user bookmarks into the document. The input needs to be a valid bookmark JSON format. - -Parameters: - -Name | Type | Description ---- | --- | --- -bookmarkJson | String | needs to be in valid bookmark JSON format, for example {"0": "Page 1"}. The page numbers are 1-indexed - -Returns a Promise. - -```js -this._viewer.importBookmarkJson("{\"0\": \"Page 1\", \"3\": \"Page 4\"}"); -``` - -#### openBookmarkList -Displays the bookmark tab of the existing list container. If this tab has been disabled, the method does nothing. - -Returns a Promise. - -```js -this._viewer.openBookmarkList(); -``` - -### Multi-tab - -#### closeAllTabs -Closes all tabs in a multi-tab environment. - -Returns a Promise. - -```js -// Do this only when DocumentView has multiTabEnabled = true -this._viewer.closeAllTabs(); -``` - -#### openTabSwitcher -Opens the tab switcher in a multi-tab environment. - -Returns a Promise. - -```js -// Do this only when DocumentView has multiTabEnabled = true -this._viewer.openTabSwitcher(); -``` - -### Zoom - -#### getZoom -Returns the current zoom scale of current document viewer. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -zoom | double | current zoom scale in the viewer - -```js -this._viewer.getZoom().then((zoom) => { - console.log('Zoom scale of the current document is:', zoom); -}); -``` - -#### setZoomLimits -Sets the minimum and maximum zoom bounds of current viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -zoomLimitMode | String | one of the constants in [`Config.ZoomLimitMode`](./src/Config/Config.ts), defines whether bounds are relative to the standard zoom scale in the current viewer or absolute -minimum | double | the lower bound of the zoom limit range -maximum | double | the upper bound of the zoom limit range - -Returns a Promise. - -```js -this._viewer.setZoomLimits(Config.ZoomLimitMode.Absolute, 1.0, 3.5); -``` - -#### zoomWithCenter -Sets the zoom scale in the current document viewer with a zoom center. - -Parameters: - -Name | Type | Description ---- | --- | --- -zoom | double | the zoom ratio to be set -x | int | the x-coordinate of the zoom center -y | int | the y-coordinate of the zoom center - -Returns a Promise. - -```js -this._viewer.zoomWithCenter(3.0, 100, 300); -``` - -#### zoomToRect -Zoom the viewer to a specific rectangular area in a page. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | int | the page number of the zooming area (1-indexed) -rect | map | The rectangular area with keys x1 (left), y1(bottom), y1(right), y2(top). Coordinates are in double - -Returns a Promise. - -```js -this._viewer.zoomToRect(3, {'x1': 1.0, 'y1': 2.0, 'x2': 3.0, 'y2': 4.0}); -``` - -#### smartZoom -Zoom to a paragraph that contains the specified coordinate. If no paragraph contains the coordinate, the zooming would not happen. - -Parameters: - -Name | Type | Description --- | -- | -- -x | int | the x-coordinate of the target coordinate -y | int | the y-coordinate of the target coordinate -animated | bool | whether the transition is animated - -Returns a Promise. - -```js -this._viewer.smartZoom(100, 200, true); -``` - -### Scroll - -#### getScrollPos -Returns the horizontal and vertical scroll position of current document viewer. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -horizontal | number | current horizontal scroll position -vertical | number | current vertical scroll position - -```js -this._viewer.getScrollPos().then(({horizontal, vertical}) => { - console.log('Current horizontal scroll position is:', horizontal); - console.log('Current vertical scroll position is:', vertical); -}); -``` - -### Reflow - -#### isReflowMode -Returns whether the viewer is currently in reflow mode. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -inReflow | bool | whether the viewer is in reflow mode - -```js -this._viewer.isReflowMode().then((inReflow) => { - console.log(inReflow ? 'in reflow mode' : 'not in reflow mode'); -}); -``` - -#### toggleReflow -Allows the user to programmatically enter and exit reflow mode. - -Returns a promise. - -```js -this._viewer.toggleReflow(); -``` - -### Canvas - -#### getCanvasSize -Returns the canvas size of current document viewer. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -width | number | current width of canvas -height | number | current height of canvas - -```js -this._viewer.getCanvasSize().then(({width, height}) => { - console.log('Current canvas width is:', width); - console.log('Current canvas height is:', height); -}); -``` - -### Coordinate - -#### convertPagePointsToScreenPoints -Converts points from page coordinates to screen coordinates in the viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -points | array | list of points, each in the format `{x: number, y: number}`. You could optionally have a `pageNumber: number` in the object. Without specifying, the page system is referring to the current page - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -convertedPoints | array | list of converted points in screen system, each in the format `{x: number, y: number}`. It would be empty if conversion is unsuccessful - -```js -// convert (50, 50) on current page and (100, 100) on page 1 from page system to screen system -this._viewer.convertPagePointsToScreenPoints([{x: 50, y: 50}, {x: 100, y:100, pageNumber: 1}]).then((convertedPoints) => { - convertedPoints.forEach(point => { - console.log(point); - }) -}); -``` - -#### convertScreenPointsToPagePoints -Converts points from screen coordinates to page coordinates in the viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -points | array | list of points, each in the format `{x: number, y: number}`. You could optionally have a `pageNumber: number` in the object. Without specifying, the page system is referring to the current page - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -convertedPoints | array | list of converted points in page system, each in the format `{x: number, y: number}`. It would be empty if conversion is unsuccessful - -```js -// convert (50, 50) and (100, 100) from screen system to page system, on current page and page 1 respectively -this._viewer.convertScreenPointsToPagePoints([{x: 50, y: 50}, {x: 100, y:100, pageNumber: 1}]).then((convertedPoints) => { - convertedPoints.forEach(point => { - console.log(point); - }) -}); -``` - -#### getPageNumberFromScreenPoint -Returns the page number that contains the point on screen. - -Parameters: - -Name | Type | Description ---- | --- | --- -x | number | the x-coordinate of the screen point -y | number | the y-coordinate of the screen point - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | number | the page number of the screen point - -```js -this._viewer.getPageNumberFromScreenPoint(10.0,50.5).then((pageNumber) => { - console.log('The page number of the screen point is', pageNumber); -}); -``` - -### Rendering Options - -#### setProgressiveRendering -Sets whether the control will render progressively or will just draw once the entire view has been rendered. - -Parameters: - -Name | Type | Description ---- | --- | --- -progressiveRendering | bool | whether to render progressively -initialDelay | number | delay before the progressive rendering timer is started, in milliseconds -interval | number | delay between refreshes, in milliseconds - -Returns a Promise. - -```js -// delay for 10s before start, and refresh every 1s -this._viewer.setProgressiveRendering(true, 10000, 1000); -``` - -#### setImageSmoothing -Enables or disables image smoothing. The rasterizer allows a trade-off between rendering quality and rendering speed. This function can be used to indicate the preference between rendering speed and quality. - -Parameters: - -Name | Type | Description ---- | --- | --- -imageSmoothing | bool | whether to enable image smoothing - -Returns a Promise. - -```js -this._viewer.setImageSmoothing(false); -``` - -#### setOverprint -Enables or disables support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc). - -Parameters: - -Name | Type | Description ---- | --- | --- -overprint | string | the mode of overprint, should be a [`Config.OverprintMode`](./src/Config/Config.ts) constant - -Returns a Promise. - -```js -this._viewer.setOverprint(Config.OverprintMode.Off); -``` - -### Viewer Options - -#### setPageBorderVisibility -Sets whether borders of each page are visible in the viewer, which is disabled by default. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageBorderVisibility | bool | whether borders of each page are visible in the viewer - -```js -this._viewer.setPageBorderVisibility(true); -``` - -#### setPageTransparencyGrid -Enables or disables transparency grid (check board pattern) to reflect page transparency, which is disabled by default. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageTransparencyGrid | bool | whether to use the transparency grid - -```js -this._viewer.setPageTransparencyGrid(true); -``` - -#### setBackgroundColor -Sets the background color of the viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -backgroundColor | object | the background color, in the format `{red: number, green: number, blue: number}`, each number in range [0, 255] - -```js -this._viewer.setBackgroundColor({red: 0, green: 0, blue: 255}); // blue color -``` - -#### setDefaultPageColor -Sets the default page color of the viewer. - -Parameters: - -Name | Type | Description ---- | --- | --- -defaultPageColor | object | the default page color, in the format `{red: number, green: number, blue: number}`, each number in range [0, 255] - -```js -this._viewer.setDefaultPageColor({red: 0, green: 255, blue: 0}); // green color -``` - -### Text Selection - -#### startSearchMode -Search for a term and all matching results will be highlighted. - -Returns a Promise. - -Parameters: - -Name | Type | Description ---- | --- | --- -searchString | string | the text to search for -matchCase | bool | indicates if it is case sensitive -matchWholeWord | bool | indicates if it matches an entire word only - -```js -this._viewer.startSearchMode('PDFTron', false, false); -``` - -#### exitSearchMode -Finishes the current text search and remove all the highlights. - -Returns a Promise. - -```js -this._viewer.exitSearchMode(); -``` - -#### findText -Searches asynchronously, starting from the current page, for the given text. PDFViewCtrl automatically scrolls to the position so that the found text is visible. - -Returns a Promise. - -Parameters: - -Name | Type | Description ---- | --- | --- -searchString | string | the text to search for -matchCase | bool | indicates if it is case sensitive -matchWholeWord | bool | indicates if it matches an entire word only -searchUp | bool | indicates if it searches upward -regExp | bool | indicates if searchString is a regular expression - -```js -this._viewer.findText('PDFTron', false, false, true, false); -``` - -#### cancelFindText -Cancels the current text search thread, if exists. - -Returns a Promise. - -```js -this._viewer.cancelFindText(); -``` - -#### openSearch -Displays a search bar that allows the user to enter and search text within a document. - -Returns a Promise. - -```js -this._viewer.openSearch(); -``` - -#### getSelection -Returns the text selection on a given page, if any. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | number | the specified page number. It is 1-indexed - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -selection | object | the text selection, in the format `{html: string, unicode: string, pageNumber: number, quads: [[{x: number, y: number}, {x: number, y: number}, {x: number, y: number}, {x: number, y: number}], ...]}`. If no such selection could be found, this would be null - -quads indicate the quad boundary boxes for the selection, which could have a size larger than 1 if selection spans across different lines. Each quad have 4 points with x, y coordinates specified in number, representing a boundary box. The 4 points are in counter-clockwise order, though the first point is not guaranteed to be on lower-left relatively to the box. - -```js -this._viewer.getSelection(2).then((selection) => { - if (selection) { - console.log('Found selection on page', selection.pageNumber); - for (let i = 0; i < selection.quads.length; i ++) { - const quad = selection.quads[i]; - console.log('selection boundary quad', i); - for (const quadPoint of quad) { - console.log('A quad point has coordinates', quadPoint.x, quadPoint.y); - } - } - } -}); -``` - -#### hasSelection -Returns whether there is a text selection in the current document. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -hasSelection | bool | whether a text selection exists - -```js -this._viewer.hasSelection().then((hasSelection) => { - console.log('There is a selection in the document.'); -}); -``` - -#### clearSelection -Clears any text selection in the current document. - -Returns a Promise. - -```js -this._viewer.clearSelection(); -``` - -#### getSelectionPageRange -Returns the page range (beginning and end) that has text selection on it. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -begin | number | the first page to have selection, -1 if there are no selections -end | number | the last page to have selection, -1 if there are no selections - -```js -this._viewer.getSelectionPageRange().then(({begin, end}) => { - if (begin === -1) { - console.log('There is no selection'); - } else { - console.log('The selection range is from', begin, 'to', end); - } -}); -``` - -#### hasSelectionOnPage -Returns whether there is a text selection on the specified page in the current document. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | number | the specified page number. It is 1-indexed - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -hasSelection | bool | whether a text selection exists on the specified page - -```js -this._viewer.hasSelectionOnPage(5).then((hasSelection) => { - if (hasSelection) { - console.log('There is a selection on page 5 in the document.'); - } -}); -``` - -#### selectInRect -Selects the text within the given rectangle region. - -Parameters: - -Name | Type | Description ---- | --- | --- -rect | object | the rectangle region in the format of `x1: number, x2: number, y1: number, y2: number` - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -selected | bool | whether there is text selected - -```js -this._viewer.selectInRect({x1: 0, y1: 0, x2: 200.5, y2: 200.5}).then((selected) => { - console.log(selected); -}); -``` - -#### isThereTextInRect -Returns whether there is text in given rectangle region. - -Parameters: - -Name | Type | Description ---- | --- | --- -rect | object | the rectangle region in the format of `x1: number, x2: number, y1: number, y2: number` - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -hasText | bool | whether there is text in the region - -```js -this._viewer.isThereTextInRect({x1: 0, y1: 0, x2: 200, y2: 200}).then((hasText) => { - console.log(hasText); -}); -``` - -#### selectAll -Selects all text on the page. - -Returns a Promise. - -```js -this._viewer.selectAll(); -``` - -### Undo/Redo - -#### undo -Undo the last modification. - -Returns a Promise. - -```js -this._viewer.undo(); -``` - -#### redo -Redo the last modification. - -Returns a Promise. - -```js -this._viewer.redo(); -``` - -#### canUndo -Checks whether an undo operation can be performed from the current snapshot. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -canUndo | bool | whether it is possible to undo from the current snapshot - -```js -this._viewer.canUndo().then((canUndo) => { - console.log(canUndo ? 'undo possible' : 'no action to undo'); -}); -``` - -#### canRedo -Checks whether a redo operation can be perfromed from the current snapshot. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -canRedo | bool | whether it is possible to redo from the current snapshot - -```js -this._viewer.canRedo().then((canRedo) => { - console.log(canRedo ? 'redo possible' : 'no action to redo'); -}); -``` - -### Signatures - -#### getSavedSignatures -Gets a list of absolute file paths to PDFs containing the saved signatures. - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -signatures | array | an array of string containing the absolute file paths; if there are no saved signatures, the value is an empty array - -```js -this._viewer.getSavedSignatures().then((signatures) => { - if (signatures.length > 0) { - signatures.forEach((signature) => { - console.log(signature); - }); - } -}) -``` - -#### getSavedSignatureFolder -Retrieves the absolute file path to the folder containing the saved signature PDFs. - -For Android, to get the folder containing the saved signature JPGs, use [`getSavedSignatureJpgFolder`](#getSavedSignatureJpgFolder). - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -path | string | the absolute file path to the folder - -```js -this._viewer.getSavedSignatureFolder().then((path) => { - if (path != null) { - console.log(path); - } -}) -``` - -#### getSavedSignatureJpgFolder -Retrieves the absolute file path to the folder containing the saved signature JPGs. Android only. - -To get the folder containing the saved signature PDFs, use [`getSavedSignatureFolder`](#getSavedSignatureFolder). - -Returns a Promise. - -Promise Parameters: - -Name | Type | Description ---- | --- | --- -path | string | the absolute file path to the folder - -```js -this._viewer.getSavedSignatureJpgFolder().then((path) => { - if (path != null) { - console.log(path); - } -}) -``` - -### Others - -#### exportAsImage -Export a PDF page to an image format defined in [`Config.ExportFormat`](./src/Config/Config.ts). - -Unlike RNPdftron.exportAsImage, this is a viewer method and should only be called *after* the document has been loaded or else unexpected behaviour can occur. This method uses the PDF that is associated with the viewer, and does not take a local file path to the desired PDF. - -Parameters: - -Name | Type | Description ---- | --- | --- -pageNumber | int | the page to be converted; if the value does not refer to a valid page number, the file path will be undefined -dpi | double | the output image resolution -exportFormat | string | one of the [`Config.ExportFormat`](./src/Config/Config.ts) constants - -Returns a Promise. - -Name | Type | Description ---- | --- | --- -path | string | the temp path of the created image, user is responsible for clean up the cache - -```js -this._viewer.exportToImage(1, 92, Config.ExportFormat.BMP).then((path) => { - console.log('export', path); -}); -``` - -#### showCrop -Displays the page crop option. Android only. - -Returns a Promise. - -```js -this._viewer.showCrop(); -``` - -#### openOutlineList -Displays the outline tab of the existing list container. If this tab has been disabled, the method does nothing. - -Returns a Promise. - -```js -this._viewer.openOutlineList(); -``` - -#### openLayersList -On Android it displays the layers dialog while on iOS it displays the layers tab of the existing list container. If this tab has been disabled or there are no layers in the document, the method does nothing. - -Returns a Promise. - -```js -this._viewer.openLayersList(); -``` - -#### openNavigationLists -Displays the existing list container. Its current tab will be the one last opened. - -Returns a Promise. - -```js -this._viewer.openNavigationLists(); -``` - -#### showViewSettings -Displays the view settings. - -Requires a source rect in screen co-ordinates. On iOS this rect will be the anchor point for the view. The rect is ignored on Android. - -Returns a Promise. - -Parameters: - -Name | Type | Description ---- | --- | --- -rect | map | The rectangular area in screen co-ordinates with keys x1 (left), y1(bottom), y1(right), y2(top). Coordinates are in double format. - -```js -this._viewer.showViewSettings({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}); -``` - -#### showAddPagesView -Displays the add pages view. - -Requires a source rect in screen co-ordinates. On iOS this rect will be the anchor point for the view. The rect is ignored on Android. - -Returns a Promise. - -Parameters: - -Name | Type | Description ---- | --- | --- -rect | map | The rectangular area in screen co-ordinates with keys x1 (left), y1(bottom), y1(right), y2(top). Coordinates are in double format. - -```js -this._viewer.showAddPagesView({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}); -``` - -#### shareCopy -Displays the share copy view. - -Requires a source rect in screen co-ordinates. On iOS this rect will be the anchor point for the view. The rect is ignored on Android. - -Returns a Promise. - -Parameters: - -Name | Type | Description ---- | --- | --- -rect | map | The rectangular area in screen co-ordinates with keys x1 (left), y1(bottom), y1(right), y2(top). Coordinates are in double format. -flattening | bool | Whether the shared copy should be flattened before sharing. - -```js -this._viewer.shareCopy({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}, true); -``` diff --git a/README.md b/README.md index 93be98c1c..171ee1788 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # PDFTron React Native Wrapper -- [API](API.md) +- [API](https://raw.githack.com/PDFTron/pdftron-react-native/ts-typedocs-master/docs/index.html) - [Prerequisites](#prerequisites) - [Preview](#preview) - [Installation](#installation) @@ -10,7 +10,7 @@ - [License](#license) ## API -APIs are available on the [API page](API.md). +APIs are available on the [API page](https://raw.githack.com/PDFTron/pdftron-react-native/ts-typedocs-master/docs/index.html). ## Prerequisites - No license key is required for trial. However, a valid commercial license key is required after trial. @@ -336,7 +336,7 @@ To get access to TypeScript support, simply update your PDFTron React Native dep For non-TypeScript users, updating your PDFTron React Native dependency to version 3.0.0 or higher will not automatically install TypeScript itself, and you can continue to use the library as before (without TypeScript support). If you currently do not use TypeScript itself in your project and would like to, see [Adding TypeScript to an Existing Project](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project). Regardless of whether you use TypeScript, the following benefits are available: -- Proper API typings which can be used in tools such as [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense). This offers insight into the data being passed without referring to the [API documentation](API.md). +- Proper API typings which can be used in tools such as [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense). This offers insight into the data being passed without referring to the [API documentation](https://raw.githack.com/PDFTron/pdftron-react-native/ts-typedocs-master/docs/index.html). - Greater type safety and reliability due to the migration of source files from JavaScript to TypeScript. - Updated Add an API guides for [Android](https://www.pdftron.com/documentation/android/get-started/react-native/add-an-api/) and [iOS](https://www.pdftron.com/documentation/ios/get-started/react-native/add-an-api) to offer step-by-step, TypeScript-supported examples on accessing properties, methods, and events. Contributors should be aware that PRs must now be made to the `dev` branch (see [Contributing](./CONTRIBUTING.md)). diff --git a/index.ts b/index.ts index c0f1a0a8b..8a752ccae 100644 --- a/index.ts +++ b/index.ts @@ -4,26 +4,186 @@ import { DocumentView } from './src/DocumentView/DocumentView'; import { Config } from './src/Config/Config'; import * as AnnotOptions from './src/AnnotOptions/AnnotOptions'; -interface RNPdftron { - initialize(licenseKey: string) : void; - enableJavaScript(enabled: boolean) : void; - getVersion() : Promise; - getPlatformVersion() : Promise; - getSystemFontList() : Promise; - clearRubberStampCache() : Promise; - encryptDocument(filePath: string, password: string, currentPassword: string) : Promise; - pdfFromOffice(docxPath: string, options?: {applyPageBreaksToSheet?: boolean, displayChangeTracking?: boolean, excelDefaultCellBorderWidth?: number, - excelMaxAllowedCellCount?: number, locale?: string}) : Promise; - pdfFromOfficeTemplate(docxPath: string, json: object) : Promise; - exportAsImage(pageNumber: number, dpi: number, exportFormat: Config.ExportFormat, filePath: string) : Promise; +/** + * @typedef RNPdftron + * @hidesource + * @desc RNPdftron contains static methods for global library initialization, configuration, and + * utility methods. + */ +interface RNPdftron +{ + /** + * @method + * @desc Initializes PDFTron SDK with your PDFTron commercial license key. + * You can run PDFTron in demo mode by passing an empty string. + * @param {string} licenseKey your PDFTron license key + * @example RNPdftron.initialize('your_license_key'); + */ + initialize(licenseKey: string) : void; + + /** + * @method + * @desc Enables JavaScript engine for PDFTron SDK, by default it is enabled. + * @param {boolean} enabled whether to enable or disable JavaScript engine + * @example RNPdftron.enableJavaScript(true); + */ + enableJavaScript(enabled: boolean) : void; + + /** + * @method + * @desc Gets the current PDFNet version. + * @returns {Promise} version - current PDFNet version + * @example + * RNPdftron.getVersion().then((version) => { + * console.log("Current PDFNet version:", version); + * }); + */ + getVersion() : Promise; + + /** + * @method + * @desc Gets the version of current platform (Android/iOS). + * @returns {Promise} platformVersion - current platform version (Android/iOS) + * @example + * RNPdftron.getPlatformVersion().then((platformVersion) => { + * console.log("App currently running on:", platformVersion); + * }); + */ + getPlatformVersion() : Promise; + + /** + * @method + * @desc Gets the font list available on the OS (Android only). + * This is typically useful when you are mostly working with non-ascii characters in the viewer. + * @returns {Promise} fontList - the font list available on Android + * @example + * RNPdftron.getSystemFontList().then((fontList) => { + * console.log("OS font list:", fontList); + * }); + */ + getSystemFontList() : Promise; + + /** + * @method + * @desc Clear the information and bitmap cache for rubber stamps (Android only). + * This is typically useful when the content of rubber stamps has been changed in the viewer. + * @example + * RNPdftron.clearRubberStampCache().then(() => { + * console.log("Rubber stamp cache cleared"); + * }); + */ + clearRubberStampCache() : Promise; + + /** + * @method + * @desc Encrypts (password-protect) a document (must be a PDF). + * + * **Note**: This function does not lock the document, + * it cannot be used while the document is opened in the viewer. + * @param {string} filePath the local file path to the file + * @param {string} password the password you would like to set + * @param {string} currentPassword the current password, use empty string if no password + * @example + * RNPdftron.encryptDocument("/sdcard/Download/new.pdf", "1111", "").then(() => { + * console.log("done password"); + * }); + */ + encryptDocument(filePath: string, password: string, currentPassword: string) : Promise; + + /** + * @method + * @desc Generates a PDF from an Office document + * @param {string} docxPath the local file path to the Office file. + * @param {boolean} [options.applyPageBreaksToSheet] Whether we should split Excel workheets into + * pages so that the output resembles print output. + * @param {boolean} [options.displayChangeTracking] If this option is true, will display office + * change tracking markup present in the document (i.e, red strikethrough of deleted + * content and underlining of new content). + * @param {double} [options.excelDefaultCellBorderWidth] Cell border width for table cells that + * would normally be drawn with no border. + * @param {int} [options.excelMaxAllowedCellCount] Conversion will throw an exception if the + * number of cells in a Microsoft Excel document is above the set MaxAllowedCellCount. + * @param {string} [options.locale] ISO 639-1 code of the current system locale. + * For example: 'en-US', 'ar-SA', 'de-DE', etc. + * @returns {Promise} resultPdfPath - the local file path to the generated PDF. + * The user is responsible for cleaning up the temporary file that is generated. + * @example + * // With options + * RNPdftron.pdfFromOffice("/sdcard/Download/red.xlsx", + * { + * applyPageBreaksToSheet: true, + * displayChangeTracking: true, + * excelDefaultCellBorderWidth: 1, + * excelMaxAllowedCellCount: 250000, + * locale: 'en-US' + * }) + * .then((resultPdfPath) => { + * console.log(resultPdfPath); + * }); + * + * // Without options + * RNPdftron.pdfFromOffice("/sdcard/Download/red.xlsx", null).then((resultPdfPath) => { + * console.log(resultPdfPath); + * }); + */ + pdfFromOffice(docxPath: string, options?: {applyPageBreaksToSheet?: boolean, + displayChangeTracking?: boolean, excelDefaultCellBorderWidth?: number, + excelMaxAllowedCellCount?: number, locale?: string}) : Promise + + /** + * @method + * @desc Generates a PDF using a template in the form of an Office document + * and replacement data in the form of a JSON object. + * For more information please see our + * [template guide](https://www.pdftron.com/documentation/core/guides/generate-via-template/). + * + * The user is responsible for cleaning up the temporary file that is generated. + * @param {string} docxPath the local file path to the template file + * @param {object} json the replacement data in the form of a JSON object + * @returns {Promise} resultPdfPath - the local file path to the generated PDF + * @example + * RNPdftron.pdfFromOfficeTemplate("/sdcard/Download/red.docx", json).then((resultPdfPath) => { + * console.log(resultPdfPath); + * }); + */ + pdfFromOfficeTemplate(docxPath: string, json: object) : Promise; + + /** + * @method + * @desc Export a PDF page to an image format defined in {@link Config.ExportFormat}. + * + * Unlike {@link DocumentView#exportAsImage DocumentView.exportAsImage}, + * this method is static and should only be called *before* a `DocumentView` + * instance has been created or else unexpected behaviour can occur. + * This method also takes a local file path to the desired PDF. + * @param {int} pageNumber the page to be converted; + * if the value does not refer to a valid page number, the file path will be undefined + * @param {double} dpi the output image resolution + * @param {Config.ExportFormat} exportFormat image format to be exported to + * @param {string} filePath local file path to pdf + * @returns {Promise} resultImagePath - the temp path of the created image, + * user is responsible for clean up the cache + * @example + * RNPdftron.exportAsImage(1, 92, Config.ExportFormat.BMP, "/sdcard/Download/red.pdf").then( + * (resultImagePath) => { + * console.log('export', resultImagePath); + * }); + */ + exportAsImage(pageNumber: number, dpi: number, + exportFormat: Config.ExportFormat, filePath: string) : Promise; } +/** + * @class + * @hideconstructor + */ +// eslint-disable-next-line no-redeclare const RNPdftron : RNPdftron = NativeModules.RNPdftron; export { - RNPdftron, - PDFViewCtrl, - DocumentView, - Config, - AnnotOptions, -}; \ No newline at end of file + RNPdftron, + PDFViewCtrl, + DocumentView, + Config, + AnnotOptions +}; diff --git a/lib/index.js b/lib/index.js index ebc135487..6287eeef3 100644 --- a/lib/index.js +++ b/lib/index.js @@ -3,5 +3,10 @@ import { PDFViewCtrl } from './src/PDFViewCtrl/PDFViewCtrl'; import { DocumentView } from './src/DocumentView/DocumentView'; import { Config } from './src/Config/Config'; import * as AnnotOptions from './src/AnnotOptions/AnnotOptions'; +/** + * @class + * @hideconstructor + */ +// eslint-disable-next-line no-redeclare const RNPdftron = NativeModules.RNPdftron; -export { RNPdftron, PDFViewCtrl, DocumentView, Config, AnnotOptions, }; +export { RNPdftron, PDFViewCtrl, DocumentView, Config, AnnotOptions }; diff --git a/lib/src/Config/Config.js b/lib/src/Config/Config.js index 73fad538d..ae59ceb9b 100644 --- a/lib/src/Config/Config.js +++ b/lib/src/Config/Config.js @@ -1,5 +1,20 @@ +/** + * @constant + * @class (Assigned to class for documentation purposes.) + * @hideconstructor + * @name Config + * @classdesc Defines configuration constants for the viewer. + * See [`Config.ts`](https://github.com/PDFTron/pdftron-react-native/blob/master/src/Config/Config.ts) + * for the full list of constants. + * + * Due to the length of the source file, we have included links to the exact lines + * of the source code where these APIs have been implemented. + */ export const Config = { - // Buttons define the various kinds of buttons for the viewer + /** + * @member + * @desc Buttons define the various kinds of buttons for the viewer + */ Buttons: { editToolButton: 'editToolButton', viewControlsButton: 'viewControlsButton', @@ -54,7 +69,10 @@ export const Config = { tabsButton: 'tabsButton', fileAttachmentButton: 'fileAttachmentButton', }, - // Tools define the various kinds of tools for the viewer + /** + * @member + * @desc Tools define the various kinds of tools for the viewer + */ Tools: { annotationEdit: 'AnnotationEdit', textSelect: 'TextSelect', @@ -101,14 +119,21 @@ export const Config = { // Android only. annotationCreateLinkText: 'AnnotationCreateLinkText', }, - // FitMode define how a page should fit relative to the viewer, alternatively, the default zoom level + /** + * @member + * @desc FitMode define how a page should fit relative to the viewer, + * alternatively, the default zoom level + */ FitMode: { FitPage: 'FitPage', FitWidth: 'FitWidth', FitHeight: 'FitHeight', Zoom: 'Zoom', }, - // LayoutMode defines the layout mode of the viewer + /** + * @member + * @desc LayoutMode defines the layout mode of the viewer + */ LayoutMode: { Single: 'Single', Continuous: 'Continuous', @@ -117,12 +142,18 @@ export const Config = { FacingCover: 'FacingCover', FacingCoverContinuous: 'FacingCoverContinuous', }, - // FieldFlags define the property flags for a form field + /** + * @member + * @desc FieldFlags define the property flags for a form field + */ FieldFlags: { ReadOnly: 0, Required: 1, }, - // AnnotationMenu defines the menu items when an annotation is selected + /** + * @member + * @desc AnnotationMenu defines the menu items when an annotation is selected + */ AnnotationMenu: { style: 'style', note: 'note', @@ -143,13 +174,19 @@ export const Config = { group: 'group', ungroup: 'ungroup', }, - // EraserType defines the type of eraser that will be used when eraser is selected + /** + * @member + * @desc EraserType defines the type of eraser that will be used when eraser is selected + */ EraserType: { annotationEraser: 'annotationEraser', hybrideEraser: 'hybrideEraser', inkEraser: 'inkEraser' }, - // LongPressMenu defines the menu items when a long press on empty space or text occurs + /** + * @member + * @desc LongPressMenu defines the menu items when a long press on empty space or text occurs + */ LongPressMenu: { copy: 'copy', paste: 'paste', @@ -157,12 +194,18 @@ export const Config = { share: 'share', read: 'read', }, - // Actions define potentially overridable action to the viewer + /** + * @member + * @desc Actions define potentially overridable action to the viewer + */ Actions: { linkPress: 'linkPress', stickyNoteShowPopUp: 'stickyNoteShowPopUp', }, - // AnnotationFlags define the flags for any annotation in the document + /** + * @member + * @desc AnnotationFlags define the flags for any annotation in the document + */ AnnotationFlags: { hidden: "hidden", invisible: "invisible", @@ -175,7 +218,10 @@ export const Config = { readOnly: "readOnly", toggleNoView: "toggleNoView" }, - // DefaultToolbars define a set of pre-designed toolbars for easier customization + /** + * @member + * @desc DefaultToolbars define a set of pre-designed toolbars for easier customization + */ DefaultToolbars: { View: "PDFTron_View", Annotate: "PDFTron_Annotate", @@ -188,7 +234,10 @@ export const Config = { Redaction: "PDFTron_Redact", Favorite: "PDFTron_Favorite" }, - // ToolbarIcons define default toolbar icons for use for potential custom toolbars + /** + * @member + * @desc ToolbarIcons define default toolbar icons for use for potential custom toolbars + */ ToolbarIcons: { View: "PDFTron_View", Annotate: "PDFTron_Annotate", @@ -201,72 +250,108 @@ export const Config = { Redaction: "PDFTron_Redact", Favorite: "PDFTron_Favorite" }, - // CustomToolbarKey defines the necessary keys for a custom toolbar + /** + * @member + * @desc CustomToolbarKey defines the necessary keys for a custom toolbar + */ CustomToolbarKey: { Id: "id", Name: "name", Icon: "icon", Items: "items" }, - // CustomToolItemKey defines the necessary keys for a custom tool inside a custom toolbar + /** + * @member + * @desc CustomToolItemKey defines the necessary keys for a custom tool inside a custom toolbar + */ CustomToolItemKey: { Id: "id", Name: "name", Icon: "icon" }, - // ThumbnailFilterMode defines filter modes in the thumbnails browser + /** + * @member + * @desc ThumbnailFilterMode defines filter modes in the thumbnails browser + */ ThumbnailFilterMode: { Annotated: "annotated", Bookmarked: "bookmarked", }, - // Conversion defines conversion sources and destinations + /** + * @member + * @desc Conversion defines conversion sources and destinations + */ Conversion: { Screen: "screen", Canvas: "canvas", Page: "page", }, - // ViewModePickerItem defines view mode items in the view mode dialog + /** + * @member + * @desc ViewModePickerItem defines view mode items in the view mode dialog + */ ViewModePickerItem: { Crop: "viewModeCrop", Rotation: "viewModeRotation", ColorMode: "viewModeColorMode", }, - // ZoomLimitMode defines the limit mode for zoom in the current document viewer + /** + * @member + * @desc ZoomLimitMode defines the limit mode for zoom in the current document viewer + */ ZoomLimitMode: { None: "none", Absolute: "absolute", Relative: "relative", }, - // OverprintMode defines when overprint would be applied in the viewer + /** + * @member + * @desc OverprintMode defines when overprint would be applied in the viewer + */ OverprintMode: { On: "on", Off: "off", OnlyPDFX: "pdfx", // only apply to PDF/X files }, - // ColorPostProcessMode defines color modifications after rendering in the viewer + /** + * @member + * @desc ColorPostProcessMode defines color modifications after rendering in the viewer + */ ColorPostProcessMode: { None: "none", Invert: "invert", GradientMap: "gradientMap", NightMode: "nightMode" }, - // ReflowOrientation defines the scrolling direction when in reflow viewing mode + /** + * @member + * @desc ReflowOrientation defines the scrolling direction when in reflow viewing mode + */ ReflowOrientation: { Horizontal: 'horizontal', Vertical: 'vertical', }, - // Export to format + /** + * @member + * @desc Export to format + */ ExportFormat: { BMP: "BMP", JPEG: "JPEG", PNG: "PNG", }, - // AnnotationManagerEditMode determines whose changes can be edited. + /** + * @member + * @desc AnnotationManagerEditMode determines whose changes can be edited. + */ AnnotationManagerEditMode: { Own: "own", All: "all", }, - // AnnotationManagerUndoMode determines whose changes can be undone. + /** + * @member + * @desc AnnotationManagerUndoMode determines whose changes can be undone. + */ AnnotationManagerUndoMode: { Own: "own", All: "all", diff --git a/lib/src/DocumentView/DocumentView.js b/lib/src/DocumentView/DocumentView.js index b80b9168d..ee1e7ad63 100644 --- a/lib/src/DocumentView/DocumentView.js +++ b/lib/src/DocumentView/DocumentView.js @@ -1,82 +1,1132 @@ import React, { PureComponent } from 'react'; import PropTypes from 'prop-types'; -import { requireNativeComponent, ViewPropTypes, Platform, Alert, NativeModules, findNodeHandle, } from 'react-native'; -const { DocumentViewManager } = NativeModules; +import { requireNativeComponent, ViewPropTypes, Platform, Alert, NativeModules, findNodeHandle } from 'react-native'; import { Config } from "../Config/Config"; +const { DocumentViewManager } = NativeModules; /** - * Object containing PropTypes types for {@link DocumentView} class. - * Also used to generate prop types for TS users. + * @desc This object outlines valid {@link DocumentView} class props. + * These can be passed into {@link DocumentView} to customize the viewer. + * + * For Contributors: The propTypes interface below contains PropTypes types for + * the {@link DocumentView} class. + * It is also used to generate custom types for TS users. * * To represent functions, please use {@link func}. * To represent "one of Config.Buttons values" or "an array of * Config.Buttons values", please use {@link oneOf} or {@link arrayOf}. + * + * @ignore */ -const propTypes = { +export const DocumentViewPropTypes = { + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @desc The path or url to the document. Required. + * @example + * + */ document: PropTypes.string.isRequired, + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @desc The password of the document, if any. + * @example + * + */ password: PropTypes.string, + /** + * @memberof DocumentView + * @category Page + * @type {number} + * @optional + * @desc Defines the initial page number that viewer displays when the document is opened. + * Note that page numbers are 1-indexed. + * @example + * + */ initialPageNumber: PropTypes.number, + /** + * @memberof DocumentView + * @category Page + * @type {number} + * @optional + * @desc Defines the currently displayed page number. + * Different from {@link DocumentView.initialPageNumber initialPageNumber}, + * changing this prop value at runtime will change the page accordingly. + * @example + * + */ pageNumber: PropTypes.number, + /** + * @memberof DocumentView + * @category Open a Document + * @type {object} + * @optional + * @desc Defines custom headers to use with HTTP/HTTPS requests. + * @example + * + */ customHeaders: PropTypes.object, + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @default The extension in the {@link DocumentView.document document} prop + * @desc Used for specifying the extension of the document to be loaded. + * @example + * + */ documentExtension: PropTypes.string, + /** + * @memberof DocumentView + * @category UI Customization + * @type {string} + * @optional + * @desc The file name of the icon to be used for the leading navigation button. + * The button will use the specified icon if it is valid, and the default icon otherwise. + * + * **Note**: to add the image file to your application, please follow the steps below: + * + * ##### Android + * 1. Add the image resource to the drawable directory in + * [`example/android/app/src/main/res`](https://github.com/PDFTron/pdftron-react-native/blob/master/example/android/app/src/main/res). + * For details about supported file types and potential compression, check out + * [here](https://developer.android.com/guide/topics/graphics/drawables#drawables-from-images). + * + * demo-android + *

+ * 2. Now you can use the image in the viewer. + * For example, if you add `button_close.png` to drawable, + * you could use `'button_close'` in leadingNavButtonIcon. + * + * ##### iOS + * 1. After pods has been installed, open the `.xcworkspace` file for this application in Xcode + * (in this case, it's [`example.xcworkspace`](https://github.com/PDFTron/pdftron-react-native/tree/master/example/ios/example.xcworkspace)), + * and navigate through the list below. + * This would allow you to add resources, in this case, an image, to your project. + * - "Project navigator" + * - "example" (or the app name) + * - "Build Phases" + * - "Copy Bundle Resources" + * - "+". + * + * demo-ios + *

+ * 2. Now you can use the image in the viewer. + * For example, if you add `button_open.png` to the bundle, + * you could use `'button_open.png'` in leadingNavButtonIcon. + * + * @example + * let iosNav = 'ic_close_black_24px.png'; + * let androidNav = 'ic_arrow_back_white_24dp'; + * + */ leadingNavButtonIcon: PropTypes.string, + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show the leading navigation button. + * @example + * + */ showLeadingNavButton: PropTypes.bool, + /** + * @memberof DocumentView + * @category UI Customization + * @event + * @type {function} + * @optional + * @desc This function is called when the leading navigation button is pressed. + * @example + * { + * console.log('The leading nav has been pressed'); + * }} + * /> + */ onLeadingNavButtonPressed: func(), + /** + * @memberof DocumentView + * @category Open a Document + * @event + * @type {function} + * @optional + * @desc This function is called when the document finishes loading. + * @param {string} path + * @example + * { + * console.log('The document has finished loading:', path); + * }} + * /> + */ onDocumentLoaded: func(), + /** + * @memberof DocumentView + * @category Open a Document + * @event + * @type {function} + * @optional + * @desc This function is called when document opening encounters an error. + * @param {string} error + * @example + * { + * console.log('Error occured during document opening:', error); + * }} + * /> + */ onDocumentError: func(), + /** + * @memberof DocumentView + * @category Page + * @event + * @type {function} + * @optional + * @desc This function is called when the page number has been changed. + * @param {int} previousPageNumber the previous page number + * @param {int} pageNumber the current page number + * @example + * { + * console.log('Page number changes from', previousPageNumber, 'to', pageNumber); + * }} + * /> + */ onPageChanged: func(), + /** + * @memberof DocumentView + * @category Scroll + * @event + * @type {function} + * @optional + * @desc This function is called when the scroll position has been changed. + * @param {number} horizontal the horizontal position of the scroll + * @param {number} vertical the vertical position of the scroll + * @example + * { + * console.log('Current scroll position is', horizontal, + * 'horizontally, and', vertical, 'vertically.'); + * }} + * /> + */ onScrollChanged: func(), + /** + * @memberof DocumentView + * @category Zoom + * @event + * @type {function} + * @optional + * @desc This function is called when the zoom scale has been changed. + * @param {double} zoom the current zoom ratio of the document + * @example + * { + * console.log('Current zoom ratio is', zoom); + * }} + * /> + */ onZoomChanged: func(), + /** + * @memberof DocumentView + * @category Zoom + * @event + * @type {function} + * @optional + * @desc This function is called when a zooming has been finished. + * For example, if zoom via gesture, this is called on gesture release. + * @param {double} zoom the current zoom ratio of the document + * @example + * { + * console.log('Current zoom ratio is', zoom); + * }} + * /> + */ onZoomFinished: func(), + /** + * @memberof DocumentView + * @category Zoom + * @type {number} + * @optional + * @desc Zoom factor used to display the page content. + * @example + * + */ zoom: PropTypes.number, + /** + * @memberof DocumentView + * @category UI Customization + * @type {Config.Buttons[]} + * @optional + * @default Defaults to none. + * @desc Defines buttons to be disabled for the viewer. + * @example + * + */ disabledElements: arrayOf(Config.Buttons), + /** + * @memberof DocumentView + * @category UI Customization + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines tools to be disabled for the viewer. + * @example + * + */ disabledTools: arrayOf(Config.Tools), + /** + * @memberof DocumentView + * @category Long Press Menu + * @type {Config.LongPressMenu[]} + * @optional + * @default Contains all the items. + * @desc Defines menu items that can show when long press on text or blank space. + * @example + * + */ longPressMenuItems: arrayOf(Config.LongPressMenu), + /** + * @memberof DocumentView + * @category Long Press Menu + * @type {Config.LongPressMenu[]} + * @optional + * @default Defaults to none. + * @desc Defines the menu items on long press that will skip default behavior when pressed. + * They will still be displayed in the long press menu, + * and the function {@link DocumentView.event:onLongPressMenuPress onLongPressMenuPress} + * will be called where custom behavior can be implemented. + * @example + * + */ overrideLongPressMenuBehavior: arrayOf(Config.LongPressMenu), + /** + * @memberof DocumentView + * @category Long Press Menu + * @event + * @type {function} + * @optional + * @desc This function is called if the pressed long press menu item is passed in to + * {@link DocumentView.overrideLongPressMenuBehavior overrideLongPressMenuBehavior}. + * @param {Config.LongPressMenu} longPressMenu the menu item that has been pressed. + * @param {string} longPressText the selected text if pressed on text, empty otherwise + * @example + * { + * console.log('Long press menu item', longPressMenu, 'has been pressed'); + * if (longPressText !== '') { + * console.log('The selected text is', longPressText); + * } + * }} + * /> + */ onLongPressMenuPress: func(), + /** + * @memberof DocumentView + * @category Long Press Menu + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show the popup menu of options + * when the user long presses on text or blank space on the document. + * @example + * + */ longPressMenuEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotation Menu + * @type {Config.AnnotationMenu[]} + * @optional + * @default Contains all the items. + * @desc Defines the menu items that can show when an annotation is selected. + * @example + * + */ annotationMenuItems: arrayOf(Config.AnnotationMenu), + /** + * @memberof DocumentView + * @category Annotation Menu + * @type {Config.AnnotationMenu[]} + * @optional + * @default Defaults to none. + * @desc Defines the menu items that will skip default behavior when pressed. + * They will still be displayed in the annotation menu, + * and the function {@link DocumentView.event:onAnnotationMenuPress onAnnotationMenuPress} + * will be called where custom behavior can be implemented. + * @example + * + */ overrideAnnotationMenuBehavior: arrayOf(Config.AnnotationMenu), + /** + * @memberof DocumentView + * @category Annotation Menu + * @event + * @type {function} + * @optional + * @desc This function is called when an annotation menu item passed in to + * {@link DocumentView.overrideAnnotationMenuBehavior overrideAnnotationMenuBehavior} is pressed. + * @param {Config.AnnotationMenu} annotationMenu the menu item that has been pressed. + * @param {object[]} annotations An array of + * `{id: string, pageNumber: number, type: string, screenRect: object, pageRect: object}` objects. + * + * `id` is the annotation identifier and `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * + * Both rects are represented with + * `{x1: number, y1: number, x2: number, y2: number, width: number, height: number}` objects. + * @example + * { + * console.log('Annotation menu item', annotationMenu, 'has been pressed'); + * annotations.forEach(annotation => { + * console.log('The id of selected annotation is', annotation.id); + * console.log('The page number of selected annotation is', annotation.pageNumber); + * console.log('The type of selected annotation is', annotation.type); + * console.log('The screenRect of selected annotation is', annotation.screenRect); + * console.log('The pageRect of selected annotation is', annotation.pageRect); + * }); + * }} + * /> + */ onAnnotationMenuPress: func(), + /** + * @memberof DocumentView + * @category Annotation Menu + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines annotation types that will not show in the annotation (long-press) menu. + * @example + * + */ hideAnnotationMenu: arrayOf(Config.Tools), + /** + * @memberof DocumentView + * @category Custom Behavior + * @type {Config.Actions[]} + * @optional + * @default Defaults to none. + * @desc Defines actions that will skip default behavior, such as external link click. + * The function {@link DocumentView.event:onBehaviorActivated onBehaviorActivated} will be + * called where custom behavior can be implemented, whenever the defined actions occur. + * @example + * + */ overrideBehavior: arrayOf(Config.Actions), + /** + * @memberof DocumentView + * @category Custom Behavior + * @event + * @type {function} + * @optional + * @desc This function is called if the activated behavior is passed in to + * {@link DocumentView.overrideBehavior overrideBehavior} + * @param {Config.Actions} action the action which has been activated. + * @param {object} data A JSON object that varies depending on the action. + * + * If action is `Config.Actions.linkPress`, data type is `{url: string}`. + * + * If action is `Config.Actions.stickyNoteShowPopUp`, data type is + * `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}` + * + * `type` is one of the {@link Config.Tools} constants, + * + * `screenRect` was formerly called `rect`. + * @example + * { + * console.log('Activated action is', action); + * if (action === Config.Actions.linkPress) { + * console.log('The external link pressed is', data.url); + * } else if (action === Config.Actions.stickyNoteShowPopUp) { + * console.log('Sticky note has been activated, but it would not show a pop up window.'); + * } + * }} + * /> + */ onBehaviorActivated: func(), + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default true + * @deprecated Use the {@link DocumentView.hideTopAppNavBar hideTopAppNavBar} prop instead. + */ topToolbarEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the bottom toolbar of the viewer is enabled. + * @example + * + */ bottomToolbarEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether an unhandled tap in the viewer should toggle the visibility + * of the top and bottom toolbars. When false, the top and bottom toolbar visibility + * will not be toggled and the page content will fit between the bars, if any. + * @example + * + */ hideToolbarsOnTap: PropTypes.bool, + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the document slider of the viewer is enabled. + * @example + * + */ documentSliderEnabled: PropTypes.bool, - downloadDialogEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Page + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show the page indicator for the viewer. + * @example + * + */ pageIndicatorEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether the download dialog should be shown. + * @example + * + */ + downloadDialogEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Page + * @type {boolean} + * @optional + * @default true + * @desc iOS only + * + * Defines whether the keyboard shortcuts of the viewer are enabled. + * @example + * + */ keyboardShortcutsEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called when an annotation(s) is selected. + * @param {object[]} annotations array of annotation data in the format + * `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`, + * representing the selected annotations. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * { + * annotations.forEach(annotation => { + * console.log('The id of selected annotation is', annotation.id); + * console.log('It is in page', annotation.pageNumber); + * console.log('Its type is', annotation.type); + * }); + * }} + * /> + */ onAnnotationsSelected: func(), + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to an annotation(s) + * in the current document. + * + * Note: When an annotation is flattened, it also gets deleted, so both + * {@link DocumentView.event:onAnnotationChanged onAnnotationChanged} and + * {@link DocumentView.event:onAnnotationFlattened onAnnotationFlattened} are called. + * + * @param {string} action the action that occurred (add, delete, modify) + * @param {object[]} annotations array of annotation data in the format + * `{id: string, pageNumber: number, type: string}`, + * representing the annotations that have been changed. + * + * `type` is one of the {@link Config.Tools} constants + * @example + * { + * console.log('Annotation edit action is', action); + * annotations.forEach(annotation => { + * console.log('The id of changed annotation is', annotation.id); + * console.log('It is in page', annotation.pageNumber); + * console.log('Its type is', annotation.type); + * }); + * }} + * /> + */ onAnnotationChanged: func(), - onAnnotationFlattened: func(), + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to form field values. + * @param {object[]} fields array of field data in the format + * `{fieldName: string, fieldType: string, fieldValue: any}`, + * representing the fields that have been changed + * @example + * { + * fields.forEach(field => { + * console.log('The name of the changed field is', field.fieldName); + * console.log('The type of the changed field is', field.fieldType); + * console.log('The value of the changed field is', field.fieldValue); + * }); + * }} + * /> + */ onFormFieldValueChanged: func(), - onAnnotationToolbarItemPress: func(), + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if an annotation(s) has been flattened in the + * current document. + * @param {object[]} annotations array of annotation data in the format + * `{id: string, pageNumber: number, type: string}`, + * representing the annotations that have been changed. + * + * `type` is one of the {@link Config.Tools} constants + * + * `id` returned via the event listener can be null. + * @example + * { + annotations.forEach(annotation => { + console.log('The id of changed annotation is', annotation.id); + console.log('It is in page', annotation.pageNumber); + console.log('Its type is', annotation.type); + }); + }} + * /> + */ + onAnnotationFlattened: func(), + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default false + * @desc Defines whether the viewer is read-only. + * If true, the UI will not allow the user to change the document. + * @example + * + */ readOnly: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called when a custom toolbar tool item is clicked + * @param {string} id the Config.CustomToolItemKey.Id defined in the tool + * @example + * { + * console.log('toolbar item press: ' + id); + * }} + * /> + */ + onAnnotationToolbarItemPress: func(), + /** + * @memberof DocumentView + * @category Thumbnails + * @type {boolean} + * @optional + * @default true + * @desc Defines whether user can modify the document + * using the thumbnail view (eg add/remove/rotate pages). + * @example + * + */ thumbnailViewEditingEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Layout + * @type {Config.FitMode} + * @optional + * @default Config.FitMode.FitWidth + * @desc Defines the fit mode (default zoom level) of the viewer. + * @example + * + */ fitMode: oneOf(Config.FitMode), + /** + * @memberof DocumentView + * @category Layout + * @type {Config.LayoutMode} + * @optional + * @default Config.LayoutMode.Continuous + * @desc Defines the layout mode of the viewer. + * @example + * + */ layoutMode: oneOf(Config.LayoutMode), + /** + * @memberof DocumentView + * @category Layout + * @event + * @type {function} + * @optional + * @desc This function is called when the layout of the viewer has been changed. + * @example + * { + * console.log('Layout has been updated.'); + * }} + * /> + */ onLayoutChanged: func(), + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Android only + * + * Defines whether the viewer will add padding to take account of the system status bar. + * @example + * + */ padStatusBar: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc If true, the active annotation creation tool will remain in the current annotation + * creation tool. Otherwise, it will revert to the "pan tool" after an annotation is created. + * @example + * + */ continuousAnnotationEditing: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc Defines whether an annotation is selected after it is created. + * On iOS, this functions for shape and text markup annotations only. + * @example + * + */ selectAnnotationAfterCreation: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @type {string} + * @optional + * @desc Defines the author name for all annotations created on the current document. + * Exported xfdfCommand will include this piece of information. + * @example + * + */ annotationAuthor: PropTypes.string, + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show saved signatures for re-use when using the signing tool. + * @example + * + */ showSavedSignatures: PropTypes.bool, + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default true + * @desc iOS only + * + * Defines whether to store new signatures when using the signing tool. + * @example + * + */ storeNewSignature: PropTypes.bool, + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default false + * @desc If true, {@link DocumentView.document document} prop will be treated as a base64 string. + * If it is not the base64 string of a pdf file, + * {@link DocumentView.base64FileExtension base64FileExtension} is required. + * + * When viewing a document initialized with a base64 string (i.e. a memory buffer), + * a temporary file is created on Android and iOS. + * @example + * + */ isBase64String: PropTypes.bool, + /** + * @memberof DocumentView + * @category Collaboration + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to enable realtime collaboration. + * If true then {@link DocumentView.currentUser currentUser} must be set as well for + * collaboration mode to work. Feature set may vary between local and collaboration mode. + * @example + * + */ collabEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Collaboration + * @type {string} + * @desc Required if {@link DocumentView.collabEnabled collabEnabled} is set to true. + * + * Defines the current user. + * Created annotations will have their title (author) set to this string. + * @example + * + */ currentUser: PropTypes.string, + /** + * @memberof DocumentView + * @category Collaboration + * @type {string} + * @optional + * @desc Defines the current user name. + * Will set the user name only if {@link DocumentView.collabEnabled collabEnabled} is true + * and {@link DocumentView.currentUser currentUser} is defined. This should be used only if + * you want the user's display name to be different than the annotation's title/author + * (in the case that {@link DocumentView.currentUser currentUser} is an ID rather than a + * human-friendly name.) + * @example + * + */ currentUserName: PropTypes.string, + /** + * @memberof DocumentView + * @category Import/Export Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to annotations in the current document. + * Unlike {@link DocumentView.event:onAnnotationChanged onAnnotationChanged}, this function has + * an XFDF command string as its parameter. If you are modifying or deleting multiple annotations, + * then on Android the function is only called once, and on iOS it is called for each annotation. + * + * **Known Issues** + * + * On iOS, there is currently a bug that prevents the last XFDF from being retrieved when + * modifying annotations while collaboration mode is enabled. + * @param {string} action the action that occurred (add, delete, modify) + * @param {string} xfdfCommand an xfdf string containing info about the edit + * @param {array} annotations an array of annotation data. + * When collaboration is enabled data comes in the format `{id: string}`, otherwise the format is + * `{id: string, pageNumber: number, type: string}`. + * In both cases, the data represents the annotations that have been changed. + * + * `type` is one of the {@link Config.Tools} constants. + * @example + * { + * console.log('Annotation edit action is', action); + * console.log('The exported xfdfCommand is', xfdfCommand); + * annotations.forEach((annotation) => { + * console.log('Annotation id is', annotation.id); + * if (!this.state.collabEnabled) { + * console.log('Annotation pageNumber is', annotation.pageNumber); + * console.log('Annotation type is', annotation.type); + * } + * }); + * }} + * collabEnabled={this.state.collabEnabled} + * currentUser={'Pdftron'} + * /> + */ onExportAnnotationCommand: func(), + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default true + * @desc Defines whether document is automatically saved by the viewer. + * @example + * + */ autoSaveEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Page + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the viewer should change pages when the user taps the edge of a page, + * when the viewer is in a horizontal viewing mode. + * @example + * + */ pageChangeOnTap: PropTypes.bool, + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default true + * @desc Android and iOS 13+ only + * + * Defines whether the UI will appear in a dark color when the system is dark mode. + * If false, it will use viewer setting instead. + * @example + * + */ followSystemDarkMode: PropTypes.bool, + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default true + * @desc Defines whether a stylus should act as a pen when in pan mode. + * If false, it will act as a finger. + * @example + * + */ useStylusAsPen: PropTypes.bool, + /** + * @memberof DocumentView + * @category Multi-tab + * @type {boolean} + * @optional + * @default false + * @desc Defines whether viewer will use tabs in order to have more than + * one document open simultaneously (like a web browser). Changing the + * {@link DocumentView.document document} prop value will cause a new tab + * to be opened with the associated file. + * @example + * + */ multiTabEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Multi-tab + * @type {string} + * @optional + * @default the file name + * @desc Set the tab title if {@link DocumentView.multiTabEnabled multiTabEnabled} is true. + * @example + * + */ tabTitle: PropTypes.string, + /** + * @memberof DocumentView + * @category Multi-tab + * @type {number} + * @optional + * @default unlimited + * @desc Sets the limit on the maximum number of tabs that the viewer could have at a time. + * Open more documents after reaching this limit will overwrite the old tabs. + * @example + * + */ maxTabCount: PropTypes.number, + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default false + * @desc + * Defines whether signature fields will be signed with image stamps. + * This is useful if you are saving XFDF to remote source. + * @example + * + */ signSignatureFieldsWithStamps: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default false + * @desc Defines whether an annotation's permission flags will be respected when it is selected. + * For example, a locked annotation can not be resized or moved. + * @example + * + */ annotationPermissionCheckEnabled: PropTypes.bool, + /** + * @type {Config.DefaultToolbars[]|object} + * @category Toolbar Customization + * @memberof DocumentView + * @optional + * @default Defaults to none. + * @desc Type can be array of {@link Config.DefaultToolbars} constants or custom toolbar objects. + * + * Defines custom toolbars. If passed in, the default toolbars will no longer appear. + * It is possible to mix and match with default toolbars. See example below. + * @example + * const myToolbar = { + * [Config.CustomToolbarKey.Id]: 'myToolbar', + * [Config.CustomToolbarKey.Name]: 'myToolbar', + * [Config.CustomToolbarKey.Icon]: Config.ToolbarIcons.FillAndSign, + * [Config.CustomToolbarKey.Items]: [Config.Tools.annotationCreateArrow, + * Config.Tools.annotationCreateCallout, Config.Buttons.undo] + * }; + * ... + * + */ annotationToolbars: PropTypes.arrayOf(PropTypes.oneOfType([ oneOf(Config.DefaultToolbars), PropTypes.exact({ @@ -93,49 +1143,708 @@ const propTypes = { ])) }) ])), + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {Config.DefaultToolbars[]} + * @optional + * @default Defaults to none. + * @desc Defines which default annotation toolbars should be hidden. + * Note that this prop should be used when + * {@link DocumentView.annotationToolbars annotationToolbars} is not defined. + * @example + * + */ hideDefaultAnnotationToolbars: arrayOf(Config.DefaultToolbars), + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {Config.Buttons[]} + * @optional + * @desc iOS only + * + * Customizes the right bar section of the top app nav bar. + * If passed in, the default right bar section will not be used. + * @example + * + */ topAppNavBarRightBar: arrayOf(Config.Buttons), + /** + * @memberof DocumentView + * @type {Config.Buttons[]} + * @category Toolbar Customization + * @optional + * @desc Only the outline list, thumbnail list, share, view mode, + * search, and reflow buttons are supported on Android. + * + * Defines a custom bottom toolbar. If passed in, the default bottom toolbar will not be used. + * @example + * + */ bottomToolbar: arrayOf(Config.Buttons), + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to show the toolbar switcher in the top toolbar. + * @example + * + */ hideAnnotationToolbarSwitcher: PropTypes.bool, + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to hide both the top app nav bar and the annotation toolbar. + * @example + * + */ hideTopToolbars: PropTypes.bool, + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to hide the top navigation app bar. + * @example + * + */ hideTopAppNavBar: PropTypes.bool, + /** + * @memberof DocumentView + * @category Bookmark + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to user bookmarks. + * @param {string} bookmarkJson the list of current bookmarks in JSON format + * @example + * { + * console.log('Bookmarks have been changed. Current bookmark collection is', bookmarkJson); + * }} + * /> + */ onBookmarkChanged: func(), + /** + * @memberof DocumentView + * @category Thumbnails + * @type {Config.ThumbnailFilterMode[]} + * @optional + * @desc Defines filter modes that should be hidden in the thumbnails browser. + * @example + * + */ hideThumbnailFilterModes: arrayOf(Config.ThumbnailFilterMode), + /** + * @memberof DocumentView + * @category UI Customization + * @event + * @type {function} + * @optional + * @desc This function is called when the current tool changes to a new tool + * @param {Config.Tools|string} previousTool the previous tool + * (one of the {@link Config.Tools} constants or "unknown tool"), + * representing the tool before change + * @param {Config.Tools|string} tool the current tool (one of the {@link Config.Tools} constants + * or "unknown tool"), representing the current tool + * @example + * { + * console.log('Tool has been changed from', previousTool, 'to', tool); + * }} + * /> + */ onToolChanged: func(), + /** + * @memberof DocumentView + * @category Scroll + * @type {number} + * @optional + * @desc Defines the horizontal scroll position in the current document viewer. + * @example + * + */ horizontalScrollPos: PropTypes.number, + /** + * @memberof DocumentView + * @category Scroll + * @type {number} + * @optional + * @desc Defines the vertical scroll position in the current document viewer. + * @example + * + */ verticalScrollPos: PropTypes.number, + /** + * @memberof DocumentView + * @category Text Selection + * @event + * @type {function} + * @optional + * @desc This function is called immediately before a text search begins, + * either through user actions, or function calls such as {@link DocumentView#findText findText}. + * @example + * { + * console.log('Text search has started'); + * }} + * /> + */ onTextSearchStart: func(), + /** + * @memberof DocumentView + * @category Text Selection + * @event + * @type {function} + * @optional + * @desc This function is called after a text search is finished or canceled. + * @param {boolean} found whether a result is found. + * If false, it could be caused by not finding a matching result in the document, + * invalid text input, or action cancellation + * (user actions or {@link DocumentView#cancelFindText cancelFindText}) + * @param {object} textSelection the text selection, in the format + * `{html: string, unicode: string, pageNumber: number, + * quads: [[{x: number, y: number}, {x: number, y: number}, {x: number, y: number}, + * {x: number, y: number}], ...]}`. If no such selection could be found, this would be null + * + * Quads indicate the quad boundary boxes for the selection, + * which could have a size larger than 1 if selection spans across different lines. + * Each quad have 4 points with x, y coordinates specified in number, representing a boundary box. + * The 4 points are in counter-clockwise order, though the first point is not guaranteed to be on + * lower-left relatively to the box. + * @example + * { + * if (found) { + * console.log('Found selection on page', textSelection.pageNumber); + * for (let i = 0; i < textSelection.quads.length; i ++) { + * const quad = textSelection.quads[i]; + * console.log('selection boundary quad', i); + * for (const quadPoint of quad) { + * console.log('A quad point has coordinates', quadPoint.x, quadPoint.y); + * } + * } + * } + * }} + * /> + */ onTextSearchResult: func(), + /** + * @memberof DocumentView + * @category UI Customization + * @type {Config.ViewModePickerItem[]} + * @optional + * @default Defaults to none. + * @desc Defines view mode items to be hidden in the view mode dialog. + * @example + * + */ hideViewModeItems: arrayOf(Config.ViewModePickerItem), + /** + * @memberof DocumentView + * @category Navigation + * @type {boolean} + * @optional + * @default true + * @deprecated Use the {@link DocumentView.showQuickNavigationButton showQuickNavigationButton} + * prop instead. + * @desc Android only. + * + * Defines whether the page stack navigation buttons will appear in the viewer. + * @example + * + */ pageStackEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Navigation + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the quick navigation buttons will appear in the viewer. + * @example + * + */ showQuickNavigationButton: PropTypes.bool, + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default true. + * @desc Android only. + * + * Defines whether to show the option to pick images in the signature dialog. + * @example + * + */ photoPickerEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to automatically resize the bounding box of free + * text annotations when editing. + * @example + * + */ autoResizeFreeTextEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc If document editing is enabled, then this value determines + * if the annotation list is editable. + * @example + * + */ annotationsListEditingEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Navigation + * @type {boolean} + * @optional + * @default true on Android and false on iOS + * @desc Defines whether the navigation list will be displayed as a side panel + * on large devices such as iPads and tablets. + * @example + * + */ showNavigationListAsSidePanelOnLargeDevices: PropTypes.bool, + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to restrict data usage when viewing online PDFs. + * @example + * + */ restrictDownloadUsage: PropTypes.bool, + /** + * @memberof DocumentView + * @category Bookmark + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the bookmark list can be edited. + * If the viewer is readonly then bookmarks on Android are + * still editable but are saved to the device rather than the PDF. + * @example + * + */ userBookmarksListEditingEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Reflow + * @type {boolean} + * @optional + * @default true + * @desc Will be available on iOS in version 9.1.2 and greater + * + * Whether to show images in reflow mode. + * @example + * + */ imageInReflowEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Reflow + * @type {Config.ReflowOrientation} + * @optional + * @default Defaults to the viewer's scroll direction + * @desc Android only. + * + * Sets the scrolling direction of the reflow control. + * @example + * + */ reflowOrientation: oneOf(Config.ReflowOrientation), + /** + * @memberof DocumentView + * @category Undo/Redo + * @event + * @type {function} + * @optional + * @desc This function is called when the state of the current document's + * undo/redo stack has been changed. + * @example + * { + * console.log("Undo/redo stack state changed"); + * }} + * /> + */ onUndoRedoStateChanged: func(), + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether the tablet layout should be used on tablets. + * Otherwise uses the same layout as phones. + * @example + * + */ tabletLayoutEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {Config.DefaultToolbars|string} + * @optional + * @default Defaults to none. + * @desc Type can be one of the {@link Config.DefaultToolbars} constants + * or the `id` of a custom toolbar object. + * + * Defines which {@link DocumentView.annotationToolbars annotationToolbar} + * should be selected when the document is opened. + * @example + * + */ initialToolbar: PropTypes.string, + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc If true, ink tool will use multi-stroke mode. + * Otherwise, each stroke is a new ink annotation. + * @example + * + */ inkMultiStrokeEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Open a Document + * @type {Config.EraserType} + * @optional + * @desc Sets the default eraser tool type. Value only applied after a clean + * install. + * Eraser Type | Description + * --- | --- + * `annotationEraser` | Erases everything as an object; if you touch ink, + * the entire object is erased. + * `hybrideEraser` | Erases ink by pixel, but erases other annotation types as objects. + * `inkEraser` | Erases ink by pixel only. Android only. + * @example + * + */ defaultEraserType: oneOf(Config.EraserType), + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @desc Android only. + * + * Sets the folder path for all save options, this defaults to the app cache path. + * Example: + * @example + * + */ exportPath: PropTypes.string, + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @desc Android only. + * + * Sets the cache folder used to cache PDF files opened using a http/https link, + * this defaults to the app cache path. + * @example + * + */ openUrlPath: PropTypes.string, + /** + * @memberof DocumentView + * @category Annotations + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines annotation types that cannot be edited after creation. + * @example + * + */ disableEditingByAnnotationType: arrayOf(Config.Tools), + /** + * @memberof DocumentView + * @category Scroll + * @type {boolean} + * @optional + * @default false + * @desc iOS only. + * + * Determines whether scrollbars will be hidden on the viewer. + * @example + * + */ hideScrollbars: PropTypes.bool, + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default true + * @desc Sets whether to remember the last visited page and zoom for a + * document if it gets opened again. + * @example + * + */ saveStateEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Sets whether the new saved file should open after saving. + * @example + * + */ openSavedCopyInNewTab: PropTypes.bool, + /** + * @memberof DocumentView + * @category Annotations + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines types to be excluded from the annotation list. + * @example + * + */ excludedAnnotationListTypes: arrayOf(Config.Tools), + /** + * @memberof DocumentView + * @category Collaboration + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether to show an annotation's reply review state. + * @example + * + */ + replyReviewStateEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Collaboration + * @type {Config.AnnotationManagerEditMode} + * @optional + * @default Config.AnnotationManagerEditMode.Own + * @desc Sets annotation manager edit mode when {@link DocumentView.collabEnabled collabEnabled} + * is true. + * + * Mode | Description + * --- | --- + * `Config.AnnotationManagerEditMode.Own` | In this mode, you can edit only your own changes + * `Config.AnnotationManagerEditMode.All` | In this mode, you can edit everyone's changes + * @example + * + */ annotationManagerEditMode: oneOf(Config.AnnotationManagerEditMode), + /** + * @memberof DocumentView + * @category Collaboration + * @type {Config.AnnotationManagerUndoMode} + * @optional + * @default Config.AnnotationManagerUndoMode.Own + * @desc Sets annotation manager undo mode when {@link DocumentView.collabEnabled collabEnabled} + * is true. + * + * Mode | Description + * --- | --- + * `Config.AnnotationManagerUndoMode.Own` | In this mode, you can undo only your own changes + * `Config.AnnotationManagerUndoMode.All` | In this mode, you can undo everyone's changes + * @example + * + */ annotationManagerUndoMode: oneOf(Config.AnnotationManagerUndoMode), - replyReviewStateEnabled: PropTypes.bool, + /** + * @memberof DocumentView + * @category Page + * @event + * @type {function} + * @optional + * @desc This function is called when a page has been moved in the document. + * @param {int} previousPageNumber the previous page number + * @param {int} pageNumber the current page number + * @example + * { + * console.log('Page moved from', previousPageNumber, 'to', pageNumber); + * }} + * /> + */ onPageMoved: func(), + /** + * @memberof DocumentView + * @category Page + * @event + * @type {function} + * @optional + * @desc This function is called when pages are added to the document. + * @param {int} pageNumbers An array of the page numbers that were added to the document + * @example + * { + * console.log('Pages added:', pageNumbers); + * }} + * /> + */ onPagesAdded: func(), + /** + * @memberof DocumentView + * @category Multi-tab + * @event + * @type {function} + * @optional + * @desc The function is activated when a tab is changed. + * + * This API is meant for tab-specific changes. + * If you would like to know when the document finishes loading instead, see + * the {@link DocumentView.event:onDocumentLoaded onDocumentLoaded} event. + * @param {string} currentTab The file path of current tab's document + * @example + * { + * console.log("The current tab is ", currentTab); + * }} + * /> + */ onTabChanged: func(), + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether the last tool used in the current viewer session will + * be the tool selected upon starting a new viewer session. + * @example + * + */ rememberLastUsedTool: PropTypes.bool, + /** + * @memberof DocumentView + * @category UI Customization + * @type {string} + * @optional + * @desc The file name of the icon to be used as the overflow menu button. + * The button will use the specified icon if it is valid, and the default icon otherwise. + * + * **Note**: to add the image file to your application, follow the steps under the Note + * section of {@link DocumentView.leadingNavButtonIcon leadingNavButtonIcon}. + * @example + * let iosButton = 'ic_close_black_24px.png'; + * let androidButton = 'ic_arrow_back_white_24dp'; + * + */ overflowMenuButtonIcon: PropTypes.string, ...ViewPropTypes, }; @@ -147,11 +1856,13 @@ const propTypes = { * @returns {Requireable} A custom PropType constant. * @example * func<(path: string) => void>() +* @ignore */ function func() { - let validator = function (props, propName, componentName, location, propFullName) { + const validator = function (props, propName, componentName, location, propFullName) { if (typeof props[propName] !== "function" && typeof props[propName] !== "undefined") { - return new Error(`Invalid prop \`${propName}\` of type \`${typeof props[propName]}\` supplied to \`${componentName}\`, expected a function.`); + return new Error(`Invalid prop \`${propName}\` of type \`${typeof props[propName]}\` + supplied to \`${componentName}\`, expected a function.`); } return null; }; @@ -167,7 +1878,8 @@ function func() { * @example * oneOf(Config.Tools) * oneOf(Config.Tools, Config.Buttons) -*/ + * @ignore + */ function oneOf(obj, ...rest) { if (rest.length > 0) { return PropTypes.oneOf(Object.values(Object.assign({}, obj, ...rest))); @@ -182,13 +1894,23 @@ function oneOf(obj, ...rest) { * @example * arrayOf(Config.Tools) * arrayOf(Config.Tools, Config.Buttons) + * @ignore */ function arrayOf(obj, ...rest) { return PropTypes.arrayOf(oneOf(obj, ...rest)); } +/** + * @class + * @classdesc An all-in-one React component for displaying and editing documents of different types + * such as PDF, docx, pptx, xlsx and various image formats. + * + * Due to the length of the source file, we have included links to the exact lines of the source + * code where these APIs have been implemented. + * @hideconstructor + */ export class DocumentView extends PureComponent { _viewerRef; - static propTypes = propTypes; + static propTypes = Object.assign(DocumentViewPropTypes, { ...ViewPropTypes }); onChange = (event) => { if (event.nativeEvent.onLeadingNavButtonPressed) { if (this.props.onLeadingNavButtonPressed) { @@ -212,21 +1934,21 @@ export class DocumentView extends PureComponent { if (this.props.onScrollChanged) { this.props.onScrollChanged({ 'horizontal': event.nativeEvent.horizontal, - 'vertical': event.nativeEvent.vertical, + 'vertical': event.nativeEvent.vertical }); } } else if (event.nativeEvent.onZoomChanged) { if (this.props.onZoomChanged) { this.props.onZoomChanged({ - 'zoom': event.nativeEvent.zoom, + 'zoom': event.nativeEvent.zoom }); } } else if (event.nativeEvent.onZoomFinished) { if (this.props.onZoomFinished) { this.props.onZoomFinished({ - 'zoom': event.nativeEvent.zoom, + 'zoom': event.nativeEvent.zoom }); } } @@ -276,7 +1998,8 @@ export class DocumentView extends PureComponent { this.props.onDocumentError(event.nativeEvent.onDocumentError); } else { - const msg = event.nativeEvent.onDocumentError ? event.nativeEvent.onDocumentError : 'Unknown error'; + const error = 'Unknown error'; + const msg = event.nativeEvent.onDocumentError ? event.nativeEvent.onDocumentError : error; Alert.alert('Alert', msg, [ { text: 'OK' } ], { cancelable: true }); @@ -311,14 +2034,14 @@ export class DocumentView extends PureComponent { if (this.props.onBehaviorActivated) { this.props.onBehaviorActivated({ 'action': event.nativeEvent.action, - 'data': event.nativeEvent.data, + 'data': event.nativeEvent.data }); } } else if (event.nativeEvent.onBookmarkChanged) { if (this.props.onBookmarkChanged) { this.props.onBookmarkChanged({ - 'bookmarkJson': event.nativeEvent.bookmarkJson, + 'bookmarkJson': event.nativeEvent.bookmarkJson }); } } @@ -326,7 +2049,7 @@ export class DocumentView extends PureComponent { if (this.props.onToolChanged) { this.props.onToolChanged({ 'previousTool': event.nativeEvent.previousTool, - 'tool': event.nativeEvent.tool, + 'tool': event.nativeEvent.tool }); } } @@ -339,7 +2062,7 @@ export class DocumentView extends PureComponent { if (this.props.onTextSearchResult) { this.props.onTextSearchResult({ 'found': event.nativeEvent.found, - 'textSelection': event.nativeEvent.textSelection, + 'textSelection': event.nativeEvent.textSelection }); } } @@ -352,7 +2075,7 @@ export class DocumentView extends PureComponent { if (this.props.onPageMoved) { this.props.onPageMoved({ 'previousPageNumber': event.nativeEvent.previousPageNumber, - 'pageNumber': event.nativeEvent.pageNumber, + 'pageNumber': event.nativeEvent.pageNumber }); } } @@ -372,6 +2095,19 @@ export class DocumentView extends PureComponent { } }; // Methods + /** + * @method + * @category Document + * @desc Returns the path of the current document. + * If {@link DocumentView.isBase64String isBase64String} is true, + * this would be the path to the temporary pdf file converted from + * the base64 string in {@link DocumentView.document document}. + * @returns {Promise} path - the document path. + * @example + * this._viewer.getDocumentPath().then((path) => { + * console.log('The path to current document is: ' + path); + * }); + */ getDocumentPath = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -379,6 +2115,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotation Tools + * @desc Sets the current tool mode. + * @param {Config.Tools} toolMode the tool mode to set. + * @returns {Promise} + * @example + * this._viewer.setToolMode(Config.Tools.annotationCreateFreeHand).then(() => { + * // done switching tools + * }); + */ setToolMode = (toolMode) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -386,6 +2133,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotation Tools + * @desc Commits the current tool, only available for multi-stroke ink and poly-shape. + * @returns {Promise} committed - true if either ink or poly-shape tool is + * committed, false otherwise + * @example + * this._viewer.commitTool().then((committed) => { + * // committed: true if either ink or poly-shape tool is committed, false otherwise + * }); + */ commitTool = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -393,6 +2151,16 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Gets the current page count of the document. + * @returns {Promise} pageCount - the current page count of the document + * @example + * this._viewer.getPageCount().then((pageCount) => { + * console.log('pageCount', pageCount); + * }); + */ getPageCount = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -400,6 +2168,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Bookmark + * @desc Imports user bookmarks into the document. + * The input needs to be a valid bookmark JSON format. + * @param {string} bookmarkJson needs to be in valid bookmark JSON format, + * for example {"0": "Page 1"}. The page numbers are 1-indexed + * @returns {Promise} + * @example + * this._viewer.importBookmarkJson("{\"0\": \"Page 1\", \"3\": \"Page 4\"}"); + */ importBookmarkJson = (bookmarkJson) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -407,6 +2186,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Bookmark + * @desc Displays the bookmark tab of the existing list container. + * If this tab has been disabled, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openBookmarkList(); + */ openBookmarkList = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -414,6 +2202,23 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Import/Export Annotations + * @desc Imports remote annotation command to local document. + * @param {string} xfdfCommand the XFDF command string + * @param {boolean} [initialLoad=false] whether this is for initial load. + * @returns {Promise} + * @example + * const xfdfCommand = '' + + * '' + + * '' + + * ''; + * this._viewer.importAnnotationCommand(xfdfCommand); + */ importAnnotationCommand = (xfdfCommand, initialLoad) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -424,6 +2229,22 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Import/Export Annotations + * @desc Imports XFDF annotation string to the current document. + * @param {string} xfdf annotation string in XFDF format for import + * @returns {Promise} + * @example + * const xfdf = '\n' + + * '\n\t\n\t\t' + + * '\n\t\n\t\t' + + * '\n\t' + + * '\n\t\n'; + * this._viewer.importAnnotations(xfdf); + */ importAnnotations = (xfdf) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -431,6 +2252,25 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Import/Export Annotations + * @desc Extracts XFDF from the current document. + * @param {object} options key: annotList, type: array. + * If specified, annotations with the matching id and pageNumber will be exported; + * otherwise, all annotations in the current document will be exported. + * @returns {Promise} xfdf - annotation string in XFDF format + * @example Without options: + * this._viewer.exportAnnotations().then((xfdf) => { + * console.log('XFDF for all annotations:', xfdf); + * }); + * @example With options: + * // annotList is an array of annotation data in the format {id: string, pageNumber: int} + * const annotations = [{id: 'annot1', pageNumber: 1}, {id: 'annot2', pageNumber: 3}]; + * this._viewer.exportAnnotations({annotList: annotations}).then((xfdf) => { + * console.log('XFDF for 2 specified annotations', xfdf); + * }); + */ exportAnnotations = (options) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -438,6 +2278,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Flattens the forms and (optionally) annotations in the current document. + * @param {boolean} formsOnly Defines whether only forms are flattened. + * If false, all annotations will be flattened. + * @returns {Promise} + * @example + * // flatten forms and annotations in the current document. + * this._viewer.flattenAnnotations(false); + */ flattenAnnotations = (formsOnly) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -445,6 +2296,26 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Deletes the specified annotations in the current document. + * @param {object[]} annotations Defines which annotation to be deleted. + * Each element is in the format {id: string, pageNumber: int} + * @returns {Promise} + * @example + * // delete annotations in the current document. + * this._viewer.deleteAnnotations([ + * { + * id: 'annotId1', + * pageNumber: 1, + * }, + * { + * id: 'annotId2', + * pageNumber: 2, + * } + * ]); + */ deleteAnnotations = (annotations) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -452,6 +2323,20 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Document + * @desc Saves the current document. + * If {@link DocumentView.isBase64String isBase64String} is true, + * this would be the base64 string encoded from the temporary pdf file, + * which is created from the base64 string in {@link DocumentView.document document}. + * @returns {Promise} filePath - the location of the saved document, + * or the base64 string of the pdf in the case of base64 + * @example + * this._viewer.saveDocument().then((filePath) => { + * console.log('saveDocument:', filePath); + * }); + */ saveDocument = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -459,6 +2344,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Sets a field flag value on one or more form fields. + * @param {string[]} fields list of field names for which the flag should be set + * @param {Config.FieldFlags} flag flag to be set + * @param {boolean} value value to set for flag + * @returns {Promise} + * @example + * this._viewer.setFlagForFields(['First Name', 'Last Name'], Config.FieldFlags.ReadOnly, true); + */ setFlagForFields = (fields, flag, value) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -466,6 +2362,25 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Get type and value information of a field using its name. + * @param {string} fieldName name of the field + * @returns {Promise} field - an object with information keys: + * `fieldName`, `fieldValue` (undefined for fields with no values) and + * `fieldType`(one of button, checkbox, radio, text, choice, signature and unknown), + * or undefined if such field does not exist + * + * @example + * this._viewer.getField('someFieldName').then((field) => { + * if (field !== undefined) { + * console.log('field name:', field.fieldName); + * console.log('field value:', field.fieldValue); + * console.log('field type:', field.fieldType); + * } + * }); + */ getField = (fieldName) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -473,6 +2388,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Displays the annotation tab of the existing list container. + * If this tab has been disabled, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openAnnotationList(); + */ openAnnotationList = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -481,12 +2405,32 @@ export class DocumentView extends PureComponent { return Promise.resolve(); }; /** - * note: this function exists for supporting the old version. It simply calls setValuesForFields. - * + * @method + * @deprecated Note: this function exists for supporting the old version. + * It simply calls {@link DocumentView#setValuesForFields setValuesForFields}. + * @ignore */ setValueForFields = (fieldsMap) => { return this.setValuesForFields(fieldsMap); }; + /** + * @method + * @category Annotations + * @desc Sets field values on one or more form fields. + * + * Note: the old function `setValueForFields` is deprecated. Please use this one instead. + * @param {object} fieldsMap map of field names and values which should be set + * @returns {Promise} + * @example + * this._viewer.setValuesForFields({ + * 'textField1': 'Test', + * 'textField2': 1234, + * 'checkboxField1': true, + * 'checkboxField2': false, + * 'radioButton1': 'Yes', + * 'radioButton2': 'No' + * }); + */ setValuesForFields = (fieldsMap) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -494,6 +2438,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Navigation + * @desc Handles the back button in search mode. Android only. + * @returns {Promise} handled - whether the back button is handled successfully + * @example + * this._viewer.handleBackButton().then((handled) => { + * if (!handled) { + * BackHandler.exitApp(); + * } + * }); + */ handleBackButton = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -502,12 +2458,44 @@ export class DocumentView extends PureComponent { return Promise.resolve(); }; /** - * note: this function exists for supporting the old version. It simply calls setFlagsForAnnotations. - * + * @method + * @deprecated Note: this function exists for supporting the old version. + * It simply calls {@link DocumentView#setFlagsForAnnotations setFlagsForAnnotations}. + * @ignore */ setFlagForAnnotations = (annotationFlagList) => { return this.setFlagsForAnnotations(annotationFlagList); }; + /** + * @method + * @category Annotations + * @desc Sets flags for specified annotations in the current document. + * The `flagValue` controls whether a flag will be set to or removed from the annotation. + * + * Note: the old function `setFlagForAnnotations` is deprecated. Please use this one. + * + * @param {object[]} annotationFlagList A list of annotation flag operations. + * Each element is in the format + * `{id: string, pageNumber: int, + * flag: One of {@link Config.AnnotationFlags} constants, flagValue: boolean}` + * @returns {Promise} + * @example + * // Set flag for annotations in the current document. + * this._viewer.setFlagsForAnnotations([ + * { + * id: 'annotId1', + * pageNumber: 1, + * flag: Config.AnnotationFlags.noView, + * flagValue: true + * }, + * { + * id: 'annotId2', + * pageNumber: 5, + * flag: Config.AnnotationFlags.lockedContents, + * flagValue: false + * } + * ]); + */ setFlagsForAnnotations = (annotationFlagList) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -515,6 +2503,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Selects the specified annotation in the current document. + * @param {string} id the id of the target annotation + * @param {integer} pageNumber the page number where the targe annotation is located. + * It is 1-indexed. + * @returns {Promise} + * @example + * // select annotation in the current document. + * this._viewer.selectAnnotation('annotId1', 1); + */ selectAnnotation = (id, pageNumber) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -523,12 +2523,63 @@ export class DocumentView extends PureComponent { return Promise.resolve(); }; /** - * note: this function exists for supporting the old version. It simply calls setPropertiesForAnnotation. - * + * @method + * @deprecated Note: this function exists for supporting the old version. + * It simply calls setPropertiesForAnnotation. + * @ignore */ setPropertyForAnnotation = (id, pageNumber, propertyMap) => { return this._viewerRef.setPropertiesForAnnotation(id, pageNumber, propertyMap); }; + /** + * @method + * @category Annotations + * @desc Sets properties for specified annotation in the current document, if it is valid. + * + * Note: the old function `setPropertyForAnnotation` is deprecated. Please use this one. + * + * @param {string} annotationId the unique id of the annotation + * @param {integer} pageNumber the page number where annotation is located. It is 1-indexed + * @param {object} propertyMap an object containing properties to be set. + * Available properties are listed below. + * + * Properties in propertyMap: + * + * Name | Type | Markup exclusive | Example + * --- | --- | --- | --- + * rect | object | no | {x1: 1, y1: 2, x2: 3, y2: 4} + * contents | string | no | "contents" + * subject | string | yes | "subject" + * title | string | yes | "title" + * contentRect | object | yes | {x1: 1, y1: 2, x2: 3, y2: 4} + * customData | object | no | {key: value} + * strokeColor | object | no | {red: 255, green: 0, blue: 0} + * + * @returns {Promise} + * @example + * // Set properties for annotation in the current document. + * this._viewer.setPropertiesForAnnotation('Pdftron', 1, { + * rect: { + * x1: 1.1, // left + * y1: 3, // bottom + * x2: 100.9, // right + * y2: 99.8 // top + * }, + * contents: 'Hello World', + * subject: 'Sample', + * title: 'set-prop-for-annot', + * customData: { + * key1: 'value1', + * key2: 'value2', + * key3: 'value3' + * }, + * strokeColor: { + * "red": 255, + * "green": 0, + * "blue": 0 + * } + * }); + */ setPropertiesForAnnotation = (id, pageNumber, propertyMap) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -536,6 +2587,31 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Gets properties for specified annotation in the current document, if it is valid. + * + * @param {string} annotationId the unique id of the annotation + * @param {integer} pageNumber the page number where annotation is located. It is 1-indexed + * @returns {Promise} propertyMap - the non-null properties of the annotation + * + * Name | Type | Markup exclusive | Example + * --- | --- | --- | --- + * rect | object | no | {x1: 1, y1: 1, x2: 2, y2: 2, width: 1, height: 1} + * contents | string | no | "Contents" + * subject | string | yes | "Subject" + * title | string | yes | "Title" + * contentRect | object | yes | {x1: 1, y1: 1, x2: 2, y2: 2, width: 1, height: 1} + * strokeColor | object | no | {red: 255, green: 0, blue: 0} + * @example + * // Get properties for annotation in the current document. + * this._viewer.getPropertiesForAnnotation('Pdftron', 1).then((properties) => { + * if (properties) { + * console.log('Properties for annotation: ', properties); + * } + * }) + */ getPropertiesForAnnotation = (id, pageNumber) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -543,6 +2619,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Sets whether all annotations and forms should be rendered. + * This method affects the viewer and does not change the document. + * + * Unlike {@link DocumentView#setVisibilityForAnnotation setVisibilityForAnnotation}, + * this method is used to show and hide all annotations and forms in the viewer. + * @param {boolean} drawAnnotations whether all annotations and forms should be rendered + * @returns {Promise} + * @example + * this._viewer.setDrawAnnotations(false); + */ setDrawAnnotations = (drawAnnotations) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -550,6 +2639,21 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Sets visibility for specified annotation in the current document, if it is valid. + * Note that if {@link DocumentView#setDrawAnnotations drawAnnotations} + * is set to false in the viewer, this function would not render the annotation even + * if visibility is true. + * + * @param {string} annotationId the unique id of the annotation + * @param {integer}pageNumber the page number where annotation is located. It is 1-indexed + * @param {boolean }visibility whether the annotation should be visible + * @returns {Promise} + * @example + * this._viewer.setVisibilityForAnnotation('Pdftron', 1, true); + */ setVisibilityForAnnotation = (id, pageNumber, visibility) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -557,6 +2661,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Enables or disables highlighting form fields. It is disabled by default. + * @param {boolean} highlightFields whether form fields should be highlighted + * @example + * this._viewer.setHighlightFields(true); + */ setHighlightFields = (highlightFields) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -564,6 +2676,33 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Gets an annotation at the (x, y) position in screen coordinates, if any. + * @param {integer} x the x-coordinate of the point + * @param {integer} y the y-coordinate of the point + * @param {double} distanceThreshold maximum distance from the point (x, y) + * to the annotation for it to be considered a hit (in dp) + * @param {double} minimumLineWeight For very thin lines, + * it is almost impossible to hit the actual line. + * This specifies a minimum line thickness (in screen coordinates) for the purpose of calculating + * whether a point is inside the annotation or not (in dp) + * @returns {Promise} annotation - the annotation found in the format of + * `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * this._viewer.getAnnotationAtPoint(167, 287, 100, 10).then((annotation) => { + * if (annotation) { + * console.log('Annotation found at point (167, 287) has id:', annotation.id); + * } + * }) + */ getAnnotationAtPoint = (x, y, distanceThreshold, minimumLineWeight) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -571,6 +2710,32 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Gets the list of annotations at a given line in screen coordinates. + * Note that this is not an area selection. It should be used similar + * to {@link DocumentView#getAnnotationAtPoint getAnnotationAtPoint}, except that this should + * be used when you want to get multiple annotations which are overlaying with each other. + * @param {integer} x1 x-coordinate of an endpoint on the line + * @param {integer} y1 y-coordinate of an endpoint on the line + * @param {integer} x2 x-coordinate of the other endpoint on the line, usually used as a threshold + * @param {integer} y2 y-coordinate of the other endpoint on the line, usually used as a threshold + * @returns {Promise} annotations - list of annotations at the target line, + * each in the format of `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * this._viewer.getAnnotationListAt(0, 0, 200, 200).then((annotations) => { + * for (const annotation of annotations) { + * console.log('Annotation found at line has id:', annotation.id); + * } + * }) + */ getAnnotationListAt = (x1, y1, x2, y2) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -578,6 +2743,26 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Gets the list of annotations on a given page. + * @param {integer} pageNumber the page number where annotations are located. It is 1-indexed + * @returns {Promise>} annotations - list of annotations on the target page, + * each in the format of `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * this._viewer.getAnnotationsOnPage(2).then((annotations) => { + * for (const annotation of annotations) { + * console.log('Annotation found on page 2 has id:', annotation.id); + * } + * }) + */ getAnnotationsOnPage = (pageNumber) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -585,6 +2770,26 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Annotations + * @desc Gets an annotation's `customData` property. + * @param {string} annotationId the unique id of the annotation + * @param {integer} pageNumber the page number where annotation is located. It is 1-indexed + * @param {string} key the unique key associated with the `customData` property + * @returns {Promise} value - the `customData` property associated + * with the given key + * @example + * this._viewer.setPropertiesForAnnotation("annotation1", 2, { + * customData: { + * data: "Nice annotation" + * } + * }).then(() => { + * this._viewer.getCustomDataForAnnotation("annotation1", 2, "data").then((value) => { + * console.log(value === "Nice annotation"); + * }) + * }) + */ getCustomDataForAnnotation = (annotationID, pageNumber, key) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -592,6 +2797,20 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Gets the crop box for specified page as a JSON object. + * @param {integer} pageNumber the page number for the target crop box. It is 1-indexed + * @returns {Promise} cropBox - an object with information about position + * (`x1`, `y1`, `x2` and `y2`) and size (`width` and `height`) + * @example + * this._viewer.getPageCropBox(1).then((cropBox) => { + * console.log('bottom-left coordinate:', cropBox.x1, cropBox.y1); + * console.log('top-right coordinate:', cropBox.x2, cropBox.y2); + * console.log('width and height:', cropBox.width, cropBox.height); + * }); + */ getPageCropBox = (pageNumber) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -599,6 +2818,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Sets current page of the document. + * @param {integer} pageNumber the page number to be set as the current page; 1-indexed + * @returns {Promise} success - whether the setting process was successful + * @example + * this._viewer.setCurrentPage(4).then((success) => { + * if (success) { + * console.log("Current page is set to 4."); + * } + * }); + */ setCurrentPage = (pageNumber) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -606,6 +2838,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Gets the visible pages in the current viewer as an array. + * @returns {Promise>} visiblePages - a list of visible pages in the + * current viewer + * @example + * this._viewer.getVisiblePages().then((visiblePages) => { + * for (const page of visiblePages) { + * console.log('page', page, 'is visible.') + * } + * }); + */ getVisiblePages = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -613,6 +2858,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Go to the previous page of the document. If on first page, it will stay on first page. + * @returns {Promise} success - whether the setting process was successful + * (no change due to staying in first page counts as being successful) + * @example + * this._viewer.gotoPreviousPage().then((success) => { + * if (success) { + * console.log("Go to previous page."); + * } + * }); + */ gotoPreviousPage = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -620,6 +2878,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Go to the next page of the document. If on last page, it will stay on last page. + * @returns {Promise} success - whether the setting process was successful + * (no change due to staying in last page counts as being successful) + * @example + * this._viewer.gotoNextPage().then((success) => { + * if (success) { + * console.log("Go to next page."); + * } + * }); + */ gotoNextPage = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -627,6 +2898,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Go to the first page of the document. + * @returns {Promise} success - whether the setting process was successful + * @example + * this._viewer.gotoFirstPage().then((success) => { + * if (success) { + * console.log("Go to first page."); + * } + * }); + */ gotoFirstPage = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -634,6 +2917,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Go to the last page of the document. + * @returns {Promise} success - whether the setting process was successful + * @example + * this._viewer.gotoLastPage().then((success) => { + * if (success) { + * console.log("Go to last page."); + * } + * }); + */ gotoLastPage = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -641,6 +2936,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Opens a go-to page dialog. If the user inputs a valid page number into the dialog, + * the viewer will go to that page. + * @returns {Promise} + * @example + * this._viewer.showGoToPageView(); + */ showGoToPageView = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -648,6 +2952,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Multi-tab + * @desc Closes all tabs in a multi-tab environment. + * @returns {Promise} + * @example + * // Do this only when DocumentView has multiTabEnabled = true + * this._viewer.closeAllTabs(); + */ closeAllTabs = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -655,6 +2968,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Multi-tab + * @desc Opens the tab switcher in a multi-tab environment. + * @returns {Promise} + * @example + * // Do this only when DocumentView has multiTabEnabled = true + * this._viewer.openTabSwitcher(); + */ openTabSwitcher = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -662,6 +2984,16 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Zoom + * @desc Returns the current zoom scale of current document viewer. + * @returns {Promise} zoom - current zoom scale in the viewer + * @example + * this._viewer.getZoom().then((zoom) => { + * console.log('Zoom scale of the current document is:', zoom); + * }); + */ getZoom = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -669,6 +3001,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Zoom + * @desc Sets the minimum and maximum zoom bounds of current viewer. + * @param {Config.ZoomLimitMode} zoomLimitMode defines whether bounds are relative to the + * standard zoom scale in the current viewer or absolute + * @param {double} minimum the lower bound of the zoom limit range + * @param {double} maximum the upper bound of the zoom limit range + * @returns {Promise} + * @example + * this._viewer.setZoomLimits(Config.ZoomLimitMode.Absolute, 1.0, 3.5); + */ setZoomLimits = (zoomLimitMode, minimum, maximum) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -676,6 +3020,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Zoom + * @desc Sets the zoom scale in the current document viewer with a zoom center. + * @param {double} zoom the zoom ratio to be set + * @param {int} x the x-coordinate of the zoom center + * @param {int} y the y-coordinate of the zoom center + * @returns {Promise} + * @example + * this._viewer.zoomWithCenter(3.0, 100, 300); + */ zoomWithCenter = (zoom, x, y) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -683,6 +3038,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Zoom + * @desc Zoom the viewer to a specific rectangular area in a page. + * @param {int} pageNumber the page number of the zooming area (1-indexed) + * @param {object} rect The rectangular area with keys + * `x1` (left), `y1` (bottom), `y1` (right), `y2` (top). Coordinates are in double + * @returns {Promise} + * @example + * this._viewer.zoomToRect(3, {'x1': 1.0, 'y1': 2.0, 'x2': 3.0, 'y2': 4.0}); + */ zoomToRect = (pageNumber, rect) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -690,6 +3056,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Zoom + * @desc Zoom to a paragraph that contains the specified coordinate. + * If no paragraph contains the coordinate, the zooming would not happen. + * @param {int} x the x-coordinate of the target coordinate + * @param {int} y the y-coordinate of the target coordinate + * @param {boolean} animated whether the transition is animated + * @returns {Promise} + * @example + * this._viewer.smartZoom(100, 200, true); + */ smartZoom = (x, y, animated) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -697,6 +3075,23 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Scroll + * @desc Returns the horizontal and vertical scroll position of current document viewer. + * @returns {Promise} + * + * Name | Type | Description + * --- | --- | --- + * horizontal | number | current horizontal scroll position + * vertical | number | current vertical scroll position + * + * @example + * this._viewer.getScrollPos().then(({horizontal, vertical}) => { + * console.log('Current horizontal scroll position is:', horizontal); + * console.log('Current vertical scroll position is:', vertical); + * }); + */ getScrollPos = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -704,6 +3099,23 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Canvas + * @desc Returns the canvas size of current document viewer. + * @returns {Promise} + * + * Name | Type | Description + * --- | --- | --- + * width | number | current width of canvas + * height | number | current height of canvas + * + * @example + * this._viewer.getCanvasSize().then(({width, height}) => { + * console.log('Current canvas width is:', width); + * console.log('Current canvas height is:', height); + * }); + */ getCanvasSize = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -711,6 +3123,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Gets the rotation value of all pages in the current document. + * @returns {Promise} pageRotation - the rotation degree of all pages, + * one of 0, 90, 180 or 270 (clockwise). + * @example + * this._viewer.getPageRotation().then((pageRotation) => { + * console.log('The current page rotation degree is' + pageRotation); + * }); + */ getPageRotation = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -718,6 +3141,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Rotates all pages in the current document in clockwise direction (by 90 degrees). + * @returns {Promise} + * @example + * this._viewer.rotateClockwise(); + */ rotateClockwise = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -725,6 +3156,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Rotates all pages in the current document in counter-clockwise direction (by 90 degrees). + * @returns {Promise} + * @example + * this._viewer.rotateCounterClockwise(); + */ rotateCounterClockwise = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -732,6 +3171,25 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Coordinate + * @desc Converts points from screen coordinates to page coordinates in the viewer. + * @param {object[]} points list of points, each in the format `{x: number, y: number}`. + * You could optionally have a `pageNumber: number` in the object. + * Without specifying, the page system is referring to the current page + * @returns {Promise} convertedPoints - list of converted points in page system, + * each in the format `{x: number, y: number}`. It would be empty if conversion is unsuccessful + * @example + * // convert (50, 50) and (100, 100) from screen system to page system, + * // on current page and page 1 respectively + * this._viewer.convertScreenPointsToPagePoints([{x: 50, y: 50}, {x: 100, y:100, pageNumber: 1}]) + * .then((convertedPoints) => { + * convertedPoints.forEach(point => { + * console.log(point); + * }) + * }); + */ convertScreenPointsToPagePoints = (points) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -739,6 +3197,25 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Coordinate + * @desc Converts points from page coordinates to screen coordinates in the viewer. + * @param {object[]} points list of points, each in the format `{x: number, y: number}`. + * You could optionally have a `pageNumber: number` in the object. + * Without specifying, the page system is referring to the current page + * @returns {Promise} convertedPoints - list of converted points in + * screen system, each in the format `{x: number, y: number}`. + * It would be empty if conversion is unsuccessful + * @example + * // convert (50, 50) on current page and (100, 100) on page 1 from page system to screen system + * this._viewer.convertPagePointsToScreenPoints([{x: 50, y: 50}, {x: 100, y:100, pageNumber: 1}]) + * .then((convertedPoints) => { + * convertedPoints.forEach(point => { + * console.log(point); + * }) + * }); + */ convertPagePointsToScreenPoints = (points) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -746,6 +3223,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Coordinate + * @desc Returns the page number that contains the point on screen. + * @param {number} x the x-coordinate of the screen point + * @param {number} y the y-coordinate of the screen point + * @returns {Promise} pageNumber - the page number of the screen point + * @example + * this._viewer.getPageNumberFromScreenPoint(10.0,50.5).then((pageNumber) => { + * console.log('The page number of the screen point is', pageNumber); + * }); + */ getPageNumberFromScreenPoint = (x, y) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -753,6 +3242,20 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Rendering Options + * @desc Sets whether the control will render progressively + * or will just draw once the entire view has been rendered. + * @param {boolean} progressiveRendering whether to render progressively + * @param {number} initialDelay delay before the progressive rendering timer is started, + * in milliseconds + * @param {number} interval delay between refreshes, in milliseconds + * @returns {Promise} + * @example + * // delay for 10s before start, and refresh every 1s + * this._viewer.setProgressiveRendering(true, 10000, 1000); + */ setProgressiveRendering = (progressiveRendering, initialDelay, interval) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -760,6 +3263,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Rendering Options + * @desc Enables or disables image smoothing. + * The rasterizer allows a trade-off between rendering quality and rendering speed. + * This function can be used to indicate the preference between rendering speed and quality. + * @param {boolean} imageSmoothing whether to enable image smoothing + * @returns {Promise} + * @example + * this._viewer.setImageSmoothing(false); + */ setImageSmoothing = (imageSmoothing) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -767,6 +3281,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Rendering Options + * @desc Enables or disables support for overprint and overprint simulation. + * Overprint is a device dependent feature and the results will vary depending + * on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc). + * @param {Config.OverprintMode} overprint the mode of overprint + * @returns {Promise} + * @example + * this._viewer.setOverprint(Config.OverprintMode.Off); + */ setOverprint = (overprint) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -774,13 +3299,37 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category UI Customization + * @desc Sets the color post processing transformation mode for the viewer. + * @param {Config.ColorPostProcessMode} colorPostProcessMode color post processing + * transformation mode + * @example + * this._viewer.setColorPostProcessMode(Config.ColorPostProcessMode.NightMode); + */ setColorPostProcessMode = (colorPostProcessMode) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - DocumentViewManager.setColorPostProcessMode(tag, colorPostProcessMode); + return DocumentViewManager.setColorPostProcessMode(tag, colorPostProcessMode); } return Promise.resolve(); }; + /** + * @method + * @category UI Customization + * @desc Sets the white and black color for the color post processing transformation. + * @param {object} whiteColor the white color for the color post processing transformation, + * in the format `{red: number, green: number, blue: number}`. + * `alpha` could be optionally included (only Android would apply alpha), + * and all numbers should be in range [0, 255] + * @param {object} blackColor the black color for the color post processing transformation, + * in the same format as whiteColor + * @example + * const whiteColor = {"red": 0, "green": 0, "blue": 255}; + * const blackColor = {"red": 255, "green": 0, "blue": 0}; + * this._viewer.setColorPostProcessColors(whiteColor, blackColor); + */ setColorPostProcessColors = (whiteColor, blackColor) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -788,6 +3337,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Search for a term and all matching results will be highlighted. + * @param {string} searchString the text to search for + * @param {boolean} matchCase indicates if it is case sensitive + * @param {boolean} matchWholeWord indicates if it matches an entire word only + * @returns {Promise} + * @example + * this._viewer.startSearchMode('PDFTron', false, false); + */ startSearchMode = (searchString, matchCase, matchWholeWord) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -795,6 +3355,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Finishes the current text search and remove all the highlights. + * @returns {Promise} + * @example + * this._viewer.exitSearchMode(); + */ exitSearchMode = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -802,6 +3370,20 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Searches asynchronously, starting from the current page, for the given text. + * PDFViewCtrl automatically scrolls to the position so that the found text is visible. + * @param {string} searchString the text to search for + * @param {boolean} matchCase indicates if it is case sensitive + * @param {boolean} matchWholeWord indicates if it matches an entire word only + * @param {boolean} searchUp indicates if it searches upward + * @param {boolean} regExp indicates if searchString is a regular expression + * @returns {Promise} + * @example + * this._viewer.findText('PDFTron', false, false, true, false); + */ findText = (searchString, matchCase, matchWholeWord, searchUp, regExp) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -809,6 +3391,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Cancels the current text search thread, if exists. + * @returns {Promise} + * @example + * this._viewer.cancelFindText(); + */ cancelFindText = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -816,6 +3406,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Displays a search bar that allows the user to enter and search text within a document. + * @returns {Promise} + * @example + * this._viewer.openSearch(); + */ openSearch = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -823,6 +3421,36 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Returns the text selection on a given page, if any. + * @param {number} pageNumber the specified page number. It is 1-indexed + * @returns {Promise} selection - the text selection, in the format + * `{html: string, unicode: string, pageNumber: number, + * quads: [[{x: number, y: number}, {x: number, y: number}, + * {x: number, y: number}, {x: number, y: number}], ...]}`. + * If no such selection could be found, this would be null + * + * Quads indicate the quad boundary boxes for the selection, + * which could have a size larger than 1 if selection spans across different lines. + * Each quad have 4 points with x, y coordinates specified in number, representing a boundary box. + * The 4 points are in counter-clockwise order, though the first point is not guaranteed to be on + * lower-left relatively to the box. + * @example + * this._viewer.getSelection(2).then((selection) => { + * if (selection) { + * console.log('Found selection on page', selection.pageNumber); + * for (let i = 0; i < selection.quads.length; i ++) { + * const quad = selection.quads[i]; + * console.log('selection boundary quad', i); + * for (const quadPoint of quad) { + * console.log('A quad point has coordinates', quadPoint.x, quadPoint.y); + * } + * } + * } + * }); + */ getSelection = (pageNumber) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -830,6 +3458,16 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Returns whether there is a text selection in the current document. + * @returns {Promise} hasSelection - whether a text selection exists + * @example + * this._viewer.hasSelection().then((hasSelection) => { + * console.log('There is a selection in the document.'); + * }); + */ hasSelection = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -837,6 +3475,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Clears any text selection in the current document. + * @returns {Promise} + * @example + * this._viewer.clearSelection(); + */ clearSelection = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -844,6 +3490,26 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Returns the page range (beginning and end) that has text selection on it. + * @returns {Promise} + * + * Name | Type | Description + * --- | --- | --- + * begin | number | the first page to have selection, -1 if there are no selections + * end | number | the last page to have selection, -1 if there are no selections + * + * @example + * this._viewer.getSelectionPageRange().then(({begin, end}) => { + * if (begin === -1) { + * console.log('There is no selection'); + * } else { + * console.log('The selection range is from', begin, 'to', end); + * } + * }); + */ getSelectionPageRange = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -851,6 +3517,20 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Returns whether there is a text selection on the specified page in the current document. + * @param {number} pageNumber the specified page number. It is 1-indexed + * @returns {Promise} hasSelection - whether a text selection exists on + * the specified page + * @example + * this._viewer.hasSelectionOnPage(5).then((hasSelection) => { + * if (hasSelection) { + * console.log('There is a selection on page 5 in the document.'); + * } + * }); + */ hasSelectionOnPage = (pageNumber) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -858,6 +3538,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Selects the text within the given rectangle region. + * @param {object} rect the rectangle region in the format of + * `{x1: number, x2: number, y1: number, y2: number}` + * @returns {Promise} selected - whether there is text selected + * @example + * this._viewer.selectInRect({x1: 0, y1: 0, x2: 200.5, y2: 200.5}).then((selected) => { + * console.log(selected); + * }); + */ selectInRect = (rect) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -865,6 +3557,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Returns whether there is text in given rectangle region. + * @param {object} rect the rectangle region in the format of + * `{x1: number, x2: number, y1: number, y2: number}` + * @returns {Promise} hasText - whether there is text in the region + * @example + * this._viewer.isThereTextInRect({x1: 0, y1: 0, x2: 200, y2: 200}).then((hasText) => { + * console.log(hasText); + * }); + */ isThereTextInRect = (rect) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -872,6 +3576,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Text Selection + * @desc Selects all text on the page. + * @returns {Promise} + * @example + * this._viewer.selectAll(); + */ selectAll = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -879,6 +3591,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Viewer Options + * @desc Sets whether borders of each page are visible in the viewer, + * which is disabled by default. + * @param {boolean} pageBorderVisibility whether borders of each page are visible in the viewer + * @example + * this._viewer.setPageBorderVisibility(true); + */ setPageBorderVisibility = (pageBorderVisibility) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -886,6 +3607,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Viewer Options + * @desc Enables or disables transparency grid (check board pattern) to reflect page transparency, + * which is disabled by default. + * @param {boolean} pageTransparencyGrid whether to use the transparency grid + * @example + * this._viewer.setPageTransparencyGrid(true); + */ setPageTransparencyGrid = (pageTransparencyGrid) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -893,6 +3623,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Viewer Options + * @desc Sets the default page color of the viewer. + * @param {object} defaultPageColor the default page color, in the format + * `{red: number, green: number, blue: number}`, each number in range [0, 255] + * @example + * this._viewer.setDefaultPageColor({red: 0, green: 255, blue: 0}); // green color + */ setDefaultPageColor = (defaultPageColor) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -900,6 +3639,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Viewer Options + * @desc Sets the background color of the viewer. + * @param {object} backgroundColor the background color, in the format + * `{red: number, green: number, blue: number}`, each number in range [0, 255] + * @example + * this._viewer.setBackgroundColor({red: 0, green: 0, blue: 255}); // blue color + */ setBackgroundColor = (backgroundColor) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -907,6 +3655,26 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc Export a PDF page to image format defined in {@link Config.ExportFormat}. + * + * Unlike {@link RNPdftron#exportAsImage RNPdftron.exportAsImage}, + * this is a viewer method and should only be called *after* the document has been + * loaded or else unexpected behaviour can occur. + * This method uses the PDF that is associated with the viewer, + * and does not take a local file path to the desired PDF. + * @param {int} pageNumber the page to be converted; + * if the value does not refer to a valid page number, the file path will be undefined + * @param {double} dpi the output image resolution + * @param {Config.ExportFormat} exportFormat image format to be exported to + * @returns {Promise} path - the temp path of the created image, + * user is responsible for clean up the cache + * @example + * this._viewer.exportToImage(1, 92, Config.ExportFormat.BMP).then((path) => { + * console.log('export', path); + * }); + */ exportAsImage = (pageNumber, dpi, exportFormat) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -914,6 +3682,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Undo/Redo + * @desc Undo the last modification. + * @returns {Promise} + * @example + * this._viewer.undo(); + */ undo = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -921,6 +3697,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Undo/Redo + * @desc Redo the last modification. + * @returns {Promise} + * @example + * this._viewer.redo(); + */ redo = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -928,6 +3712,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Undo/Redo + * @desc Checks whether an undo operation can be performed from the current snapshot. + * @returns {Promise} canUndo - whether it is possible to undo from + * the current snapshot + * @example + * this._viewer.canUndo().then((canUndo) => { + * console.log(canUndo ? 'undo possible' : 'no action to undo'); + * }); + */ canUndo = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -935,6 +3730,17 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Undo/Redo + * @desc Checks whether a redo operation can be perfromed from the current snapshot. + * @returns {Promise} canRedo - whether it is possible to redo from + * the current snapshot + * @example + * this._viewer.canRedo().then((canRedo) => { + * console.log(canRedo ? 'redo possible' : 'no action to redo'); + * }); + */ canRedo = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -942,6 +3748,13 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc Displays the page crop option. Android only. + * @returns {Promise} + * @example + * this._viewer.showCrop(); + */ showCrop = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -949,6 +3762,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Toolbar + * @desc Sets the current {@link DocumentView.annotationToolbars annotationToolbars} + * for the viewer. + * @param {Config.DefaultToolbars|string} toolbar the toolbar to enable. Should be one of the + * {@link Config.DefaultToolbars} constants or the `id` of a custom toolbar object. + * @returns {Promise} + * @example + * this._viewer.setCurrentToolbar(Config.DefaultToolbars.Insert).then(() => { + * // done switching toolbar + * }); + */ setCurrentToolbar = (toolbar) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -956,6 +3782,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc Displays the view settings. + * + * Requires a source rect in screen co-ordinates. + * On iOS this rect will be the anchor point for the view. The rect is ignored on Android. + * @param {map} rect The rectangular area in screen co-ordinates with keys + * `x1` (left), `y1` (bottom), `y1` (right), `y2` (top). Coordinates are in double format. + * @returns {Promise} + * @example + * this._viewer.showViewSettings({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}); + */ showViewSettings = (rect) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -963,6 +3801,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Page + * @desc Android only. + * + * Displays a rotate dialog. + * This dialog allows users to rotate pages of the opened document by 90, 180 and 270 degrees. + * It also displays a thumbnail of the current page at the selected rotation angle. + * @returns {Promise} + * @example + * this._viewer.showRotateDialog(); + */ showRotateDialog = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -970,6 +3820,18 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc Displays the add pages view. + * + * Requires a source rect in screen co-ordinates. + * On iOS this rect will be the anchor point for the view. The rect is ignored on Android. + * @param {map} rect The rectangular area in screen co-ordinates with keys + * `x1` (left), `y1` (bottom), `y1` (right), `y2`(top). Coordinates are in double format. + * @returns {Promise} + * @example + * this._viewer.showAddPagesView({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}); + */ showAddPagesView = (rect) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -977,6 +3839,16 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Reflow + * @desc Returns whether the viewer is currently in reflow mode. + * @returns {Promise} inReflow - whether the viewer is in reflow mode + * @example + * this._viewer.isReflowMode().then((inReflow) => { + * console.log(inReflow ? 'in reflow mode' : 'not in reflow mode'); + * }); + */ isReflowMode = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -984,6 +3856,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Reflow + * @desc Allows the user to programmatically enter and exit reflow mode. + * @returns {Promise} + * @example + * this._viewer.toggleReflow(); + */ toggleReflow = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -991,6 +3871,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc Displays the share copy view. + * + * Requires a source rect in screen co-ordinates. + * On iOS this rect will be the anchor point for the view. The rect is ignored on Android. + * @returns {Promise} + * @param {map} rect The rectangular area in screen co-ordinates with keys + * `x1` (left), y1 (bottom), `y1` (right), `y2` (top). Coordinates are in double format. + * @param {boolean} flattening Whether the shared copy should be flattened before sharing. + * @example + * this._viewer.shareCopy({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}, true); + */ shareCopy = (rect, flattening) => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -998,6 +3891,19 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Thumbnails + * @desc Display a page thumbnails view. + * + * This view allows users to navigate pages of a document. + * If {@link DocumentView.thumbnailViewEditingEnabled thumbnailViewEditingEnabled} is true, + * the user can also manipulate the document, including add, remove, re-arrange, rotate and + * duplicate pages. + * @returns {Promise} + * @example + * this._viewer.openThumbnailsView(); + */ openThumbnailsView = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1005,6 +3911,14 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc Displays the outline tab of the existing list container. + * If this tab has been disabled, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openOutlineList(); + */ openOutlineList = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1012,6 +3926,15 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc On Android it displays the layers dialog, while on iOS it displays the layers tab + * of the existing list container. If this tab has been disabled or there are no layers in + * the document, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openLayersList(); + */ openLayersList = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1019,6 +3942,13 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @desc Displays the existing list container. Its current tab will be the one last opened. + * @returns {Promise} + * @example + * this._viewer.openNavigationLists(); + */ openNavigationLists = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1026,6 +3956,21 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Signature + * @desc Gets a list of absolute file paths to PDFs containing the saved signatures. + * @returns {Promise>} signatures - an array of string containing the + * absolute file paths; if there are no saved signatures, the value is an empty array + * @example + * this._viewer.getSavedSignatures().then((signatures) => { + * if (signatures.length > 0) { + * signatures.forEach((signature) => { + * console.log(signature); + * }); + * } + * }) + */ getSavedSignatures = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1033,6 +3978,20 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Signature + * @desc Retrieves the absolute file path to the folder containing the saved signatures. + * For Android, to get the folder containing the saved signature JPGs, use + * {@link DocumentView.getSavedSignatureJpgFolder getSavedSignatureJpgFolder}. + * @returns {Promise} path - the absolute file path to the folder + * @example + * this._viewer.getSavedSignatureFolder().then((path) => { + * if (path != null) { + * console.log(path); + * } + * }) + */ getSavedSignatureFolder = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1040,6 +3999,22 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** + * @method + * @category Signature + * @desc Android only. + * + * Retrieves the absolute file path to the folder containing the saved signature JPGs. + * For Android, to get the folder containing the saved signature PDFs, use + * {@link DocumentView.getSavedSignatureFolder getSavedSignatureFolder}. + * @returns {Promise} path - the absolute file path to the folder + * @example + * this._viewer.getSavedSignatureJpgFolder().then((path) => { + * if (path != null) { + * console.log(path); + * } + * }) + */ getSavedSignatureJpgFolder = () => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1047,13 +4022,20 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); }; + /** @ignore */ _setNativeRef = (ref) => { this._viewerRef = ref; }; + /** + * @ignore + * + */ render() { return ( // @ts-ignore - ); } diff --git a/lib/src/PDFViewCtrl/PDFViewCtrl.js b/lib/src/PDFViewCtrl/PDFViewCtrl.js index abd2817cc..e35ad8293 100644 --- a/lib/src/PDFViewCtrl/PDFViewCtrl.js +++ b/lib/src/PDFViewCtrl/PDFViewCtrl.js @@ -1,14 +1,41 @@ import React, { PureComponent } from 'react'; import PropTypes from 'prop-types'; import { requireNativeComponent, ViewPropTypes, Platform } from 'react-native'; -const propTypes = { - document: PropTypes.string.isRequired, - ...ViewPropTypes, +/** + * @desc This object outlines valid {@link PDFViewCtrl} class props. + * These can be passed into {@link PDFViewCtrl} to customize the viewer. + * @ignore + */ +const PDFViewCtrlPropTypes = { + /** + * @memberof PDFViewCtrl + * @type {string} + * @desc The path or url to the document. Required. + * @hidesource + * @example + * + */ + document: PropTypes.string.isRequired }; +/** + * @class + * @classdesc A React component for displaying documents of different types such as + * PDF, docx, pptx, xlsx and various image formats. + * + * PDFViewCtrl is useful when a higher level of customization is required. + * For easy all-in-one document viewing and editing, use {@link DocumentView}. + * @hideconstructor + * @hidesource + * @ignore + */ export class PDFViewCtrl extends PureComponent { - static propTypes = propTypes; + static propTypes = Object.assign(PDFViewCtrlPropTypes, { ...ViewPropTypes }); render() { - return (); + return (); } } const name = Platform.OS === 'ios' ? 'RNTPTPDFViewCtrl' : 'RCTPDFViewCtrl'; diff --git a/package.json b/package.json index 1cd90855f..9a16b954e 100644 --- a/package.json +++ b/package.json @@ -6,8 +6,6 @@ "main": "./lib/index.js", "typings": "index.ts", "scripts": { - "copy-to-repo": "cd scripts && python3 fileCopy.py toRepo && cd ..", - "copy-to-node-modules": "cd scripts && python3 fileCopy.py toModule && cd ..", "start": "tsc" }, "repository": { @@ -31,6 +29,13 @@ "react": "*", "@types/react": "*", "@types/react-native": "*", + "@typescript-eslint/eslint-plugin": "^4.31.0", + "@typescript-eslint/parser": "^4.31.0", + "eslint": "^7.32.0", + "eslint-config-standard": "^16.0.3", + "eslint-plugin-import": "^2.24.2", + "eslint-plugin-node": "^11.1.0", + "eslint-plugin-promise": "^5.1.0", "typescript": "*" } } diff --git a/scripts/README.md b/scripts/README.md deleted file mode 100644 index 52982391d..000000000 --- a/scripts/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# scripts folder - -This folder is only for convenient file copying for pdftron react native, which does not in any way affect the implementation of this module. - -To run the scripts, you could go to [package.json](./../package.json) in the root to see the list of available scripts. - -For example, if script name is `copy-to-repo`, then navigate to the root of this repository, and run: - -``` -npm run copy-to-repo -``` - -## Scripts - -### copy-to-repo -This script copies pdftron-react-native (node modules in example -> root level of this repository). It is mostly useful when you have finished the implementation and are one step away from committing. - -### copy-to-node-modules -This script copies pdftron-react-native (root level of this repository -> node modules in example). Generally, this has been done by `npm install` or `yarn install`, but it could still be useful if you are switching branches. - diff --git a/scripts/fileCopy.py b/scripts/fileCopy.py deleted file mode 100644 index 7257ae49d..000000000 --- a/scripts/fileCopy.py +++ /dev/null @@ -1,27 +0,0 @@ -import sys -import os -import shutil - -# NOTE: this script is only used to copy files under android, ios and src folders. - -REPO_DIR = os.path.dirname(os.path.dirname(__file__)) -MODULE_DIR = os.path.join(REPO_DIR, 'example', 'node_modules', 'react-native-pdftron') - -COPY_FOLDER_LIST = ['android', 'ios', 'src'] - -toRepo = sys.argv[1] == 'toRepo' - -# The source and destination for copying process -srcRoot = MODULE_DIR if toRepo else REPO_DIR -dstRoot = REPO_DIR if toRepo else MODULE_DIR - -print(srcRoot) -print(dstRoot) - -# delete original folders if exist and copy over -for folder in COPY_FOLDER_LIST: - src = os.path.join(srcRoot, folder) - dst = os.path.join(dstRoot, folder) - if (os.path.exists(dst)): - shutil.rmtree(dst) - shutil.copytree(src, dst) \ No newline at end of file diff --git a/src/AnnotOptions/AnnotOptions.ts b/src/AnnotOptions/AnnotOptions.ts index 12edca35f..bca329a40 100644 --- a/src/AnnotOptions/AnnotOptions.ts +++ b/src/AnnotOptions/AnnotOptions.ts @@ -75,4 +75,4 @@ export interface StickyNoteData { type: string; pageRect?: Rect; screenRect?: Rect; -} \ No newline at end of file +} diff --git a/src/Config/Config.ts b/src/Config/Config.ts index bf4e4c33d..51f343a18 100644 --- a/src/Config/Config.ts +++ b/src/Config/Config.ts @@ -1,6 +1,21 @@ +/** + * @constant + * @class (Assigned to class for documentation purposes.) + * @hideconstructor + * @name Config + * @classdesc Defines configuration constants for the viewer. + * See [`Config.ts`](https://github.com/PDFTron/pdftron-react-native/blob/master/src/Config/Config.ts) + * for the full list of constants. + * + * Due to the length of the source file, we have included links to the exact lines + * of the source code where these APIs have been implemented. + */ export const Config = { - // Buttons define the various kinds of buttons for the viewer + /** + * @member + * @desc Buttons define the various kinds of buttons for the viewer + */ Buttons: { editToolButton: 'editToolButton', viewControlsButton: 'viewControlsButton', @@ -57,7 +72,10 @@ export const Config = { fileAttachmentButton: 'fileAttachmentButton', }, - // Tools define the various kinds of tools for the viewer + /** + * @member + * @desc Tools define the various kinds of tools for the viewer + */ Tools: { annotationEdit: 'AnnotationEdit', textSelect: 'TextSelect', @@ -107,7 +125,11 @@ export const Config = { annotationCreateLinkText: 'AnnotationCreateLinkText', }, - // FitMode define how a page should fit relative to the viewer, alternatively, the default zoom level + /** + * @member + * @desc FitMode define how a page should fit relative to the viewer, + * alternatively, the default zoom level + */ FitMode: { FitPage: 'FitPage', FitWidth: 'FitWidth', @@ -115,7 +137,10 @@ export const Config = { Zoom: 'Zoom', }, - // LayoutMode defines the layout mode of the viewer + /** + * @member + * @desc LayoutMode defines the layout mode of the viewer + */ LayoutMode: { Single: 'Single', Continuous: 'Continuous', @@ -125,13 +150,19 @@ export const Config = { FacingCoverContinuous: 'FacingCoverContinuous', }, - // FieldFlags define the property flags for a form field + /** + * @member + * @desc FieldFlags define the property flags for a form field + */ FieldFlags: { ReadOnly: 0, Required: 1, }, - // AnnotationMenu defines the menu items when an annotation is selected + /** + * @member + * @desc AnnotationMenu defines the menu items when an annotation is selected + */ AnnotationMenu: { style: 'style', note: 'note', @@ -153,14 +184,20 @@ export const Config = { ungroup: 'ungroup', }, - // EraserType defines the type of eraser that will be used when eraser is selected + /** + * @member + * @desc EraserType defines the type of eraser that will be used when eraser is selected + */ EraserType: { annotationEraser: 'annotationEraser', hybrideEraser: 'hybrideEraser', inkEraser: 'inkEraser' }, - // LongPressMenu defines the menu items when a long press on empty space or text occurs + /** + * @member + * @desc LongPressMenu defines the menu items when a long press on empty space or text occurs + */ LongPressMenu: { copy: 'copy', paste: 'paste', @@ -169,13 +206,19 @@ export const Config = { read: 'read', }, - // Actions define potentially overridable action to the viewer + /** + * @member + * @desc Actions define potentially overridable action to the viewer + */ Actions: { linkPress: 'linkPress', stickyNoteShowPopUp: 'stickyNoteShowPopUp', }, - // AnnotationFlags define the flags for any annotation in the document + /** + * @member + * @desc AnnotationFlags define the flags for any annotation in the document + */ AnnotationFlags: { hidden: "hidden", invisible: "invisible", @@ -189,7 +232,10 @@ export const Config = { toggleNoView: "toggleNoView" }, - // DefaultToolbars define a set of pre-designed toolbars for easier customization + /** + * @member + * @desc DefaultToolbars define a set of pre-designed toolbars for easier customization + */ DefaultToolbars: { View: "PDFTron_View", Annotate: "PDFTron_Annotate", @@ -203,7 +249,10 @@ export const Config = { Favorite: "PDFTron_Favorite" }, - // ToolbarIcons define default toolbar icons for use for potential custom toolbars + /** + * @member + * @desc ToolbarIcons define default toolbar icons for use for potential custom toolbars + */ ToolbarIcons: { View: "PDFTron_View", Annotate: "PDFTron_Annotate", @@ -217,7 +266,10 @@ export const Config = { Favorite: "PDFTron_Favorite" }, - // CustomToolbarKey defines the necessary keys for a custom toolbar + /** + * @member + * @desc CustomToolbarKey defines the necessary keys for a custom toolbar + */ CustomToolbarKey: { Id: "id", Name: "name", @@ -225,48 +277,69 @@ export const Config = { Items: "items" }, - // CustomToolItemKey defines the necessary keys for a custom tool inside a custom toolbar + /** + * @member + * @desc CustomToolItemKey defines the necessary keys for a custom tool inside a custom toolbar + */ CustomToolItemKey: { Id: "id", Name: "name", Icon: "icon" }, - // ThumbnailFilterMode defines filter modes in the thumbnails browser + /** + * @member + * @desc ThumbnailFilterMode defines filter modes in the thumbnails browser + */ ThumbnailFilterMode: { Annotated: "annotated", Bookmarked: "bookmarked", }, - // Conversion defines conversion sources and destinations + /** + * @member + * @desc Conversion defines conversion sources and destinations + */ Conversion: { Screen: "screen", Canvas: "canvas", Page: "page", }, - // ViewModePickerItem defines view mode items in the view mode dialog + /** + * @member + * @desc ViewModePickerItem defines view mode items in the view mode dialog + */ ViewModePickerItem: { Crop: "viewModeCrop", Rotation: "viewModeRotation", ColorMode: "viewModeColorMode", }, - // ZoomLimitMode defines the limit mode for zoom in the current document viewer + /** + * @member + * @desc ZoomLimitMode defines the limit mode for zoom in the current document viewer + */ ZoomLimitMode: { None: "none", Absolute: "absolute", Relative: "relative", }, - // OverprintMode defines when overprint would be applied in the viewer + /** + * @member + * @desc OverprintMode defines when overprint would be applied in the viewer + */ OverprintMode: { On: "on", Off: "off", OnlyPDFX: "pdfx", // only apply to PDF/X files }, - // ColorPostProcessMode defines color modifications after rendering in the viewer + /** + * @member + * @desc ColorPostProcessMode defines color modifications after rendering in the viewer + */ ColorPostProcessMode: { None: "none", Invert: "invert", @@ -274,26 +347,38 @@ export const Config = { NightMode: "nightMode" }, - // ReflowOrientation defines the scrolling direction when in reflow viewing mode + /** + * @member + * @desc ReflowOrientation defines the scrolling direction when in reflow viewing mode + */ ReflowOrientation: { Horizontal: 'horizontal', Vertical: 'vertical', }, - // Export to format + /** + * @member + * @desc Export to format + */ ExportFormat: { BMP: "BMP", JPEG: "JPEG", PNG: "PNG", }, - // AnnotationManagerEditMode determines whose changes can be edited. + /** + * @member + * @desc AnnotationManagerEditMode determines whose changes can be edited. + */ AnnotationManagerEditMode: { Own: "own", All: "all", }, - // AnnotationManagerUndoMode determines whose changes can be undone. + /** + * @member + * @desc AnnotationManagerUndoMode determines whose changes can be undone. + */ AnnotationManagerUndoMode: { Own: "own", All: "all", @@ -330,6 +415,7 @@ type ValueOf = T[keyof T]; * * These types are used for props such as `disabledElements` and methods such as `exportAsImage` */ +// eslint-disable-next-line no-redeclare export module Config { export type Buttons = ValueOf; export type Tools = ValueOf; @@ -351,7 +437,7 @@ export module Config { export type ColorPostProcessMode = ValueOf; export type ReflowOrientation = ValueOf; export type ExportFormat = ValueOf; - export type AnnotationManagerEditMode = ValueOf; + export type AnnotationManagerEditMode = ValueOf; export type AnnotationManagerUndoMode = ValueOf; export type CustomToolbarKey = { id: string; diff --git a/src/DocumentView/DocumentView.tsx b/src/DocumentView/DocumentView.tsx index a2eee0fb7..0ce6519be 100644 --- a/src/DocumentView/DocumentView.tsx +++ b/src/DocumentView/DocumentView.tsx @@ -6,86 +6,1215 @@ import { Platform, Alert, NativeModules, - findNodeHandle, + findNodeHandle } from 'react-native'; -const { DocumentViewManager } = NativeModules; -import {Config} from "../Config/Config"; +import { Config } from "../Config/Config"; import * as AnnotOptions from "../AnnotOptions/AnnotOptions"; +const { DocumentViewManager } = NativeModules; -/** - * Object containing PropTypes types for {@link DocumentView} class. - * Also used to generate prop types for TS users. +/** + * @desc This object outlines valid {@link DocumentView} class props. + * These can be passed into {@link DocumentView} to customize the viewer. + * + * For Contributors: The propTypes interface below contains PropTypes types for + * the {@link DocumentView} class. + * It is also used to generate custom types for TS users. * * To represent functions, please use {@link func}. * To represent "one of Config.Buttons values" or "an array of * Config.Buttons values", please use {@link oneOf} or {@link arrayOf}. + * + * @ignore */ -const propTypes = { +export const DocumentViewPropTypes = { + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @desc The path or url to the document. Required. + * @example + * + */ document: PropTypes.string.isRequired, + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @desc The password of the document, if any. + * @example + * + */ password: PropTypes.string, + + /** + * @memberof DocumentView + * @category Page + * @type {number} + * @optional + * @desc Defines the initial page number that viewer displays when the document is opened. + * Note that page numbers are 1-indexed. + * @example + * + */ initialPageNumber: PropTypes.number, + + /** + * @memberof DocumentView + * @category Page + * @type {number} + * @optional + * @desc Defines the currently displayed page number. + * Different from {@link DocumentView.initialPageNumber initialPageNumber}, + * changing this prop value at runtime will change the page accordingly. + * @example + * + */ pageNumber: PropTypes.number, + + /** + * @memberof DocumentView + * @category Open a Document + * @type {object} + * @optional + * @desc Defines custom headers to use with HTTP/HTTPS requests. + * @example + * + */ customHeaders: PropTypes.object, + + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @default The extension in the {@link DocumentView.document document} prop + * @desc Used for specifying the extension of the document to be loaded. + * @example + * + */ documentExtension: PropTypes.string, + + /** + * @memberof DocumentView + * @category UI Customization + * @type {string} + * @optional + * @desc The file name of the icon to be used for the leading navigation button. + * The button will use the specified icon if it is valid, and the default icon otherwise. + * + * **Note**: to add the image file to your application, please follow the steps below: + * + * ##### Android + * 1. Add the image resource to the drawable directory in + * [`example/android/app/src/main/res`](https://github.com/PDFTron/pdftron-react-native/blob/master/example/android/app/src/main/res). + * For details about supported file types and potential compression, check out + * [here](https://developer.android.com/guide/topics/graphics/drawables#drawables-from-images). + * + * demo-android + *

+ * 2. Now you can use the image in the viewer. + * For example, if you add `button_close.png` to drawable, + * you could use `'button_close'` in leadingNavButtonIcon. + * + * ##### iOS + * 1. After pods has been installed, open the `.xcworkspace` file for this application in Xcode + * (in this case, it's [`example.xcworkspace`](https://github.com/PDFTron/pdftron-react-native/tree/master/example/ios/example.xcworkspace)), + * and navigate through the list below. + * This would allow you to add resources, in this case, an image, to your project. + * - "Project navigator" + * - "example" (or the app name) + * - "Build Phases" + * - "Copy Bundle Resources" + * - "+". + * + * demo-ios + *

+ * 2. Now you can use the image in the viewer. + * For example, if you add `button_open.png` to the bundle, + * you could use `'button_open.png'` in leadingNavButtonIcon. + * + * @example + * let iosNav = 'ic_close_black_24px.png'; + * let androidNav = 'ic_arrow_back_white_24dp'; + * + */ leadingNavButtonIcon: PropTypes.string, + + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show the leading navigation button. + * @example + * + */ showLeadingNavButton: PropTypes.bool, + + /** + * @memberof DocumentView + * @category UI Customization + * @event + * @type {function} + * @optional + * @desc This function is called when the leading navigation button is pressed. + * @example + * { + * console.log('The leading nav has been pressed'); + * }} + * /> + */ onLeadingNavButtonPressed: func<() => void>(), + + /** + * @memberof DocumentView + * @category Open a Document + * @event + * @type {function} + * @optional + * @desc This function is called when the document finishes loading. + * @param {string} path + * @example + * { + * console.log('The document has finished loading:', path); + * }} + * /> + */ onDocumentLoaded: func<(path: string) => void>(), + + /** + * @memberof DocumentView + * @category Open a Document + * @event + * @type {function} + * @optional + * @desc This function is called when document opening encounters an error. + * @param {string} error + * @example + * { + * console.log('Error occured during document opening:', error); + * }} + * /> + */ onDocumentError: func<(error: string) => void>(), - onPageChanged: func<(event: {previousPageNumber: number, pageNumber: number}) => void>(), - onScrollChanged: func<(event: {horizontal: number, vertical: number}) => void>(), - onZoomChanged: func<(event: {zoom: number}) => void>(), - onZoomFinished: func<(event: {zoom: number}) => void>(), + + /** + * @memberof DocumentView + * @category Page + * @event + * @type {function} + * @optional + * @desc This function is called when the page number has been changed. + * @param {int} previousPageNumber the previous page number + * @param {int} pageNumber the current page number + * @example + * { + * console.log('Page number changes from', previousPageNumber, 'to', pageNumber); + * }} + * /> + */ + onPageChanged: func<(event: { previousPageNumber: number, pageNumber: number }) => void>(), + + /** + * @memberof DocumentView + * @category Scroll + * @event + * @type {function} + * @optional + * @desc This function is called when the scroll position has been changed. + * @param {number} horizontal the horizontal position of the scroll + * @param {number} vertical the vertical position of the scroll + * @example + * { + * console.log('Current scroll position is', horizontal, + * 'horizontally, and', vertical, 'vertically.'); + * }} + * /> + */ + onScrollChanged: func<(event: { horizontal: number, vertical: number }) => void>(), + + /** + * @memberof DocumentView + * @category Zoom + * @event + * @type {function} + * @optional + * @desc This function is called when the zoom scale has been changed. + * @param {double} zoom the current zoom ratio of the document + * @example + * { + * console.log('Current zoom ratio is', zoom); + * }} + * /> + */ + onZoomChanged: func<(event: { zoom: number }) => void>(), + + /** + * @memberof DocumentView + * @category Zoom + * @event + * @type {function} + * @optional + * @desc This function is called when a zooming has been finished. + * For example, if zoom via gesture, this is called on gesture release. + * @param {double} zoom the current zoom ratio of the document + * @example + * { + * console.log('Current zoom ratio is', zoom); + * }} + * /> + */ + onZoomFinished: func<(event: { zoom: number }) => void>(), + + /** + * @memberof DocumentView + * @category Zoom + * @type {number} + * @optional + * @desc Zoom factor used to display the page content. + * @example + * + */ zoom: PropTypes.number, + + /** + * @memberof DocumentView + * @category UI Customization + * @type {Config.Buttons[]} + * @optional + * @default Defaults to none. + * @desc Defines buttons to be disabled for the viewer. + * @example + * + */ disabledElements: arrayOf(Config.Buttons), + + /** + * @memberof DocumentView + * @category UI Customization + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines tools to be disabled for the viewer. + * @example + * + */ disabledTools: arrayOf(Config.Tools), + + /** + * @memberof DocumentView + * @category Long Press Menu + * @type {Config.LongPressMenu[]} + * @optional + * @default Contains all the items. + * @desc Defines menu items that can show when long press on text or blank space. + * @example + * + */ longPressMenuItems: arrayOf(Config.LongPressMenu), + + /** + * @memberof DocumentView + * @category Long Press Menu + * @type {Config.LongPressMenu[]} + * @optional + * @default Defaults to none. + * @desc Defines the menu items on long press that will skip default behavior when pressed. + * They will still be displayed in the long press menu, + * and the function {@link DocumentView.event:onLongPressMenuPress onLongPressMenuPress} + * will be called where custom behavior can be implemented. + * @example + * + */ overrideLongPressMenuBehavior: arrayOf(Config.LongPressMenu), - onLongPressMenuPress: func<(event: {longPressMenu: string, longPressText: string}) => void>(), + + /** + * @memberof DocumentView + * @category Long Press Menu + * @event + * @type {function} + * @optional + * @desc This function is called if the pressed long press menu item is passed in to + * {@link DocumentView.overrideLongPressMenuBehavior overrideLongPressMenuBehavior}. + * @param {Config.LongPressMenu} longPressMenu the menu item that has been pressed. + * @param {string} longPressText the selected text if pressed on text, empty otherwise + * @example + * { + * console.log('Long press menu item', longPressMenu, 'has been pressed'); + * if (longPressText !== '') { + * console.log('The selected text is', longPressText); + * } + * }} + * /> + */ + onLongPressMenuPress: func<(event: { longPressMenu: string, longPressText: string }) => void>(), + + /** + * @memberof DocumentView + * @category Long Press Menu + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show the popup menu of options + * when the user long presses on text or blank space on the document. + * @example + * + */ longPressMenuEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotation Menu + * @type {Config.AnnotationMenu[]} + * @optional + * @default Contains all the items. + * @desc Defines the menu items that can show when an annotation is selected. + * @example + * + */ annotationMenuItems: arrayOf(Config.AnnotationMenu), + + /** + * @memberof DocumentView + * @category Annotation Menu + * @type {Config.AnnotationMenu[]} + * @optional + * @default Defaults to none. + * @desc Defines the menu items that will skip default behavior when pressed. + * They will still be displayed in the annotation menu, + * and the function {@link DocumentView.event:onAnnotationMenuPress onAnnotationMenuPress} + * will be called where custom behavior can be implemented. + * @example + * + */ overrideAnnotationMenuBehavior: arrayOf(Config.AnnotationMenu), - onAnnotationMenuPress: func<(event: {annotationMenu: string, annotations: Array}) => void>(), + + /** + * @memberof DocumentView + * @category Annotation Menu + * @event + * @type {function} + * @optional + * @desc This function is called when an annotation menu item passed in to + * {@link DocumentView.overrideAnnotationMenuBehavior overrideAnnotationMenuBehavior} is pressed. + * @param {Config.AnnotationMenu} annotationMenu the menu item that has been pressed. + * @param {object[]} annotations An array of + * `{id: string, pageNumber: number, type: string, screenRect: object, pageRect: object}` objects. + * + * `id` is the annotation identifier and `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * + * Both rects are represented with + * `{x1: number, y1: number, x2: number, y2: number, width: number, height: number}` objects. + * @example + * { + * console.log('Annotation menu item', annotationMenu, 'has been pressed'); + * annotations.forEach(annotation => { + * console.log('The id of selected annotation is', annotation.id); + * console.log('The page number of selected annotation is', annotation.pageNumber); + * console.log('The type of selected annotation is', annotation.type); + * console.log('The screenRect of selected annotation is', annotation.screenRect); + * console.log('The pageRect of selected annotation is', annotation.pageRect); + * }); + * }} + * /> + */ + onAnnotationMenuPress: func<(event: { + annotationMenu: string, + annotations: Array + }) => void>(), + + /** + * @memberof DocumentView + * @category Annotation Menu + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines annotation types that will not show in the annotation (long-press) menu. + * @example + * + */ hideAnnotationMenu: arrayOf(Config.Tools), + + /** + * @memberof DocumentView + * @category Custom Behavior + * @type {Config.Actions[]} + * @optional + * @default Defaults to none. + * @desc Defines actions that will skip default behavior, such as external link click. + * The function {@link DocumentView.event:onBehaviorActivated onBehaviorActivated} will be + * called where custom behavior can be implemented, whenever the defined actions occur. + * @example + * + */ overrideBehavior: arrayOf(Config.Actions), - onBehaviorActivated: func<(event: {action: Config.Actions, data: AnnotOptions.LinkPressData | AnnotOptions.StickyNoteData}) => void>(), + + /** + * @memberof DocumentView + * @category Custom Behavior + * @event + * @type {function} + * @optional + * @desc This function is called if the activated behavior is passed in to + * {@link DocumentView.overrideBehavior overrideBehavior} + * @param {Config.Actions} action the action which has been activated. + * @param {object} data A JSON object that varies depending on the action. + * + * If action is `Config.Actions.linkPress`, data type is `{url: string}`. + * + * If action is `Config.Actions.stickyNoteShowPopUp`, data type is + * `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}` + * + * `type` is one of the {@link Config.Tools} constants, + * + * `screenRect` was formerly called `rect`. + * @example + * { + * console.log('Activated action is', action); + * if (action === Config.Actions.linkPress) { + * console.log('The external link pressed is', data.url); + * } else if (action === Config.Actions.stickyNoteShowPopUp) { + * console.log('Sticky note has been activated, but it would not show a pop up window.'); + * } + * }} + * /> + */ + onBehaviorActivated: func<(event: { + action: Config.Actions, + data: AnnotOptions.LinkPressData | AnnotOptions.StickyNoteData + }) => void>(), + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default true + * @deprecated Use the {@link DocumentView.hideTopAppNavBar hideTopAppNavBar} prop instead. + */ topToolbarEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the bottom toolbar of the viewer is enabled. + * @example + * + */ bottomToolbarEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether an unhandled tap in the viewer should toggle the visibility + * of the top and bottom toolbars. When false, the top and bottom toolbar visibility + * will not be toggled and the page content will fit between the bars, if any. + * @example + * + */ hideToolbarsOnTap: PropTypes.bool, + + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the document slider of the viewer is enabled. + * @example + * + */ documentSliderEnabled: PropTypes.bool, - downloadDialogEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Page + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show the page indicator for the viewer. + * @example + * + */ pageIndicatorEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether the download dialog should be shown. + * @example + * + */ + downloadDialogEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Page + * @type {boolean} + * @optional + * @default true + * @desc iOS only + * + * Defines whether the keyboard shortcuts of the viewer are enabled. + * @example + * + */ keyboardShortcutsEnabled: PropTypes.bool, - onAnnotationsSelected: func<(event: {annotations: Array}) => void>(), - onAnnotationChanged: func<(event: {action: string, annotations: Array}) => void>(), - onAnnotationFlattened: func<(event: {annotations: Array}) => void>(), - onFormFieldValueChanged: func<(event: {fields: Array}) => void>(), - onAnnotationToolbarItemPress: func<(event: {id: string}) => void>(), + + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called when an annotation(s) is selected. + * @param {object[]} annotations array of annotation data in the format + * `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`, + * representing the selected annotations. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * { + * annotations.forEach(annotation => { + * console.log('The id of selected annotation is', annotation.id); + * console.log('It is in page', annotation.pageNumber); + * console.log('Its type is', annotation.type); + * }); + * }} + * /> + */ + onAnnotationsSelected: func<(event: { annotations: Array }) => void>(), + + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to an annotation(s) + * in the current document. + * + * Note: When an annotation is flattened, it also gets deleted, so both + * {@link DocumentView.event:onAnnotationChanged onAnnotationChanged} and + * {@link DocumentView.event:onAnnotationFlattened onAnnotationFlattened} are called. + * + * @param {string} action the action that occurred (add, delete, modify) + * @param {object[]} annotations array of annotation data in the format + * `{id: string, pageNumber: number, type: string}`, + * representing the annotations that have been changed. + * + * `type` is one of the {@link Config.Tools} constants + * @example + * { + * console.log('Annotation edit action is', action); + * annotations.forEach(annotation => { + * console.log('The id of changed annotation is', annotation.id); + * console.log('It is in page', annotation.pageNumber); + * console.log('Its type is', annotation.type); + * }); + * }} + * /> + */ + onAnnotationChanged: func<(event: { + action: string, + annotations: Array + }) => void>(), + + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to form field values. + * @param {object[]} fields array of field data in the format + * `{fieldName: string, fieldType: string, fieldValue: any}`, + * representing the fields that have been changed + * @example + * { + * fields.forEach(field => { + * console.log('The name of the changed field is', field.fieldName); + * console.log('The type of the changed field is', field.fieldType); + * console.log('The value of the changed field is', field.fieldValue); + * }); + * }} + * /> + */ + onFormFieldValueChanged: func<(event: { fields: Array }) => void>(), + + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if an annotation(s) has been flattened in the + * current document. + * @param {object[]} annotations array of annotation data in the format + * `{id: string, pageNumber: number, type: string}`, + * representing the annotations that have been changed. + * + * `type` is one of the {@link Config.Tools} constants + * + * `id` returned via the event listener can be null. + * @example + * { + annotations.forEach(annotation => { + console.log('The id of changed annotation is', annotation.id); + console.log('It is in page', annotation.pageNumber); + console.log('Its type is', annotation.type); + }); + }} + * /> + */ + onAnnotationFlattened: func<(event: { + annotations: + Array + }) => void>(), + + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default false + * @desc Defines whether the viewer is read-only. + * If true, the UI will not allow the user to change the document. + * @example + * + */ readOnly: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotations + * @event + * @type {function} + * @optional + * @desc This function is called when a custom toolbar tool item is clicked + * @param {string} id the Config.CustomToolItemKey.Id defined in the tool + * @example + * { + * console.log('toolbar item press: ' + id); + * }} + * /> + */ + onAnnotationToolbarItemPress: func<(event: { id: string }) => void>(), + + /** + * @memberof DocumentView + * @category Thumbnails + * @type {boolean} + * @optional + * @default true + * @desc Defines whether user can modify the document + * using the thumbnail view (eg add/remove/rotate pages). + * @example + * + */ thumbnailViewEditingEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Layout + * @type {Config.FitMode} + * @optional + * @default Config.FitMode.FitWidth + * @desc Defines the fit mode (default zoom level) of the viewer. + * @example + * + */ fitMode: oneOf(Config.FitMode), + + /** + * @memberof DocumentView + * @category Layout + * @type {Config.LayoutMode} + * @optional + * @default Config.LayoutMode.Continuous + * @desc Defines the layout mode of the viewer. + * @example + * + */ layoutMode: oneOf(Config.LayoutMode), + + /** + * @memberof DocumentView + * @category Layout + * @event + * @type {function} + * @optional + * @desc This function is called when the layout of the viewer has been changed. + * @example + * { + * console.log('Layout has been updated.'); + * }} + * /> + */ onLayoutChanged: func<() => void>(), + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Android only + * + * Defines whether the viewer will add padding to take account of the system status bar. + * @example + * + */ padStatusBar: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc If true, the active annotation creation tool will remain in the current annotation + * creation tool. Otherwise, it will revert to the "pan tool" after an annotation is created. + * @example + * + */ continuousAnnotationEditing: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc Defines whether an annotation is selected after it is created. + * On iOS, this functions for shape and text markup annotations only. + * @example + * + */ selectAnnotationAfterCreation: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotations + * @type {string} + * @optional + * @desc Defines the author name for all annotations created on the current document. + * Exported xfdfCommand will include this piece of information. + * @example + * + */ annotationAuthor: PropTypes.string, + + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default true + * @desc Defines whether to show saved signatures for re-use when using the signing tool. + * @example + * + */ showSavedSignatures: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default true + * @desc iOS only + * + * Defines whether to store new signatures when using the signing tool. + * @example + * + */ storeNewSignature: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default false + * @desc If true, {@link DocumentView.document document} prop will be treated as a base64 string. + * If it is not the base64 string of a pdf file, + * {@link DocumentView.base64FileExtension base64FileExtension} is required. + * + * When viewing a document initialized with a base64 string (i.e. a memory buffer), + * a temporary file is created on Android and iOS. + * @example + * + */ isBase64String: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Collaboration + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to enable realtime collaboration. + * If true then {@link DocumentView.currentUser currentUser} must be set as well for + * collaboration mode to work. Feature set may vary between local and collaboration mode. + * @example + * + */ collabEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Collaboration + * @type {string} + * @desc Required if {@link DocumentView.collabEnabled collabEnabled} is set to true. + * + * Defines the current user. + * Created annotations will have their title (author) set to this string. + * @example + * + */ currentUser: PropTypes.string, + + /** + * @memberof DocumentView + * @category Collaboration + * @type {string} + * @optional + * @desc Defines the current user name. + * Will set the user name only if {@link DocumentView.collabEnabled collabEnabled} is true + * and {@link DocumentView.currentUser currentUser} is defined. This should be used only if + * you want the user's display name to be different than the annotation's title/author + * (in the case that {@link DocumentView.currentUser currentUser} is an ID rather than a + * human-friendly name.) + * @example + * + */ currentUserName: PropTypes.string, - onExportAnnotationCommand: func<(event: {action: string, xfdfCommand: string, annotations: Array}) => void>(), + + /** + * @memberof DocumentView + * @category Import/Export Annotations + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to annotations in the current document. + * Unlike {@link DocumentView.event:onAnnotationChanged onAnnotationChanged}, this function has + * an XFDF command string as its parameter. If you are modifying or deleting multiple annotations, + * then on Android the function is only called once, and on iOS it is called for each annotation. + * + * **Known Issues** + * + * On iOS, there is currently a bug that prevents the last XFDF from being retrieved when + * modifying annotations while collaboration mode is enabled. + * @param {string} action the action that occurred (add, delete, modify) + * @param {string} xfdfCommand an xfdf string containing info about the edit + * @param {array} annotations an array of annotation data. + * When collaboration is enabled data comes in the format `{id: string}`, otherwise the format is + * `{id: string, pageNumber: number, type: string}`. + * In both cases, the data represents the annotations that have been changed. + * + * `type` is one of the {@link Config.Tools} constants. + * @example + * { + * console.log('Annotation edit action is', action); + * console.log('The exported xfdfCommand is', xfdfCommand); + * annotations.forEach((annotation) => { + * console.log('Annotation id is', annotation.id); + * if (!this.state.collabEnabled) { + * console.log('Annotation pageNumber is', annotation.pageNumber); + * console.log('Annotation type is', annotation.type); + * } + * }); + * }} + * collabEnabled={this.state.collabEnabled} + * currentUser={'Pdftron'} + * /> + */ + onExportAnnotationCommand: func<(event: { + action: string, xfdfCommand: string, + annotations: Array + }) => void>(), + + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default true + * @desc Defines whether document is automatically saved by the viewer. + * @example + * + */ autoSaveEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Page + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the viewer should change pages when the user taps the edge of a page, + * when the viewer is in a horizontal viewing mode. + * @example + * + */ pageChangeOnTap: PropTypes.bool, + + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default true + * @desc Android and iOS 13+ only + * + * Defines whether the UI will appear in a dark color when the system is dark mode. + * If false, it will use viewer setting instead. + * @example + * + */ followSystemDarkMode: PropTypes.bool, + + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default true + * @desc Defines whether a stylus should act as a pen when in pan mode. + * If false, it will act as a finger. + * @example + * + */ useStylusAsPen: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Multi-tab + * @type {boolean} + * @optional + * @default false + * @desc Defines whether viewer will use tabs in order to have more than + * one document open simultaneously (like a web browser). Changing the + * {@link DocumentView.document document} prop value will cause a new tab + * to be opened with the associated file. + * @example + * + */ multiTabEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Multi-tab + * @type {string} + * @optional + * @default the file name + * @desc Set the tab title if {@link DocumentView.multiTabEnabled multiTabEnabled} is true. + * @example + * + */ tabTitle: PropTypes.string, + + /** + * @memberof DocumentView + * @category Multi-tab + * @type {number} + * @optional + * @default unlimited + * @desc Sets the limit on the maximum number of tabs that the viewer could have at a time. + * Open more documents after reaching this limit will overwrite the old tabs. + * @example + * + */ maxTabCount: PropTypes.number, + + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default false + * @desc + * Defines whether signature fields will be signed with image stamps. + * This is useful if you are saving XFDF to remote source. + * @example + * + */ signSignatureFieldsWithStamps: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default false + * @desc Defines whether an annotation's permission flags will be respected when it is selected. + * For example, a locked annotation can not be resized or moved. + * @example + * + */ annotationPermissionCheckEnabled: PropTypes.bool, + + /** + * @type {Config.DefaultToolbars[]|object} + * @category Toolbar Customization + * @memberof DocumentView + * @optional + * @default Defaults to none. + * @desc Type can be array of {@link Config.DefaultToolbars} constants or custom toolbar objects. + * + * Defines custom toolbars. If passed in, the default toolbars will no longer appear. + * It is possible to mix and match with default toolbars. See example below. + * @example + * const myToolbar = { + * [Config.CustomToolbarKey.Id]: 'myToolbar', + * [Config.CustomToolbarKey.Name]: 'myToolbar', + * [Config.CustomToolbarKey.Icon]: Config.ToolbarIcons.FillAndSign, + * [Config.CustomToolbarKey.Items]: [Config.Tools.annotationCreateArrow, + * Config.Tools.annotationCreateCallout, Config.Buttons.undo] + * }; + * ... + * + */ annotationToolbars: PropTypes.arrayOf(PropTypes.oneOfType([ oneOf(Config.DefaultToolbars), PropTypes.exact({ @@ -102,55 +1231,765 @@ const propTypes = { ])) }) ])), + + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {Config.DefaultToolbars[]} + * @optional + * @default Defaults to none. + * @desc Defines which default annotation toolbars should be hidden. + * Note that this prop should be used when + * {@link DocumentView.annotationToolbars annotationToolbars} is not defined. + * @example + * + */ hideDefaultAnnotationToolbars: arrayOf(Config.DefaultToolbars), + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {Config.Buttons[]} + * @optional + * @desc iOS only + * + * Customizes the right bar section of the top app nav bar. + * If passed in, the default right bar section will not be used. + * @example + * + */ topAppNavBarRightBar: arrayOf(Config.Buttons), + + /** + * @memberof DocumentView + * @type {Config.Buttons[]} + * @category Toolbar Customization + * @optional + * @desc Only the outline list, thumbnail list, share, view mode, + * search, and reflow buttons are supported on Android. + * + * Defines a custom bottom toolbar. If passed in, the default bottom toolbar will not be used. + * @example + * + */ bottomToolbar: arrayOf(Config.Buttons), + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to show the toolbar switcher in the top toolbar. + * @example + * + */ hideAnnotationToolbarSwitcher: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to hide both the top app nav bar and the annotation toolbar. + * @example + * + */ hideTopToolbars: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to hide the top navigation app bar. + * @example + * + */ hideTopAppNavBar: PropTypes.bool, - onBookmarkChanged: func<(event: {bookmarkJson: string}) => void>(), + /** + * @memberof DocumentView + * @category Bookmark + * @event + * @type {function} + * @optional + * @desc This function is called if a change has been made to user bookmarks. + * @param {string} bookmarkJson the list of current bookmarks in JSON format + * @example + * { + * console.log('Bookmarks have been changed. Current bookmark collection is', bookmarkJson); + * }} + * /> + */ + onBookmarkChanged: func<(event: { bookmarkJson: string }) => void>(), + + /** + * @memberof DocumentView + * @category Thumbnails + * @type {Config.ThumbnailFilterMode[]} + * @optional + * @desc Defines filter modes that should be hidden in the thumbnails browser. + * @example + * + */ hideThumbnailFilterModes: arrayOf(Config.ThumbnailFilterMode), - onToolChanged: func<(event: {previousTool: Config.Tools | "unknown tool", tool: Config.Tools | "unknown tool"}) => void>(), + + /** + * @memberof DocumentView + * @category UI Customization + * @event + * @type {function} + * @optional + * @desc This function is called when the current tool changes to a new tool + * @param {Config.Tools|string} previousTool the previous tool + * (one of the {@link Config.Tools} constants or "unknown tool"), + * representing the tool before change + * @param {Config.Tools|string} tool the current tool (one of the {@link Config.Tools} constants + * or "unknown tool"), representing the current tool + * @example + * { + * console.log('Tool has been changed from', previousTool, 'to', tool); + * }} + * /> + */ + onToolChanged: func<(event: { + previousTool: Config.Tools | "unknown tool", + tool: Config.Tools | "unknown tool" + }) => void>(), + + /** + * @memberof DocumentView + * @category Scroll + * @type {number} + * @optional + * @desc Defines the horizontal scroll position in the current document viewer. + * @example + * + */ horizontalScrollPos: PropTypes.number, + + /** + * @memberof DocumentView + * @category Scroll + * @type {number} + * @optional + * @desc Defines the vertical scroll position in the current document viewer. + * @example + * + */ verticalScrollPos: PropTypes.number, + + /** + * @memberof DocumentView + * @category Text Selection + * @event + * @type {function} + * @optional + * @desc This function is called immediately before a text search begins, + * either through user actions, or function calls such as {@link DocumentView#findText findText}. + * @example + * { + * console.log('Text search has started'); + * }} + * /> + */ onTextSearchStart: func<() => void>(), - onTextSearchResult: func<(event: {found: boolean, textSelection: AnnotOptions.TextSelectionResult | null}) => void>(), + + /** + * @memberof DocumentView + * @category Text Selection + * @event + * @type {function} + * @optional + * @desc This function is called after a text search is finished or canceled. + * @param {boolean} found whether a result is found. + * If false, it could be caused by not finding a matching result in the document, + * invalid text input, or action cancellation + * (user actions or {@link DocumentView#cancelFindText cancelFindText}) + * @param {object} textSelection the text selection, in the format + * `{html: string, unicode: string, pageNumber: number, + * quads: [[{x: number, y: number}, {x: number, y: number}, {x: number, y: number}, + * {x: number, y: number}], ...]}`. If no such selection could be found, this would be null + * + * Quads indicate the quad boundary boxes for the selection, + * which could have a size larger than 1 if selection spans across different lines. + * Each quad have 4 points with x, y coordinates specified in number, representing a boundary box. + * The 4 points are in counter-clockwise order, though the first point is not guaranteed to be on + * lower-left relatively to the box. + * @example + * { + * if (found) { + * console.log('Found selection on page', textSelection.pageNumber); + * for (let i = 0; i < textSelection.quads.length; i ++) { + * const quad = textSelection.quads[i]; + * console.log('selection boundary quad', i); + * for (const quadPoint of quad) { + * console.log('A quad point has coordinates', quadPoint.x, quadPoint.y); + * } + * } + * } + * }} + * /> + */ + onTextSearchResult: func<(event: { + found: boolean, + textSelection: AnnotOptions.TextSelectionResult | null + }) => void>(), + + /** + * @memberof DocumentView + * @category UI Customization + * @type {Config.ViewModePickerItem[]} + * @optional + * @default Defaults to none. + * @desc Defines view mode items to be hidden in the view mode dialog. + * @example + * + */ hideViewModeItems: arrayOf(Config.ViewModePickerItem), + + /** + * @memberof DocumentView + * @category Navigation + * @type {boolean} + * @optional + * @default true + * @deprecated Use the {@link DocumentView.showQuickNavigationButton showQuickNavigationButton} + * prop instead. + * @desc Android only. + * + * Defines whether the page stack navigation buttons will appear in the viewer. + * @example + * + */ pageStackEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Navigation + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the quick navigation buttons will appear in the viewer. + * @example + * + */ showQuickNavigationButton: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Signature + * @type {boolean} + * @optional + * @default true. + * @desc Android only. + * + * Defines whether to show the option to pick images in the signature dialog. + * @example + * + */ photoPickerEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to automatically resize the bounding box of free + * text annotations when editing. + * @example + * + */ autoResizeFreeTextEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc If document editing is enabled, then this value determines + * if the annotation list is editable. + * @example + * + */ annotationsListEditingEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Navigation + * @type {boolean} + * @optional + * @default true on Android and false on iOS + * @desc Defines whether the navigation list will be displayed as a side panel + * on large devices such as iPads and tablets. + * @example + * + */ showNavigationListAsSidePanelOnLargeDevices: PropTypes.bool, + + /** + * @memberof DocumentView + * @type {boolean} + * @optional + * @default false + * @desc Defines whether to restrict data usage when viewing online PDFs. + * @example + * + */ restrictDownloadUsage: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Bookmark + * @type {boolean} + * @optional + * @default true + * @desc Defines whether the bookmark list can be edited. + * If the viewer is readonly then bookmarks on Android are + * still editable but are saved to the device rather than the PDF. + * @example + * + */ userBookmarksListEditingEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Reflow + * @type {boolean} + * @optional + * @default true + * @desc Will be available on iOS in version 9.1.2 and greater + * + * Whether to show images in reflow mode. + * @example + * + */ imageInReflowEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Reflow + * @type {Config.ReflowOrientation} + * @optional + * @default Defaults to the viewer's scroll direction + * @desc Android only. + * + * Sets the scrolling direction of the reflow control. + * @example + * + */ reflowOrientation: oneOf(Config.ReflowOrientation), + + /** + * @memberof DocumentView + * @category Undo/Redo + * @event + * @type {function} + * @optional + * @desc This function is called when the state of the current document's + * undo/redo stack has been changed. + * @example + * { + * console.log("Undo/redo stack state changed"); + * }} + * /> + */ onUndoRedoStateChanged: func<() => void>(), + + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether the tablet layout should be used on tablets. + * Otherwise uses the same layout as phones. + * @example + * + */ tabletLayoutEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Toolbar Customization + * @type {Config.DefaultToolbars|string} + * @optional + * @default Defaults to none. + * @desc Type can be one of the {@link Config.DefaultToolbars} constants + * or the `id` of a custom toolbar object. + * + * Defines which {@link DocumentView.annotationToolbars annotationToolbar} + * should be selected when the document is opened. + * @example + * + */ initialToolbar: PropTypes.string, + + /** + * @memberof DocumentView + * @category Annotations + * @type {boolean} + * @optional + * @default true + * @desc If true, ink tool will use multi-stroke mode. + * Otherwise, each stroke is a new ink annotation. + * @example + * + */ inkMultiStrokeEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Open a Document + * @type {Config.EraserType} + * @optional + * @desc Sets the default eraser tool type. Value only applied after a clean + * install. + * Eraser Type | Description + * --- | --- + * `annotationEraser` | Erases everything as an object; if you touch ink, + * the entire object is erased. + * `hybrideEraser` | Erases ink by pixel, but erases other annotation types as objects. + * `inkEraser` | Erases ink by pixel only. Android only. + * @example + * + */ defaultEraserType: oneOf(Config.EraserType), + + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @desc Android only. + * + * Sets the folder path for all save options, this defaults to the app cache path. + * Example: + * @example + * + */ exportPath: PropTypes.string, + + /** + * @memberof DocumentView + * @category Open a Document + * @type {string} + * @optional + * @desc Android only. + * + * Sets the cache folder used to cache PDF files opened using a http/https link, + * this defaults to the app cache path. + * @example + * + */ openUrlPath: PropTypes.string, + + /** + * @memberof DocumentView + * @category Annotations + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines annotation types that cannot be edited after creation. + * @example + * + */ disableEditingByAnnotationType: arrayOf(Config.Tools), + + /** + * @memberof DocumentView + * @category Scroll + * @type {boolean} + * @optional + * @default false + * @desc iOS only. + * + * Determines whether scrollbars will be hidden on the viewer. + * @example + * + */ hideScrollbars: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default true + * @desc Sets whether to remember the last visited page and zoom for a + * document if it gets opened again. + * @example + * + */ saveStateEnabled: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Open a Document + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Sets whether the new saved file should open after saving. + * @example + * + */ openSavedCopyInNewTab: PropTypes.bool, + + /** + * @memberof DocumentView + * @category Annotations + * @type {Config.Tools[]} + * @optional + * @default Defaults to none. + * @desc Defines types to be excluded from the annotation list. + * @example + * + */ excludedAnnotationListTypes: arrayOf(Config.Tools), - annotationManagerEditMode: oneOf(Config.AnnotationManagerEditMode), - annotationManagerUndoMode: oneOf(Config.AnnotationManagerUndoMode), + + /** + * @memberof DocumentView + * @category Collaboration + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether to show an annotation's reply review state. + * @example + * + */ replyReviewStateEnabled: PropTypes.bool, - onPageMoved: func<(event: {previousPageNumber: number, pageNumber: number}) => void>(), - onPagesAdded: func<(event: {pageNumbers: Array}) => void>(), - onTabChanged: func<(event: {currentTab: string}) => void>(), + + /** + * @memberof DocumentView + * @category Collaboration + * @type {Config.AnnotationManagerEditMode} + * @optional + * @default Config.AnnotationManagerEditMode.Own + * @desc Sets annotation manager edit mode when {@link DocumentView.collabEnabled collabEnabled} + * is true. + * + * Mode | Description + * --- | --- + * `Config.AnnotationManagerEditMode.Own` | In this mode, you can edit only your own changes + * `Config.AnnotationManagerEditMode.All` | In this mode, you can edit everyone's changes + * @example + * + */ + annotationManagerEditMode: + oneOf(Config.AnnotationManagerEditMode), + + /** + * @memberof DocumentView + * @category Collaboration + * @type {Config.AnnotationManagerUndoMode} + * @optional + * @default Config.AnnotationManagerUndoMode.Own + * @desc Sets annotation manager undo mode when {@link DocumentView.collabEnabled collabEnabled} + * is true. + * + * Mode | Description + * --- | --- + * `Config.AnnotationManagerUndoMode.Own` | In this mode, you can undo only your own changes + * `Config.AnnotationManagerUndoMode.All` | In this mode, you can undo everyone's changes + * @example + * + */ + annotationManagerUndoMode: + oneOf(Config.AnnotationManagerUndoMode), + + /** + * @memberof DocumentView + * @category Page + * @event + * @type {function} + * @optional + * @desc This function is called when a page has been moved in the document. + * @param {int} previousPageNumber the previous page number + * @param {int} pageNumber the current page number + * @example + * { + * console.log('Page moved from', previousPageNumber, 'to', pageNumber); + * }} + * /> + */ + onPageMoved: func<(event: { previousPageNumber: number, pageNumber: number }) => void>(), + + /** + * @memberof DocumentView + * @category Page + * @event + * @type {function} + * @optional + * @desc This function is called when pages are added to the document. + * @param {int} pageNumbers An array of the page numbers that were added to the document + * @example + * { + * console.log('Pages added:', pageNumbers); + * }} + * /> + */ + onPagesAdded: func<(event: { pageNumbers: Array }) => void>(), + /** + * @memberof DocumentView + * @category Multi-tab + * @event + * @type {function} + * @optional + * @desc The function is activated when a tab is changed. + * + * This API is meant for tab-specific changes. + * If you would like to know when the document finishes loading instead, see + * the {@link DocumentView.event:onDocumentLoaded onDocumentLoaded} event. + * @param {string} currentTab The file path of current tab's document + * @example + * { + * console.log("The current tab is ", currentTab); + * }} + * /> + */ + onTabChanged: func<(event: { currentTab: string }) => void>(), + + /** + * @memberof DocumentView + * @category UI Customization + * @type {boolean} + * @optional + * @default true + * @desc Android only. + * + * Defines whether the last tool used in the current viewer session will + * be the tool selected upon starting a new viewer session. + * @example + * + */ rememberLastUsedTool: PropTypes.bool, + + /** + * @memberof DocumentView + * @category UI Customization + * @type {string} + * @optional + * @desc The file name of the icon to be used as the overflow menu button. + * The button will use the specified icon if it is valid, and the default icon otherwise. + * + * **Note**: to add the image file to your application, follow the steps under the Note + * section of {@link DocumentView.leadingNavButtonIcon leadingNavButtonIcon}. + * @example + * let iosButton = 'ic_close_black_24px.png'; + * let androidButton = 'ic_arrow_back_white_24dp'; + * + */ overflowMenuButtonIcon: PropTypes.string, ...ViewPropTypes, }; // Generates the prop types for TypeScript users, from PropTypes. -type DocumentViewProps = PropTypes.InferProps; +export type DocumentViewProps = PropTypes.InferProps; /** * Creates a custom PropType for functions. @@ -160,17 +1999,19 @@ type DocumentViewProps = PropTypes.InferProps; * @returns {Requireable} A custom PropType constant. * @example * func<(path: string) => void>() +* @ignore */ -function func () : Requireable { - - let validator : Validator = function (props: { [key: string]: any }, propName: string, componentName: string, location: string, propFullName: string) : Error | null { +function func(): Requireable { + const validator: Validator = function (props: { [key: string]: any }, propName: string, + componentName: string, location: string, propFullName: string): Error | null { if (typeof props[propName] !== "function" && typeof props[propName] !== "undefined") { - return new Error (`Invalid prop \`${propName}\` of type \`${typeof props[propName]}\` supplied to \`${componentName}\`, expected a function.`); + return new Error(`Invalid prop \`${propName}\` of type \`${typeof props[propName]}\` + supplied to \`${componentName}\`, expected a function.`); } return null; } - - const t : Requireable = validator as Requireable; + + const t: Requireable = validator as Requireable; t.isRequired = validator as Validator>; return t; } @@ -183,8 +2024,9 @@ function func () : Requireable { * @example * oneOf(Config.Tools) * oneOf(Config.Tools, Config.Buttons) -*/ -function oneOf(obj: object, ...rest: object[]) : Requireable { + * @ignore + */ +function oneOf(obj: object, ...rest: object[]): Requireable { if (rest.length > 0) { return PropTypes.oneOf(Object.values(Object.assign({}, obj, ...rest))); } @@ -199,15 +2041,25 @@ function oneOf(obj: object, ...rest: object[]) : Requireable { * @example * arrayOf(Config.Tools) * arrayOf(Config.Tools, Config.Buttons) + * @ignore */ -function arrayOf(obj: object, ...rest: object[]) : Requireable { +function arrayOf(obj: object, ...rest: object[]): Requireable { return PropTypes.arrayOf(oneOf(obj, ...rest)) as Requireable; } +/** + * @class + * @classdesc An all-in-one React component for displaying and editing documents of different types + * such as PDF, docx, pptx, xlsx and various image formats. + * + * Due to the length of the source file, we have included links to the exact lines of the source + * code where these APIs have been implemented. + * @hideconstructor + */ export class DocumentView extends PureComponent { _viewerRef: any; - static propTypes = propTypes; + static propTypes = Object.assign(DocumentViewPropTypes, { ...ViewPropTypes }); onChange = (event: any) => { if (event.nativeEvent.onLeadingNavButtonPressed) { @@ -221,27 +2073,27 @@ export class DocumentView extends PureComponent { } else if (event.nativeEvent.onPageChanged) { if (this.props.onPageChanged) { this.props.onPageChanged({ - 'previousPageNumber': event.nativeEvent.previousPageNumber, - 'pageNumber': event.nativeEvent.pageNumber, + 'previousPageNumber': event.nativeEvent.previousPageNumber, + 'pageNumber': event.nativeEvent.pageNumber, }); } } else if (event.nativeEvent.onScrollChanged) { if (this.props.onScrollChanged) { this.props.onScrollChanged({ - 'horizontal': event.nativeEvent.horizontal, - 'vertical': event.nativeEvent.vertical, + 'horizontal': event.nativeEvent.horizontal, + 'vertical': event.nativeEvent.vertical }); - } + } } else if (event.nativeEvent.onZoomChanged) { if (this.props.onZoomChanged) { this.props.onZoomChanged({ - 'zoom': event.nativeEvent.zoom, + 'zoom': event.nativeEvent.zoom }); } } else if (event.nativeEvent.onZoomFinished) { if (this.props.onZoomFinished) { this.props.onZoomFinished({ - 'zoom': event.nativeEvent.zoom, + 'zoom': event.nativeEvent.zoom }); } } else if (event.nativeEvent.onLayoutChanged) { @@ -262,11 +2114,11 @@ export class DocumentView extends PureComponent { }); } } else if (event.nativeEvent.onAnnotationsSelected) { - if (this.props.onAnnotationsSelected) { - this.props.onAnnotationsSelected({ - 'annotations': event.nativeEvent.annotations, - }); - } + if (this.props.onAnnotationsSelected) { + this.props.onAnnotationsSelected({ + 'annotations': event.nativeEvent.annotations, + }); + } } else if (event.nativeEvent.onFormFieldValueChanged) { if (this.props.onFormFieldValueChanged) { this.props.onFormFieldValueChanged({ @@ -283,7 +2135,8 @@ export class DocumentView extends PureComponent { if (this.props.onDocumentError) { this.props.onDocumentError(event.nativeEvent.onDocumentError); } else { - const msg = event.nativeEvent.onDocumentError ? event.nativeEvent.onDocumentError : 'Unknown error'; + const error = 'Unknown error'; + const msg = event.nativeEvent.onDocumentError ? event.nativeEvent.onDocumentError : error; Alert.alert( 'Alert', msg, @@ -319,20 +2172,20 @@ export class DocumentView extends PureComponent { if (this.props.onBehaviorActivated) { this.props.onBehaviorActivated({ 'action': event.nativeEvent.action, - 'data': event.nativeEvent.data, + 'data': event.nativeEvent.data }); } } else if (event.nativeEvent.onBookmarkChanged) { if (this.props.onBookmarkChanged) { this.props.onBookmarkChanged({ - 'bookmarkJson': event.nativeEvent.bookmarkJson, + 'bookmarkJson': event.nativeEvent.bookmarkJson }); } } else if (event.nativeEvent.onToolChanged) { if (this.props.onToolChanged) { this.props.onToolChanged({ 'previousTool': event.nativeEvent.previousTool, - 'tool': event.nativeEvent.tool, + 'tool': event.nativeEvent.tool }); } } else if (event.nativeEvent.onTextSearchStart) { @@ -343,7 +2196,7 @@ export class DocumentView extends PureComponent { if (this.props.onTextSearchResult) { this.props.onTextSearchResult({ 'found': event.nativeEvent.found, - 'textSelection': event.nativeEvent.textSelection, + 'textSelection': event.nativeEvent.textSelection }); } } else if (event.nativeEvent.onUndoRedoStateChanged) { @@ -354,7 +2207,7 @@ export class DocumentView extends PureComponent { if (this.props.onPageMoved) { this.props.onPageMoved({ 'previousPageNumber': event.nativeEvent.previousPageNumber, - 'pageNumber': event.nativeEvent.pageNumber, + 'pageNumber': event.nativeEvent.pageNumber }); } } else if (event.nativeEvent.onPagesAdded) { @@ -366,7 +2219,7 @@ export class DocumentView extends PureComponent { } else if (event.nativeEvent.onTabChanged) { if (this.props.onTabChanged) { this.props.onTabChanged({ - 'currentTab' : event.nativeEvent.currentTab + 'currentTab': event.nativeEvent.currentTab }); } } @@ -374,6 +2227,19 @@ export class DocumentView extends PureComponent { // Methods + /** + * @method + * @category Document + * @desc Returns the path of the current document. + * If {@link DocumentView.isBase64String isBase64String} is true, + * this would be the path to the temporary pdf file converted from + * the base64 string in {@link DocumentView.document document}. + * @returns {Promise} path - the document path. + * @example + * this._viewer.getDocumentPath().then((path) => { + * console.log('The path to current document is: ' + path); + * }); + */ getDocumentPath = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -381,16 +2247,37 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); } - + /** + * @method + * @category Annotation Tools + * @desc Sets the current tool mode. + * @param {Config.Tools} toolMode the tool mode to set. + * @returns {Promise} + * @example + * this._viewer.setToolMode(Config.Tools.annotationCreateFreeHand).then(() => { + * // done switching tools + * }); + */ setToolMode = (toolMode: Config.Tools): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.setToolMode(tag, toolMode); + return DocumentViewManager.setToolMode(tag, toolMode); } return Promise.resolve(); } + /** + * @method + * @category Annotation Tools + * @desc Commits the current tool, only available for multi-stroke ink and poly-shape. + * @returns {Promise} committed - true if either ink or poly-shape tool is + * committed, false otherwise + * @example + * this._viewer.commitTool().then((committed) => { + * // committed: true if either ink or poly-shape tool is committed, false otherwise + * }); + */ commitTool = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -399,6 +2286,16 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Gets the current page count of the document. + * @returns {Promise} pageCount - the current page count of the document + * @example + * this._viewer.getPageCount().then((pageCount) => { + * console.log('pageCount', pageCount); + * }); + */ getPageCount = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -407,6 +2304,17 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Bookmark + * @desc Imports user bookmarks into the document. + * The input needs to be a valid bookmark JSON format. + * @param {string} bookmarkJson needs to be in valid bookmark JSON format, + * for example {"0": "Page 1"}. The page numbers are 1-indexed + * @returns {Promise} + * @example + * this._viewer.importBookmarkJson("{\"0\": \"Page 1\", \"3\": \"Page 4\"}"); + */ importBookmarkJson = (bookmarkJson: string): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -414,7 +2322,16 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); } - + + /** + * @method + * @category Bookmark + * @desc Displays the bookmark tab of the existing list container. + * If this tab has been disabled, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openBookmarkList(); + */ openBookmarkList = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -423,6 +2340,23 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Import/Export Annotations + * @desc Imports remote annotation command to local document. + * @param {string} xfdfCommand the XFDF command string + * @param {boolean} [initialLoad=false] whether this is for initial load. + * @returns {Promise} + * @example + * const xfdfCommand = '' + + * '' + + * '' + + * ''; + * this._viewer.importAnnotationCommand(xfdfCommand); + */ importAnnotationCommand = (xfdfCommand: string, initialLoad?: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -432,12 +2366,28 @@ export class DocumentView extends PureComponent { return DocumentViewManager.importAnnotationCommand( tag, xfdfCommand, - initialLoad, + initialLoad ); } return Promise.resolve(); } + /** + * @method + * @category Import/Export Annotations + * @desc Imports XFDF annotation string to the current document. + * @param {string} xfdf annotation string in XFDF format for import + * @returns {Promise} + * @example + * const xfdf = '\n' + + * '\n\t\n\t\t' + + * '\n\t\n\t\t' + + * '\n\t' + + * '\n\t\n'; + * this._viewer.importAnnotations(xfdf); + */ importAnnotations = (xfdf: string): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -446,7 +2396,27 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - exportAnnotations = (options?: {annotList: Array}): Promise => { + /** + * @method + * @category Import/Export Annotations + * @desc Extracts XFDF from the current document. + * @param {object} options key: annotList, type: array. + * If specified, annotations with the matching id and pageNumber will be exported; + * otherwise, all annotations in the current document will be exported. + * @returns {Promise} xfdf - annotation string in XFDF format + * @example Without options: + * this._viewer.exportAnnotations().then((xfdf) => { + * console.log('XFDF for all annotations:', xfdf); + * }); + * @example With options: + * // annotList is an array of annotation data in the format {id: string, pageNumber: int} + * const annotations = [{id: 'annot1', pageNumber: 1}, {id: 'annot2', pageNumber: 3}]; + * this._viewer.exportAnnotations({annotList: annotations}).then((xfdf) => { + * console.log('XFDF for 2 specified annotations', xfdf); + * }); + */ + exportAnnotations = (options?: { annotList: Array }) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.exportAnnotations(tag, options); @@ -454,6 +2424,17 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Annotations + * @desc Flattens the forms and (optionally) annotations in the current document. + * @param {boolean} formsOnly Defines whether only forms are flattened. + * If false, all annotations will be flattened. + * @returns {Promise} + * @example + * // flatten forms and annotations in the current document. + * this._viewer.flattenAnnotations(false); + */ flattenAnnotations = (formsOnly: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -462,6 +2443,26 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Annotations + * @desc Deletes the specified annotations in the current document. + * @param {object[]} annotations Defines which annotation to be deleted. + * Each element is in the format {id: string, pageNumber: int} + * @returns {Promise} + * @example + * // delete annotations in the current document. + * this._viewer.deleteAnnotations([ + * { + * id: 'annotId1', + * pageNumber: 1, + * }, + * { + * id: 'annotId2', + * pageNumber: 2, + * } + * ]); + */ deleteAnnotations = (annotations: Array): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -470,6 +2471,20 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Document + * @desc Saves the current document. + * If {@link DocumentView.isBase64String isBase64String} is true, + * this would be the base64 string encoded from the temporary pdf file, + * which is created from the base64 string in {@link DocumentView.document document}. + * @returns {Promise} filePath - the location of the saved document, + * or the base64 string of the pdf in the case of base64 + * @example + * this._viewer.saveDocument().then((filePath) => { + * console.log('saveDocument:', filePath); + * }); + */ saveDocument = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -478,46 +2493,119 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - setFlagForFields = (fields: Array, flag: Config.FieldFlags, value: boolean): Promise => { + /** + * @method + * @category Annotations + * @desc Sets a field flag value on one or more form fields. + * @param {string[]} fields list of field names for which the flag should be set + * @param {Config.FieldFlags} flag flag to be set + * @param {boolean} value value to set for flag + * @returns {Promise} + * @example + * this._viewer.setFlagForFields(['First Name', 'Last Name'], Config.FieldFlags.ReadOnly, true); + */ + setFlagForFields = (fields: Array, flag: Config.FieldFlags, value: boolean) + : Promise => { const tag = findNodeHandle(this._viewerRef); - if(tag != null) { + if (tag != null) { return DocumentViewManager.setFlagForFields(tag, fields, flag, value); } return Promise.resolve(); } - getField = (fieldName: string): Promise => { + /** + * @method + * @category Annotations + * @desc Get type and value information of a field using its name. + * @param {string} fieldName name of the field + * @returns {Promise} field - an object with information keys: + * `fieldName`, `fieldValue` (undefined for fields with no values) and + * `fieldType`(one of button, checkbox, radio, text, choice, signature and unknown), + * or undefined if such field does not exist + * + * @example + * this._viewer.getField('someFieldName').then((field) => { + * if (field !== undefined) { + * console.log('field name:', field.fieldName); + * console.log('field value:', field.fieldValue); + * console.log('field type:', field.fieldType); + * } + * }); + */ + getField = (fieldName: string) + : Promise => { const tag = findNodeHandle(this._viewerRef); - if(tag != null) { + if (tag != null) { return DocumentViewManager.getField(tag, fieldName); } return Promise.resolve(); } + /** + * @method + * @category Annotations + * @desc Displays the annotation tab of the existing list container. + * If this tab has been disabled, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openAnnotationList(); + */ openAnnotationList = (): Promise => { const tag = findNodeHandle(this._viewerRef); - if(tag != null) { + if (tag != null) { return DocumentViewManager.openAnnotationList(tag); } return Promise.resolve(); } /** - * note: this function exists for supporting the old version. It simply calls setValuesForFields. - * + * @method + * @deprecated Note: this function exists for supporting the old version. + * It simply calls {@link DocumentView#setValuesForFields setValuesForFields}. + * @ignore */ - setValueForFields = (fieldsMap: Record): Promise => { + setValueForFields = (fieldsMap: Record): Promise => { return this.setValuesForFields(fieldsMap); } + /** + * @method + * @category Annotations + * @desc Sets field values on one or more form fields. + * + * Note: the old function `setValueForFields` is deprecated. Please use this one instead. + * @param {object} fieldsMap map of field names and values which should be set + * @returns {Promise} + * @example + * this._viewer.setValuesForFields({ + * 'textField1': 'Test', + * 'textField2': 1234, + * 'checkboxField1': true, + * 'checkboxField2': false, + * 'radioButton1': 'Yes', + * 'radioButton2': 'No' + * }); + */ setValuesForFields = (fieldsMap: Record): Promise => { const tag = findNodeHandle(this._viewerRef); - if(tag != null) { + if (tag != null) { return DocumentViewManager.setValuesForFields(tag, fieldsMap); } return Promise.resolve(); } + /** + * @method + * @category Navigation + * @desc Handles the back button in search mode. Android only. + * @returns {Promise} handled - whether the back button is handled successfully + * @example + * this._viewer.handleBackButton().then((handled) => { + * if (!handled) { + * BackHandler.exitApp(); + * } + * }); + */ handleBackButton = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -526,16 +2614,49 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - /** - * note: this function exists for supporting the old version. It simply calls setFlagsForAnnotations. - * + * @method + * @deprecated Note: this function exists for supporting the old version. + * It simply calls {@link DocumentView#setFlagsForAnnotations setFlagsForAnnotations}. + * @ignore */ - setFlagForAnnotations = (annotationFlagList: Array): Promise => { - return this.setFlagsForAnnotations(annotationFlagList); + setFlagForAnnotations = (annotationFlagList: Array) + : Promise => { + return this.setFlagsForAnnotations(annotationFlagList); } - - setFlagsForAnnotations = (annotationFlagList: Array): Promise => { + + /** + * @method + * @category Annotations + * @desc Sets flags for specified annotations in the current document. + * The `flagValue` controls whether a flag will be set to or removed from the annotation. + * + * Note: the old function `setFlagForAnnotations` is deprecated. Please use this one. + * + * @param {object[]} annotationFlagList A list of annotation flag operations. + * Each element is in the format + * `{id: string, pageNumber: int, + * flag: One of {@link Config.AnnotationFlags} constants, flagValue: boolean}` + * @returns {Promise} + * @example + * // Set flag for annotations in the current document. + * this._viewer.setFlagsForAnnotations([ + * { + * id: 'annotId1', + * pageNumber: 1, + * flag: Config.AnnotationFlags.noView, + * flagValue: true + * }, + * { + * id: 'annotId2', + * pageNumber: 5, + * flag: Config.AnnotationFlags.lockedContents, + * flagValue: false + * } + * ]); + */ + setFlagsForAnnotations = (annotationFlagList: Array) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.setFlagsForAnnotations(tag, annotationFlagList); @@ -543,6 +2664,18 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Annotations + * @desc Selects the specified annotation in the current document. + * @param {string} id the id of the target annotation + * @param {integer} pageNumber the page number where the targe annotation is located. + * It is 1-indexed. + * @returns {Promise} + * @example + * // select annotation in the current document. + * this._viewer.selectAnnotation('annotId1', 1); + */ selectAnnotation = (id: string, pageNumber: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -552,14 +2685,67 @@ export class DocumentView extends PureComponent { } /** - * note: this function exists for supporting the old version. It simply calls setPropertiesForAnnotation. - * + * @method + * @deprecated Note: this function exists for supporting the old version. + * It simply calls setPropertiesForAnnotation. + * @ignore */ - setPropertyForAnnotation = (id: string, pageNumber: number, propertyMap: AnnotOptions.AnnotationProperties): Promise => { + setPropertyForAnnotation = (id: string, pageNumber: number, + propertyMap: AnnotOptions.AnnotationProperties): Promise => { return this._viewerRef.setPropertiesForAnnotation(id, pageNumber, propertyMap); } - setPropertiesForAnnotation = (id: string, pageNumber: number, propertyMap: AnnotOptions.AnnotationProperties): Promise => { + /** + * @method + * @category Annotations + * @desc Sets properties for specified annotation in the current document, if it is valid. + * + * Note: the old function `setPropertyForAnnotation` is deprecated. Please use this one. + * + * @param {string} annotationId the unique id of the annotation + * @param {integer} pageNumber the page number where annotation is located. It is 1-indexed + * @param {object} propertyMap an object containing properties to be set. + * Available properties are listed below. + * + * Properties in propertyMap: + * + * Name | Type | Markup exclusive | Example + * --- | --- | --- | --- + * rect | object | no | {x1: 1, y1: 2, x2: 3, y2: 4} + * contents | string | no | "contents" + * subject | string | yes | "subject" + * title | string | yes | "title" + * contentRect | object | yes | {x1: 1, y1: 2, x2: 3, y2: 4} + * customData | object | no | {key: value} + * strokeColor | object | no | {red: 255, green: 0, blue: 0} + * + * @returns {Promise} + * @example + * // Set properties for annotation in the current document. + * this._viewer.setPropertiesForAnnotation('Pdftron', 1, { + * rect: { + * x1: 1.1, // left + * y1: 3, // bottom + * x2: 100.9, // right + * y2: 99.8 // top + * }, + * contents: 'Hello World', + * subject: 'Sample', + * title: 'set-prop-for-annot', + * customData: { + * key1: 'value1', + * key2: 'value2', + * key3: 'value3' + * }, + * strokeColor: { + * "red": 255, + * "green": 0, + * "blue": 0 + * } + * }); + */ + setPropertiesForAnnotation = (id: string, pageNumber: number, + propertyMap: AnnotOptions.AnnotationProperties): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.setPropertiesForAnnotation(tag, id, pageNumber, propertyMap); @@ -567,7 +2753,33 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - getPropertiesForAnnotation = (id: string, pageNumber: number): Promise => { + /** + * @method + * @category Annotations + * @desc Gets properties for specified annotation in the current document, if it is valid. + * + * @param {string} annotationId the unique id of the annotation + * @param {integer} pageNumber the page number where annotation is located. It is 1-indexed + * @returns {Promise} propertyMap - the non-null properties of the annotation + * + * Name | Type | Markup exclusive | Example + * --- | --- | --- | --- + * rect | object | no | {x1: 1, y1: 1, x2: 2, y2: 2, width: 1, height: 1} + * contents | string | no | "Contents" + * subject | string | yes | "Subject" + * title | string | yes | "Title" + * contentRect | object | yes | {x1: 1, y1: 1, x2: 2, y2: 2, width: 1, height: 1} + * strokeColor | object | no | {red: 255, green: 0, blue: 0} + * @example + * // Get properties for annotation in the current document. + * this._viewer.getPropertiesForAnnotation('Pdftron', 1).then((properties) => { + * if (properties) { + * console.log('Properties for annotation: ', properties); + * } + * }) + */ + getPropertiesForAnnotation = (id: string, pageNumber: number) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.getPropertiesForAnnotation(tag, id, pageNumber); @@ -575,6 +2787,19 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Annotations + * @desc Sets whether all annotations and forms should be rendered. + * This method affects the viewer and does not change the document. + * + * Unlike {@link DocumentView#setVisibilityForAnnotation setVisibilityForAnnotation}, + * this method is used to show and hide all annotations and forms in the viewer. + * @param {boolean} drawAnnotations whether all annotations and forms should be rendered + * @returns {Promise} + * @example + * this._viewer.setDrawAnnotations(false); + */ setDrawAnnotations = (drawAnnotations: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -583,14 +2808,38 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - setVisibilityForAnnotation = (id: string, pageNumber: number, visibility: boolean): Promise => { + /** + * @method + * @category Annotations + * @desc Sets visibility for specified annotation in the current document, if it is valid. + * Note that if {@link DocumentView#setDrawAnnotations drawAnnotations} + * is set to false in the viewer, this function would not render the annotation even + * if visibility is true. + * + * @param {string} annotationId the unique id of the annotation + * @param {integer}pageNumber the page number where annotation is located. It is 1-indexed + * @param {boolean }visibility whether the annotation should be visible + * @returns {Promise} + * @example + * this._viewer.setVisibilityForAnnotation('Pdftron', 1, true); + */ + setVisibilityForAnnotation = (id: string, pageNumber: number, visibility: boolean) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { DocumentViewManager.setVisibilityForAnnotation(tag, id, pageNumber, visibility); } return Promise.resolve(); } - + + /** + * @method + * @category Annotations + * @desc Enables or disables highlighting form fields. It is disabled by default. + * @param {boolean} highlightFields whether form fields should be highlighted + * @example + * this._viewer.setHighlightFields(true); + */ setHighlightFields = (highlightFields: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -599,7 +2848,35 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - getAnnotationAtPoint = (x: number, y: number, distanceThreshold: number, minimumLineWeight: number): Promise => { + /** + * @method + * @category Annotations + * @desc Gets an annotation at the (x, y) position in screen coordinates, if any. + * @param {integer} x the x-coordinate of the point + * @param {integer} y the y-coordinate of the point + * @param {double} distanceThreshold maximum distance from the point (x, y) + * to the annotation for it to be considered a hit (in dp) + * @param {double} minimumLineWeight For very thin lines, + * it is almost impossible to hit the actual line. + * This specifies a minimum line thickness (in screen coordinates) for the purpose of calculating + * whether a point is inside the annotation or not (in dp) + * @returns {Promise} annotation - the annotation found in the format of + * `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * this._viewer.getAnnotationAtPoint(167, 287, 100, 10).then((annotation) => { + * if (annotation) { + * console.log('Annotation found at point (167, 287) has id:', annotation.id); + * } + * }) + */ + getAnnotationAtPoint = (x: number, y: number, distanceThreshold: number, + minimumLineWeight: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.getAnnotationAt(tag, x, y, distanceThreshold, minimumLineWeight); @@ -607,7 +2884,34 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - getAnnotationListAt = (x1: number, y1: number, x2: number, y2: number): Promise> => { + /** + * @method + * @category Annotations + * @desc Gets the list of annotations at a given line in screen coordinates. + * Note that this is not an area selection. It should be used similar + * to {@link DocumentView#getAnnotationAtPoint getAnnotationAtPoint}, except that this should + * be used when you want to get multiple annotations which are overlaying with each other. + * @param {integer} x1 x-coordinate of an endpoint on the line + * @param {integer} y1 y-coordinate of an endpoint on the line + * @param {integer} x2 x-coordinate of the other endpoint on the line, usually used as a threshold + * @param {integer} y2 y-coordinate of the other endpoint on the line, usually used as a threshold + * @returns {Promise} annotations - list of annotations at the target line, + * each in the format of `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * this._viewer.getAnnotationListAt(0, 0, 200, 200).then((annotations) => { + * for (const annotation of annotations) { + * console.log('Annotation found at line has id:', annotation.id); + * } + * }) + */ + getAnnotationListAt = (x1: number, y1: number, x2: number, y2: number) + : Promise> => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.getAnnotationListAt(tag, x1, y1, x2, y2); @@ -615,6 +2919,26 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Annotations + * @desc Gets the list of annotations on a given page. + * @param {integer} pageNumber the page number where annotations are located. It is 1-indexed + * @returns {Promise>} annotations - list of annotations on the target page, + * each in the format of `{id: string, pageNumber: number, type: string, + * screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, + * pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. + * + * `type` is one of the {@link Config.Tools} constants. + * + * `screenRect` was formerly called `rect`. + * @example + * this._viewer.getAnnotationsOnPage(2).then((annotations) => { + * for (const annotation of annotations) { + * console.log('Annotation found on page 2 has id:', annotation.id); + * } + * }) + */ getAnnotationsOnPage = (pageNumber: number): Promise> => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -623,7 +2947,28 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - getCustomDataForAnnotation = (annotationID: string, pageNumber: number, key: string): Promise => { + /** + * @method + * @category Annotations + * @desc Gets an annotation's `customData` property. + * @param {string} annotationId the unique id of the annotation + * @param {integer} pageNumber the page number where annotation is located. It is 1-indexed + * @param {string} key the unique key associated with the `customData` property + * @returns {Promise} value - the `customData` property associated + * with the given key + * @example + * this._viewer.setPropertiesForAnnotation("annotation1", 2, { + * customData: { + * data: "Nice annotation" + * } + * }).then(() => { + * this._viewer.getCustomDataForAnnotation("annotation1", 2, "data").then((value) => { + * console.log(value === "Nice annotation"); + * }) + * }) + */ + getCustomDataForAnnotation = (annotationID: string, pageNumber: number, key: string) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.getCustomDataForAnnotation(tag, annotationID, pageNumber, key); @@ -631,6 +2976,20 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Gets the crop box for specified page as a JSON object. + * @param {integer} pageNumber the page number for the target crop box. It is 1-indexed + * @returns {Promise} cropBox - an object with information about position + * (`x1`, `y1`, `x2` and `y2`) and size (`width` and `height`) + * @example + * this._viewer.getPageCropBox(1).then((cropBox) => { + * console.log('bottom-left coordinate:', cropBox.x1, cropBox.y1); + * console.log('top-right coordinate:', cropBox.x2, cropBox.y2); + * console.log('width and height:', cropBox.width, cropBox.height); + * }); + */ getPageCropBox = (pageNumber: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -639,6 +2998,19 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Sets current page of the document. + * @param {integer} pageNumber the page number to be set as the current page; 1-indexed + * @returns {Promise} success - whether the setting process was successful + * @example + * this._viewer.setCurrentPage(4).then((success) => { + * if (success) { + * console.log("Current page is set to 4."); + * } + * }); + */ setCurrentPage = (pageNumber: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -647,6 +3019,19 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Gets the visible pages in the current viewer as an array. + * @returns {Promise>} visiblePages - a list of visible pages in the + * current viewer + * @example + * this._viewer.getVisiblePages().then((visiblePages) => { + * for (const page of visiblePages) { + * console.log('page', page, 'is visible.') + * } + * }); + */ getVisiblePages = (): Promise> => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -655,6 +3040,19 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Go to the previous page of the document. If on first page, it will stay on first page. + * @returns {Promise} success - whether the setting process was successful + * (no change due to staying in first page counts as being successful) + * @example + * this._viewer.gotoPreviousPage().then((success) => { + * if (success) { + * console.log("Go to previous page."); + * } + * }); + */ gotoPreviousPage = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -663,6 +3061,19 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Go to the next page of the document. If on last page, it will stay on last page. + * @returns {Promise} success - whether the setting process was successful + * (no change due to staying in last page counts as being successful) + * @example + * this._viewer.gotoNextPage().then((success) => { + * if (success) { + * console.log("Go to next page."); + * } + * }); + */ gotoNextPage = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -671,6 +3082,18 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Go to the first page of the document. + * @returns {Promise} success - whether the setting process was successful + * @example + * this._viewer.gotoFirstPage().then((success) => { + * if (success) { + * console.log("Go to first page."); + * } + * }); + */ gotoFirstPage = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -679,6 +3102,18 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Go to the last page of the document. + * @returns {Promise} success - whether the setting process was successful + * @example + * this._viewer.gotoLastPage().then((success) => { + * if (success) { + * console.log("Go to last page."); + * } + * }); + */ gotoLastPage = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -687,6 +3122,15 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Opens a go-to page dialog. If the user inputs a valid page number into the dialog, + * the viewer will go to that page. + * @returns {Promise} + * @example + * this._viewer.showGoToPageView(); + */ showGoToPageView = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -695,6 +3139,15 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Multi-tab + * @desc Closes all tabs in a multi-tab environment. + * @returns {Promise} + * @example + * // Do this only when DocumentView has multiTabEnabled = true + * this._viewer.closeAllTabs(); + */ closeAllTabs = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -703,6 +3156,15 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Multi-tab + * @desc Opens the tab switcher in a multi-tab environment. + * @returns {Promise} + * @example + * // Do this only when DocumentView has multiTabEnabled = true + * this._viewer.openTabSwitcher(); + */ openTabSwitcher = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -711,6 +3173,16 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Zoom + * @desc Returns the current zoom scale of current document viewer. + * @returns {Promise} zoom - current zoom scale in the viewer + * @example + * this._viewer.getZoom().then((zoom) => { + * console.log('Zoom scale of the current document is:', zoom); + * }); + */ getZoom = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -719,7 +3191,20 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - setZoomLimits = (zoomLimitMode: Config.ZoomLimitMode, minimum: number, maximum: number): Promise => { + /** + * @method + * @category Zoom + * @desc Sets the minimum and maximum zoom bounds of current viewer. + * @param {Config.ZoomLimitMode} zoomLimitMode defines whether bounds are relative to the + * standard zoom scale in the current viewer or absolute + * @param {double} minimum the lower bound of the zoom limit range + * @param {double} maximum the upper bound of the zoom limit range + * @returns {Promise} + * @example + * this._viewer.setZoomLimits(Config.ZoomLimitMode.Absolute, 1.0, 3.5); + */ + setZoomLimits = (zoomLimitMode: Config.ZoomLimitMode, minimum: number, maximum: number) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.setZoomLimits(tag, zoomLimitMode, minimum, maximum); @@ -727,6 +3212,17 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Zoom + * @desc Sets the zoom scale in the current document viewer with a zoom center. + * @param {double} zoom the zoom ratio to be set + * @param {int} x the x-coordinate of the zoom center + * @param {int} y the y-coordinate of the zoom center + * @returns {Promise} + * @example + * this._viewer.zoomWithCenter(3.0, 100, 300); + */ zoomWithCenter = (zoom: number, x: number, y: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -735,6 +3231,17 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Zoom + * @desc Zoom the viewer to a specific rectangular area in a page. + * @param {int} pageNumber the page number of the zooming area (1-indexed) + * @param {object} rect The rectangular area with keys + * `x1` (left), `y1` (bottom), `y1` (right), `y2` (top). Coordinates are in double + * @returns {Promise} + * @example + * this._viewer.zoomToRect(3, {'x1': 1.0, 'y1': 2.0, 'x2': 3.0, 'y2': 4.0}); + */ zoomToRect = (pageNumber: number, rect: AnnotOptions.Rect): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -743,6 +3250,18 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Zoom + * @desc Zoom to a paragraph that contains the specified coordinate. + * If no paragraph contains the coordinate, the zooming would not happen. + * @param {int} x the x-coordinate of the target coordinate + * @param {int} y the y-coordinate of the target coordinate + * @param {boolean} animated whether the transition is animated + * @returns {Promise} + * @example + * this._viewer.smartZoom(100, 200, true); + */ smartZoom = (x: number, y: number, animated: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -750,16 +3269,50 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); } - - getScrollPos = (): Promise => { + + /** + * @method + * @category Scroll + * @desc Returns the horizontal and vertical scroll position of current document viewer. + * @returns {Promise} + * + * Name | Type | Description + * --- | --- | --- + * horizontal | number | current horizontal scroll position + * vertical | number | current vertical scroll position + * + * @example + * this._viewer.getScrollPos().then(({horizontal, vertical}) => { + * console.log('Current horizontal scroll position is:', horizontal); + * console.log('Current vertical scroll position is:', vertical); + * }); + */ + getScrollPos = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.getScrollPos(tag); } return Promise.resolve(); } - - getCanvasSize = (): Promise => { + + /** + * @method + * @category Canvas + * @desc Returns the canvas size of current document viewer. + * @returns {Promise} + * + * Name | Type | Description + * --- | --- | --- + * width | number | current width of canvas + * height | number | current height of canvas + * + * @example + * this._viewer.getCanvasSize().then(({width, height}) => { + * console.log('Current canvas width is:', width); + * console.log('Current canvas height is:', height); + * }); + */ + getCanvasSize = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.getCanvasSize(tag); @@ -767,6 +3320,17 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Gets the rotation value of all pages in the current document. + * @returns {Promise} pageRotation - the rotation degree of all pages, + * one of 0, 90, 180 or 270 (clockwise). + * @example + * this._viewer.getPageRotation().then((pageRotation) => { + * console.log('The current page rotation degree is' + pageRotation); + * }); + */ getPageRotation = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -775,6 +3339,14 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Rotates all pages in the current document in clockwise direction (by 90 degrees). + * @returns {Promise} + * @example + * this._viewer.rotateClockwise(); + */ rotateClockwise = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -783,6 +3355,14 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Rotates all pages in the current document in counter-clockwise direction (by 90 degrees). + * @returns {Promise} + * @example + * this._viewer.rotateCounterClockwise(); + */ rotateCounterClockwise = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -791,8 +3371,27 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - - convertScreenPointsToPagePoints = (points: Array): Promise> => { + /** + * @method + * @category Coordinate + * @desc Converts points from screen coordinates to page coordinates in the viewer. + * @param {object[]} points list of points, each in the format `{x: number, y: number}`. + * You could optionally have a `pageNumber: number` in the object. + * Without specifying, the page system is referring to the current page + * @returns {Promise} convertedPoints - list of converted points in page system, + * each in the format `{x: number, y: number}`. It would be empty if conversion is unsuccessful + * @example + * // convert (50, 50) and (100, 100) from screen system to page system, + * // on current page and page 1 respectively + * this._viewer.convertScreenPointsToPagePoints([{x: 50, y: 50}, {x: 100, y:100, pageNumber: 1}]) + * .then((convertedPoints) => { + * convertedPoints.forEach(point => { + * console.log(point); + * }) + * }); + */ + convertScreenPointsToPagePoints = (points: Array) + : Promise> => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.convertScreenPointsToPagePoints(tag, points); @@ -800,7 +3399,27 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - convertPagePointsToScreenPoints = (points: Array): Promise> => { + /** + * @method + * @category Coordinate + * @desc Converts points from page coordinates to screen coordinates in the viewer. + * @param {object[]} points list of points, each in the format `{x: number, y: number}`. + * You could optionally have a `pageNumber: number` in the object. + * Without specifying, the page system is referring to the current page + * @returns {Promise} convertedPoints - list of converted points in + * screen system, each in the format `{x: number, y: number}`. + * It would be empty if conversion is unsuccessful + * @example + * // convert (50, 50) on current page and (100, 100) on page 1 from page system to screen system + * this._viewer.convertPagePointsToScreenPoints([{x: 50, y: 50}, {x: 100, y:100, pageNumber: 1}]) + * .then((convertedPoints) => { + * convertedPoints.forEach(point => { + * console.log(point); + * }) + * }); + */ + convertPagePointsToScreenPoints = (points: Array) + : Promise> => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.convertPagePointsToScreenPoints(tag, points); @@ -808,6 +3427,18 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Coordinate + * @desc Returns the page number that contains the point on screen. + * @param {number} x the x-coordinate of the screen point + * @param {number} y the y-coordinate of the screen point + * @returns {Promise} pageNumber - the page number of the screen point + * @example + * this._viewer.getPageNumberFromScreenPoint(10.0,50.5).then((pageNumber) => { + * console.log('The page number of the screen point is', pageNumber); + * }); + */ getPageNumberFromScreenPoint = (x: number, y: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -816,14 +3447,41 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - setProgressiveRendering = (progressiveRendering: boolean, initialDelay: number, interval: number): Promise => { + /** + * @method + * @category Rendering Options + * @desc Sets whether the control will render progressively + * or will just draw once the entire view has been rendered. + * @param {boolean} progressiveRendering whether to render progressively + * @param {number} initialDelay delay before the progressive rendering timer is started, + * in milliseconds + * @param {number} interval delay between refreshes, in milliseconds + * @returns {Promise} + * @example + * // delay for 10s before start, and refresh every 1s + * this._viewer.setProgressiveRendering(true, 10000, 1000); + */ + setProgressiveRendering = (progressiveRendering: boolean, initialDelay: number, interval: number) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.setProgressiveRendering(tag, progressiveRendering, initialDelay, interval); + return DocumentViewManager.setProgressiveRendering(tag, progressiveRendering, + initialDelay, interval); } return Promise.resolve(); } + /** + * @method + * @category Rendering Options + * @desc Enables or disables image smoothing. + * The rasterizer allows a trade-off between rendering quality and rendering speed. + * This function can be used to indicate the preference between rendering speed and quality. + * @param {boolean} imageSmoothing whether to enable image smoothing + * @returns {Promise} + * @example + * this._viewer.setImageSmoothing(false); + */ setImageSmoothing = (imageSmoothing: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -832,6 +3490,17 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Rendering Options + * @desc Enables or disables support for overprint and overprint simulation. + * Overprint is a device dependent feature and the results will vary depending + * on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc). + * @param {Config.OverprintMode} overprint the mode of overprint + * @returns {Promise} + * @example + * this._viewer.setOverprint(Config.OverprintMode.Off); + */ setOverprint = (overprint: Config.OverprintMode): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -840,15 +3509,40 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category UI Customization + * @desc Sets the color post processing transformation mode for the viewer. + * @param {Config.ColorPostProcessMode} colorPostProcessMode color post processing + * transformation mode + * @example + * this._viewer.setColorPostProcessMode(Config.ColorPostProcessMode.NightMode); + */ setColorPostProcessMode = (colorPostProcessMode: Config.ColorPostProcessMode): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - DocumentViewManager.setColorPostProcessMode(tag, colorPostProcessMode); + return DocumentViewManager.setColorPostProcessMode(tag, colorPostProcessMode); } return Promise.resolve(); } - setColorPostProcessColors = (whiteColor: AnnotOptions.Color, blackColor: AnnotOptions.Color): Promise => { + /** + * @method + * @category UI Customization + * @desc Sets the white and black color for the color post processing transformation. + * @param {object} whiteColor the white color for the color post processing transformation, + * in the format `{red: number, green: number, blue: number}`. + * `alpha` could be optionally included (only Android would apply alpha), + * and all numbers should be in range [0, 255] + * @param {object} blackColor the black color for the color post processing transformation, + * in the same format as whiteColor + * @example + * const whiteColor = {"red": 0, "green": 0, "blue": 255}; + * const blackColor = {"red": 255, "green": 0, "blue": 0}; + * this._viewer.setColorPostProcessColors(whiteColor, blackColor); + */ + setColorPostProcessColors = (whiteColor: AnnotOptions.Color, blackColor: AnnotOptions.Color) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.setColorPostProcessColors(tag, whiteColor, blackColor); @@ -856,7 +3550,19 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - startSearchMode = (searchString: string, matchCase: boolean, matchWholeWord: boolean): Promise => { + /** + * @method + * @category Text Selection + * @desc Search for a term and all matching results will be highlighted. + * @param {string} searchString the text to search for + * @param {boolean} matchCase indicates if it is case sensitive + * @param {boolean} matchWholeWord indicates if it matches an entire word only + * @returns {Promise} + * @example + * this._viewer.startSearchMode('PDFTron', false, false); + */ + startSearchMode = (searchString: string, matchCase: boolean, matchWholeWord: boolean) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.startSearchMode(tag, searchString, matchCase, matchWholeWord); @@ -864,6 +3570,14 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Finishes the current text search and remove all the highlights. + * @returns {Promise} + * @example + * this._viewer.exitSearchMode(); + */ exitSearchMode = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -872,14 +3586,38 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - findText = (searchString: string, matchCase: boolean, matchWholeWord: boolean, searchUp: boolean, regExp: boolean): Promise => { + /** + * @method + * @category Text Selection + * @desc Searches asynchronously, starting from the current page, for the given text. + * PDFViewCtrl automatically scrolls to the position so that the found text is visible. + * @param {string} searchString the text to search for + * @param {boolean} matchCase indicates if it is case sensitive + * @param {boolean} matchWholeWord indicates if it matches an entire word only + * @param {boolean} searchUp indicates if it searches upward + * @param {boolean} regExp indicates if searchString is a regular expression + * @returns {Promise} + * @example + * this._viewer.findText('PDFTron', false, false, true, false); + */ + findText = (searchString: string, matchCase: boolean, matchWholeWord: boolean, + searchUp: boolean, regExp: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.findText(tag, searchString, matchCase, matchWholeWord, searchUp, regExp); + return DocumentViewManager.findText(tag, searchString, matchCase, + matchWholeWord, searchUp, regExp); } return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Cancels the current text search thread, if exists. + * @returns {Promise} + * @example + * this._viewer.cancelFindText(); + */ cancelFindText = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -888,6 +3626,14 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Displays a search bar that allows the user to enter and search text within a document. + * @returns {Promise} + * @example + * this._viewer.openSearch(); + */ openSearch = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -895,7 +3641,37 @@ export class DocumentView extends PureComponent { } return Promise.resolve(); } - + + /** + * @method + * @category Text Selection + * @desc Returns the text selection on a given page, if any. + * @param {number} pageNumber the specified page number. It is 1-indexed + * @returns {Promise} selection - the text selection, in the format + * `{html: string, unicode: string, pageNumber: number, + * quads: [[{x: number, y: number}, {x: number, y: number}, + * {x: number, y: number}, {x: number, y: number}], ...]}`. + * If no such selection could be found, this would be null + * + * Quads indicate the quad boundary boxes for the selection, + * which could have a size larger than 1 if selection spans across different lines. + * Each quad have 4 points with x, y coordinates specified in number, representing a boundary box. + * The 4 points are in counter-clockwise order, though the first point is not guaranteed to be on + * lower-left relatively to the box. + * @example + * this._viewer.getSelection(2).then((selection) => { + * if (selection) { + * console.log('Found selection on page', selection.pageNumber); + * for (let i = 0; i < selection.quads.length; i ++) { + * const quad = selection.quads[i]; + * console.log('selection boundary quad', i); + * for (const quadPoint of quad) { + * console.log('A quad point has coordinates', quadPoint.x, quadPoint.y); + * } + * } + * } + * }); + */ getSelection = (pageNumber: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -904,6 +3680,16 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Returns whether there is a text selection in the current document. + * @returns {Promise} hasSelection - whether a text selection exists + * @example + * this._viewer.hasSelection().then((hasSelection) => { + * console.log('There is a selection in the document.'); + * }); + */ hasSelection = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -912,6 +3698,14 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Clears any text selection in the current document. + * @returns {Promise} + * @example + * this._viewer.clearSelection(); + */ clearSelection = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -920,7 +3714,27 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - getSelectionPageRange = (): Promise => { + /** + * @method + * @category Text Selection + * @desc Returns the page range (beginning and end) that has text selection on it. + * @returns {Promise} + * + * Name | Type | Description + * --- | --- | --- + * begin | number | the first page to have selection, -1 if there are no selections + * end | number | the last page to have selection, -1 if there are no selections + * + * @example + * this._viewer.getSelectionPageRange().then(({begin, end}) => { + * if (begin === -1) { + * console.log('There is no selection'); + * } else { + * console.log('The selection range is from', begin, 'to', end); + * } + * }); + */ + getSelectionPageRange = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { return DocumentViewManager.getSelectionPageRange(tag); @@ -928,6 +3742,20 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Returns whether there is a text selection on the specified page in the current document. + * @param {number} pageNumber the specified page number. It is 1-indexed + * @returns {Promise} hasSelection - whether a text selection exists on + * the specified page + * @example + * this._viewer.hasSelectionOnPage(5).then((hasSelection) => { + * if (hasSelection) { + * console.log('There is a selection on page 5 in the document.'); + * } + * }); + */ hasSelectionOnPage = (pageNumber: number): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -936,7 +3764,19 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - + /** + * @method + * @category Text Selection + * @desc Selects the text within the given rectangle region. + * @param {object} rect the rectangle region in the format of + * `{x1: number, x2: number, y1: number, y2: number}` + * @returns {Promise} selected - whether there is text selected + * @example + * this._viewer.selectInRect({x1: 0, y1: 0, x2: 200.5, y2: 200.5}).then((selected) => { + * console.log(selected); + * }); + */ + selectInRect = (rect: AnnotOptions.Rect): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -945,6 +3785,18 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Returns whether there is text in given rectangle region. + * @param {object} rect the rectangle region in the format of + * `{x1: number, x2: number, y1: number, y2: number}` + * @returns {Promise} hasText - whether there is text in the region + * @example + * this._viewer.isThereTextInRect({x1: 0, y1: 0, x2: 200, y2: 200}).then((hasText) => { + * console.log(hasText); + * }); + */ isThereTextInRect = (rect: AnnotOptions.Rect): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -953,6 +3805,14 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Text Selection + * @desc Selects all text on the page. + * @returns {Promise} + * @example + * this._viewer.selectAll(); + */ selectAll = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -961,14 +3821,32 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Viewer Options + * @desc Sets whether borders of each page are visible in the viewer, + * which is disabled by default. + * @param {boolean} pageBorderVisibility whether borders of each page are visible in the viewer + * @example + * this._viewer.setPageBorderVisibility(true); + */ setPageBorderVisibility = (pageBorderVisibility: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.setPageBorderVisibility(tag, pageBorderVisibility); + return DocumentViewManager.setPageBorderVisibility(tag, pageBorderVisibility); } return Promise.resolve(); } + /** + * @method + * @category Viewer Options + * @desc Enables or disables transparency grid (check board pattern) to reflect page transparency, + * which is disabled by default. + * @param {boolean} pageTransparencyGrid whether to use the transparency grid + * @example + * this._viewer.setPageTransparencyGrid(true); + */ setPageTransparencyGrid = (pageTransparencyGrid: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -977,14 +3855,32 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Viewer Options + * @desc Sets the default page color of the viewer. + * @param {object} defaultPageColor the default page color, in the format + * `{red: number, green: number, blue: number}`, each number in range [0, 255] + * @example + * this._viewer.setDefaultPageColor({red: 0, green: 255, blue: 0}); // green color + */ setDefaultPageColor = (defaultPageColor: AnnotOptions.Color): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.setDefaultPageColor(tag, defaultPageColor); + return DocumentViewManager.setDefaultPageColor(tag, defaultPageColor); } return Promise.resolve(); } + /** + * @method + * @category Viewer Options + * @desc Sets the background color of the viewer. + * @param {object} backgroundColor the background color, in the format + * `{red: number, green: number, blue: number}`, each number in range [0, 255] + * @example + * this._viewer.setBackgroundColor({red: 0, green: 0, blue: 255}); // blue color + */ setBackgroundColor = (backgroundColor: AnnotOptions.Color): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -993,118 +3889,285 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } - exportAsImage = (pageNumber: number, dpi: number, exportFormat: Config.ExportFormat): Promise => { + /** + * @method + * @desc Export a PDF page to image format defined in {@link Config.ExportFormat}. + * + * Unlike {@link RNPdftron#exportAsImage RNPdftron.exportAsImage}, + * this is a viewer method and should only be called *after* the document has been + * loaded or else unexpected behaviour can occur. + * This method uses the PDF that is associated with the viewer, + * and does not take a local file path to the desired PDF. + * @param {int} pageNumber the page to be converted; + * if the value does not refer to a valid page number, the file path will be undefined + * @param {double} dpi the output image resolution + * @param {Config.ExportFormat} exportFormat image format to be exported to + * @returns {Promise} path - the temp path of the created image, + * user is responsible for clean up the cache + * @example + * this._viewer.exportToImage(1, 92, Config.ExportFormat.BMP).then((path) => { + * console.log('export', path); + * }); + */ + exportAsImage = (pageNumber: number, dpi: number, exportFormat: Config.ExportFormat) + : Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.exportAsImage(tag, pageNumber, dpi, exportFormat); + return DocumentViewManager.exportAsImage(tag, pageNumber, dpi, exportFormat); } return Promise.resolve(); } + /** + * @method + * @category Undo/Redo + * @desc Undo the last modification. + * @returns {Promise} + * @example + * this._viewer.undo(); + */ undo = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.undo(tag); + return DocumentViewManager.undo(tag); } return Promise.resolve(); } + /** + * @method + * @category Undo/Redo + * @desc Redo the last modification. + * @returns {Promise} + * @example + * this._viewer.redo(); + */ redo = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.redo(tag); + return DocumentViewManager.redo(tag); } return Promise.resolve(); } + /** + * @method + * @category Undo/Redo + * @desc Checks whether an undo operation can be performed from the current snapshot. + * @returns {Promise} canUndo - whether it is possible to undo from + * the current snapshot + * @example + * this._viewer.canUndo().then((canUndo) => { + * console.log(canUndo ? 'undo possible' : 'no action to undo'); + * }); + */ canUndo = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.canUndo(tag); + return DocumentViewManager.canUndo(tag); } return Promise.resolve(); } + /** + * @method + * @category Undo/Redo + * @desc Checks whether a redo operation can be perfromed from the current snapshot. + * @returns {Promise} canRedo - whether it is possible to redo from + * the current snapshot + * @example + * this._viewer.canRedo().then((canRedo) => { + * console.log(canRedo ? 'redo possible' : 'no action to redo'); + * }); + */ canRedo = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.canRedo(tag); + return DocumentViewManager.canRedo(tag); } return Promise.resolve(); } + /** + * @method + * @desc Displays the page crop option. Android only. + * @returns {Promise} + * @example + * this._viewer.showCrop(); + */ showCrop = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.showCrop(tag); + return DocumentViewManager.showCrop(tag); } return Promise.resolve(); } + /** + * @method + * @category Toolbar + * @desc Sets the current {@link DocumentView.annotationToolbars annotationToolbars} + * for the viewer. + * @param {Config.DefaultToolbars|string} toolbar the toolbar to enable. Should be one of the + * {@link Config.DefaultToolbars} constants or the `id` of a custom toolbar object. + * @returns {Promise} + * @example + * this._viewer.setCurrentToolbar(Config.DefaultToolbars.Insert).then(() => { + * // done switching toolbar + * }); + */ setCurrentToolbar = (toolbar: string): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.setCurrentToolbar(tag, toolbar); + return DocumentViewManager.setCurrentToolbar(tag, toolbar); } return Promise.resolve(); } - + + /** + * @method + * @desc Displays the view settings. + * + * Requires a source rect in screen co-ordinates. + * On iOS this rect will be the anchor point for the view. The rect is ignored on Android. + * @param {map} rect The rectangular area in screen co-ordinates with keys + * `x1` (left), `y1` (bottom), `y1` (right), `y2` (top). Coordinates are in double format. + * @returns {Promise} + * @example + * this._viewer.showViewSettings({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}); + */ showViewSettings = (rect: AnnotOptions.Rect): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.showViewSettings(tag, rect); + return DocumentViewManager.showViewSettings(tag, rect); } return Promise.resolve(); } + /** + * @method + * @category Page + * @desc Android only. + * + * Displays a rotate dialog. + * This dialog allows users to rotate pages of the opened document by 90, 180 and 270 degrees. + * It also displays a thumbnail of the current page at the selected rotation angle. + * @returns {Promise} + * @example + * this._viewer.showRotateDialog(); + */ showRotateDialog = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.showRotateDialog(tag); + return DocumentViewManager.showRotateDialog(tag); } return Promise.resolve(); } - + + /** + * @method + * @desc Displays the add pages view. + * + * Requires a source rect in screen co-ordinates. + * On iOS this rect will be the anchor point for the view. The rect is ignored on Android. + * @param {map} rect The rectangular area in screen co-ordinates with keys + * `x1` (left), `y1` (bottom), `y1` (right), `y2`(top). Coordinates are in double format. + * @returns {Promise} + * @example + * this._viewer.showAddPagesView({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}); + */ showAddPagesView = (rect: AnnotOptions.Rect): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.showAddPagesView(tag, rect); + return DocumentViewManager.showAddPagesView(tag, rect); } return Promise.resolve(); } + /** + * @method + * @category Reflow + * @desc Returns whether the viewer is currently in reflow mode. + * @returns {Promise} inReflow - whether the viewer is in reflow mode + * @example + * this._viewer.isReflowMode().then((inReflow) => { + * console.log(inReflow ? 'in reflow mode' : 'not in reflow mode'); + * }); + */ isReflowMode = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.isReflowMode(tag); + return DocumentViewManager.isReflowMode(tag); } return Promise.resolve(); } + /** + * @method + * @category Reflow + * @desc Allows the user to programmatically enter and exit reflow mode. + * @returns {Promise} + * @example + * this._viewer.toggleReflow(); + */ toggleReflow = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.toggleReflow(tag); + return DocumentViewManager.toggleReflow(tag); } return Promise.resolve(); } + /** + * @method + * @desc Displays the share copy view. + * + * Requires a source rect in screen co-ordinates. + * On iOS this rect will be the anchor point for the view. The rect is ignored on Android. + * @returns {Promise} + * @param {map} rect The rectangular area in screen co-ordinates with keys + * `x1` (left), y1 (bottom), `y1` (right), `y2` (top). Coordinates are in double format. + * @param {boolean} flattening Whether the shared copy should be flattened before sharing. + * @example + * this._viewer.shareCopy({'x1': 10.0, 'y1': 10.0, 'x2': 20.0, 'y2': 20.0}, true); + */ shareCopy = (rect: AnnotOptions.Rect, flattening: boolean): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.shareCopy(tag, rect, flattening); + return DocumentViewManager.shareCopy(tag, rect, flattening); } return Promise.resolve(); } - + + /** + * @method + * @category Thumbnails + * @desc Display a page thumbnails view. + * + * This view allows users to navigate pages of a document. + * If {@link DocumentView.thumbnailViewEditingEnabled thumbnailViewEditingEnabled} is true, + * the user can also manipulate the document, including add, remove, re-arrange, rotate and + * duplicate pages. + * @returns {Promise} + * @example + * this._viewer.openThumbnailsView(); + */ openThumbnailsView = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.openThumbnailsView(tag); + return DocumentViewManager.openThumbnailsView(tag); } return Promise.resolve(); } + /** + * @method + * @desc Displays the outline tab of the existing list container. + * If this tab has been disabled, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openOutlineList(); + */ openOutlineList = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1113,6 +4176,15 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @desc On Android it displays the layers dialog, while on iOS it displays the layers tab + * of the existing list container. If this tab has been disabled or there are no layers in + * the document, the method does nothing. + * @returns {Promise} + * @example + * this._viewer.openLayersList(); + */ openLayersList = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1121,6 +4193,13 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @desc Displays the existing list container. Its current tab will be the one last opened. + * @returns {Promise} + * @example + * this._viewer.openNavigationLists(); + */ openNavigationLists = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { @@ -1129,40 +4208,91 @@ export class DocumentView extends PureComponent { return Promise.resolve(); } + /** + * @method + * @category Signature + * @desc Gets a list of absolute file paths to PDFs containing the saved signatures. + * @returns {Promise>} signatures - an array of string containing the + * absolute file paths; if there are no saved signatures, the value is an empty array + * @example + * this._viewer.getSavedSignatures().then((signatures) => { + * if (signatures.length > 0) { + * signatures.forEach((signature) => { + * console.log(signature); + * }); + * } + * }) + */ getSavedSignatures = (): Promise> => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.getSavedSignatures(tag); + return DocumentViewManager.getSavedSignatures(tag); } return Promise.resolve(); } + /** + * @method + * @category Signature + * @desc Retrieves the absolute file path to the folder containing the saved signatures. + * For Android, to get the folder containing the saved signature JPGs, use + * {@link DocumentView.getSavedSignatureJpgFolder getSavedSignatureJpgFolder}. + * @returns {Promise} path - the absolute file path to the folder + * @example + * this._viewer.getSavedSignatureFolder().then((path) => { + * if (path != null) { + * console.log(path); + * } + * }) + */ getSavedSignatureFolder = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.getSavedSignatureFolder(tag); + return DocumentViewManager.getSavedSignatureFolder(tag); } return Promise.resolve(); } - + + /** + * @method + * @category Signature + * @desc Android only. + * + * Retrieves the absolute file path to the folder containing the saved signature JPGs. + * For Android, to get the folder containing the saved signature PDFs, use + * {@link DocumentView.getSavedSignatureFolder getSavedSignatureFolder}. + * @returns {Promise} path - the absolute file path to the folder + * @example + * this._viewer.getSavedSignatureJpgFolder().then((path) => { + * if (path != null) { + * console.log(path); + * } + * }) + */ getSavedSignatureJpgFolder = (): Promise => { const tag = findNodeHandle(this._viewerRef); if (tag != null) { - return DocumentViewManager.getSavedSignatureJpgFolder(tag); + return DocumentViewManager.getSavedSignatureJpgFolder(tag); } return Promise.resolve(); } + /** @ignore */ _setNativeRef = (ref: any) => { this._viewerRef = ref; }; + /** + * @ignore + * + */ render() { return ( // @ts-ignore + */ + document: PropTypes.string.isRequired } // Generates the prop types for TypeScript users, from PropTypes. -type PDFViewCtrlProps = InferProps; +type PDFViewCtrlProps = InferProps; +/** + * @class + * @classdesc A React component for displaying documents of different types such as + * PDF, docx, pptx, xlsx and various image formats. + * + * PDFViewCtrl is useful when a higher level of customization is required. + * For easy all-in-one document viewing and editing, use {@link DocumentView}. + * @hideconstructor + * @hidesource + * @ignore + */ export class PDFViewCtrl extends PureComponent { - static propTypes = propTypes; + static propTypes = Object.assign(PDFViewCtrlPropTypes, { ...ViewPropTypes }); - render() { + render () { return ( ) @@ -30,4 +56,4 @@ export class PDFViewCtrl extends PureComponent { const name = Platform.OS === 'ios' ? 'RNTPTPDFViewCtrl' : 'RCTPDFViewCtrl'; -const RCTPDFViewCtrl = requireNativeComponent(name); \ No newline at end of file +const RCTPDFViewCtrl = requireNativeComponent(name);