API for Flutter PDF Viewer

This section is for some static methods for global library initialization, configuration, and utility. They could only be callable as a plugin. Below is an example for initialize:

1PdftronFlutter.initialize('your_license_key');

1String version = PdftronFlutter.version;
2print('Current Apryse SDK version is: ' + version);

1String platformVersion = PdftronFlutter.platformVersion;
2print('App is currently running on: ' + platformVersion);

1PdftronFlutter.initialize();

1PdftronFlutter.initialize('your_licensey_key');

1PdftronFlutter.setRequestedOrientation(0);

This section is for viewer related non-static methods. They would be callable in both plugin and widget versions. For example, openDocument is accessible in 2 ways:

Plugin:

1void showViewer() async {
2  await PdftronFlutter.openDocument('https://pdftron.s3.amazonaws.com/downloads/pl/PDFTRON_about.pdf');
3}

Widget (DocumentViewController):

1void _onDocumentViewCreated(DocumentViewController controller) async {
2    await controller.openDocument('https://pdftron.s3.amazonaws.com/downloads/pl/PDFTRON_about.pdf');
3}

You must choose either the widget or plugin, and use it for all APIs. Mixing widget and plugin APIs will not function correctly. For more information, see Widget or Plugin.

There are several custom classes used in these APIs: Annot, AnnotWithRect, Field, Rect, AnnotFlag, AnnotWithFlag and CustomToolbar. These classes are listed in Options, and the constants that are used in the examples below are all listed in Constants.

1var disabledElements = [Buttons.shareButton, Buttons.searchButton];
2var disabledTools = [Tools.annotationCreateLine, Tools.annotationCreateRectangle];
3var hideDefaultAnnotationToolbars = [DefaultToolbars.annotate, DefaultToolbars.draw];
4var config = Config();
5config.disabledElements = disabledElements;
6config.disabledTools = disabledTools;
7config.multiTabEnabled = false;
8config.customHeaders = {'headerName': 'headerValue'};
9config.hideDefaultAnnotationToolbars = hideDefaultAnnotationToolbars;
10config.hideAnnotationToolbarSwitcher = true;
11config.continuousAnnotationEditing = true;
12var password = 'pdf_password';
13await PdftronFlutter.openDocument(_document, password: password, config: config);

1var path = await PdftronFlutter.saveDocument();

1var path = await PdftronFlutter.getDocumentPath();

1await PdftronFlutter.openAnnotationList();

1await PdftronFlutter.openBookmarkList();

1await PdftronFlutter.openOutlineList();

1await PdftronFlutter.openLayersList();

1await PdftronFlutter.openNavigationLists();

setLeadingNavButtonIcon

Sets the file name of the icon to be used for the leading navigation button. The button will use the specified icon if showLeadingNavButton (which by default is true) is true in the config.

Parameters

leadingNavButtonIcon

string

the icon path to the navigation button

Returns

Returns a Future.

Example

Dart

1PdftronFlutter.setLeadingNavButtonIcon(Platform.isIOS ? 'ic_close_black_24px.png' : 'ic_arrow_back_white_24dp');

Report Invalid Code

Copy

Note: to add the image file to your application, please follow the steps below:

Android

1. Add the image resource to the example/android/app/src/main/res/drawable directory. For details about supported file types and potential compression, check out Create drawables from resource images.

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 Runner.xcworkspace), and navigate through the list below. This would allow you to add resources, in this case, an image, to your project.

• "Project navigator"
• "Runner" (or the app name)
• "Build Phases"
• "Copy Bundle Resources"
• "+".

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.

1PdftronFlutter.setToolMode(Tools.annotationCreateEllipse);

1var committed = await PdftronFlutter.commitTool();
2print("Tool committed: $committed");

1var setResult = await controller.setCurrentPage(5);
2print('Page set ' + (setResult ? 'successfully' : 'unsuccessfully'));

1var currentPage = await PdftronFlutter.getCurrentPage();
2print("The current page is $currentPage");

1var pageCount = await PdftronFlutter.getPageCount();
2print("The current doc has $pageCount pages");

1var cropBox = await PdftronFlutter.getPageCropBox(1);
2print('The width of crop box for page 1 is: ' + cropBox.width.toString());

1var pageRotation = await PdftronFlutter.getPageRotation(1);
2print("The rotation value of page 1 is $pageRotation");

1var pageChanged = await PdftronFlutter.gotoPreviousPage();
2if (pageChanged) {
3  print("Successfully went to previous page");
4}

Go to the next page of the document. If on last page, it will stay on last page.

Returns a Future.

Future Parameters:

1var pageChanged = await PdftronFlutter.gotoNextPage();
2if (pageChanged) {
3  print("Successfully went to next page");
4}

Go to the first page of the document.

Returns a Future.

Future Parameters:

1var pageChanged = await PdftronFlutter.gotoFirstPage();
2if (pageChanged) {
3  print("Successfully went to first page");
4}

Go to the last page of the document.

Returns a Future.

Future Parameters:

1var pageChanged = await PdftronFlutter.gotoLastPage();
2if (pageChanged) {
3  print("Successfully went to last page");
4}

Imports remote annotation command to local document. The XFDF needs to be a valid command format with <add><modify><delete> tags.

Parameters:

1var xfdfCommand = 'xfdfCommand <?xml version="1.0" encoding="UTF-8"?><xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve"><add><circle style="solid" width="5" color="#E44234" opacity="1" creationdate="D:20201218025606Z" flags="print" date="D:20201218025606Z" name="9d0f2d63-a0cc-4f06-b786-58178c4bd2b1" page="0" rect="56.4793,584.496,208.849,739.369" title="PDF" /></add><modify /><delete /><pdf-info import-version="3" version="2" xmlns="http://www.pdftron.com/pdfinfo" /></xfdf>';
2PdftronFlutter.importAnnotationCommand(xfdfCommand);

Imports XFDF annotation string to current document.

Parameters:

Returns a Future.

1var xfdf = '<?xml version="1.0" encoding="UTF-8"?>\n<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">\n\t<annots>\n\t\t<circle style="solid" width="5" color="#E44234" opacity="1" creationdate="D:20190729202215Z" flags="print" date="D:20190729202215Z" page="0" rect="138.824,653.226,236.28,725.159" title="" /></annots>\n\t<pages>\n\t\t<defmtx matrix="1.333333,0.000000,0.000000,-1.333333,0.000000,1056.000000" />\n\t</pages>\n\t<pdf-info version="2" xmlns="http://www.pdftron.com/pdfinfo" />\n</xfdf>';
2PdftronFlutter.importAnnotations(xfdf);

Extracts XFDF from the current document. If annotationList is null, export all annotations from the document; else export the valid ones specified.

Parameters:

Returns a Future.

Future Parameters:

Exports all annotations:

1var xfdf = await PdftronFlutter.exportAnnotations(null);

Exports specified annotations:

1List<Annot> annotList = new List<Annot>.empty(growable: true);
2annotList.add(new Annot('Hello', 1));
3annotList.add(new Annot('World', 2));
4var xfdf = await PdftronFlutter.exportAnnotations(annotList);

Flattens the forms and (optionally) annotations in the current document.

Parameters:

Returns a Future.

1PdftronFlutter.flattenAnnotations(true);

Deletes the specified annotations in the current document.

Parameters:

Returns a Future.

1List<Annot> annotList = new List<Annot>.empty(growable: true);
2annotList.add(new Annot('Hello', 1));
3annotList.add(new Annot('World', 2));
4PdftronFlutter.deleteAnnotations(annotList);

Deletes all annotations in the current document excluding links and widgets.

Returns a Future.

PdftronFlutter.deleteAllAnnotations();

Selects the specified annotation in the current document.

Parameters:

Returns a Future.

PdftronFlutter.selectAnnotation(new Annot('Hello', 1));

Sets flags for specified annotations in the current document.

Parameters:

Returns a Future.

1List<AnnotWithFlags> annotsWithFlags = new List<AnnotWithFlags>.empty(growable: true);
2Annot hello = new Annot('Hello', 1);
3Annot world = new Annot('World', 3);
4AnnotFlag printOn = new AnnotFlag(AnnotationFlags.print, true);
5AnnotFlag unlock = new AnnotFlag(AnnotationFlags.locked, false);
6// you can add an AnnotWithFlags object flexibly like this:
7annotsWithFlags.add(new AnnotWithFlags.fromAnnotAndFlags(hello, [printOn, unlock]));
8annotsWithFlags.add(new AnnotWithFlags.fromAnnotAndFlags(world, [unlock]));
9// Or simply use the constructor like this:
10annotsWithFlags.add(new AnnotWithFlags('Pdftron', 10, AnnotationFlags.no_zoom, true));
11PdftronFlutter.setFlagsForAnnotations(annotsWithFlags);

Sets properties for specified annotation in the current document.

Parameters:

For settable properties:

1Annot pdf = new Annot('pdf', 1);
2AnnotProperty property = new AnnotProperty();
3property.rect = new Rect.fromCoordinates(1, 1.5, 100.2, 100);
4property.contents = 'Hello World';
5property.subject = 'sample';
6property.title = 'set-props-for-annot';
7property.rotation = 90;
8PdftronFlutter.setPropertiesForAnnotation(pdf, property);

Sets a field flag value on one or more form fields.

Parameters:

Returns a Future.

PdftronFlutter.setFlagForFields(['First Name', 'Last Name'], FieldFlags.Required, true);

Sets field values on one or more form fields of different types.

Parameters:

Returns a Future.

1PdftronFlutter.setValuesForFields([
2      new Field('textField1', "Pdftron"),
3      new Field('textField2', 12.34),
4      new Field('checkboxField1', true),
5      new Field('checkboxField2', false),
6      new Field('radioField', 'Yes'),
7      new Field('choiceField', 'No')
8    ]);

Handles the back button in search mode. Android only.

Returns a Future.

Future Parameters:

1var handled = await PdftronFlutter.handleBackButton();
2print("Back button handled: $handled");

Imports user bookmarks into the document. The input needs to be a valid bookmark JSON format.

Parameters:

Returns a Future.

PdftronFlutter.importBookmarkJson("{\"0\": \"Page 1\", \"3\": \"Page 4\"}");

Creates a new bookmark with the given title and page number.

Parameters:

Returns a Future.

PdftronFlutter.addBookmark("Page 7", 6);

Closes all documents that are currently opened in a multiTab environment (that is, multiTabEnabled is true in the config).

Returns a Future.

PdftronFlutter.closeAllTabs();

This section contains all the event listeners you could attach to the viewer.

Event is raised when the document finishes loading.

Event Parameters:

1var documentLoadedCancel = startDocumentLoadedListener((path)
2{
3  print("flutter document loaded: $path");
4});

Event is raised when the document has errors when loading.

1var documentErrorCancel = startDocumentErrorListener((){
2  print("flutter document loaded unsuccessfully");
3});

Event is raised when the leading navigation button is pressed.

1Dartvar navPressedCancel = startLeadingNavButtonPressedListener(()
2{
3  print("flutter nav button pressed");
4});

Event is raised when the current page changes.

Event Parameters:

1var pageChangedCancel = startPageChangedListener((previousPageNumber, pageNumber)
2{
3  print("flutter page changed. from $previousPageNumber to $pageNumber");
4});

Event is raised when a page has been moved in the document.

Event Parameters:

1var pageMovedCancel = startPageMovedListener((previousPageNumber, pageNumber) {
2  print("flutter page moved from $previousPageNumber to $pageNumber");
3});

Event is raised when local annotation changes committed to the document.

Event Parameters:

1var annotCancel = startExportAnnotationCommandListener((xfdfCommand) {
2  // local annotation changed
3  // upload XFDF command to server here
4  print("flutter xfdfCommand: $xfdfCommand");
5});

Event is raised when there is a change to annotations to the document.

Event Parameters:

1var annotChangedCancel = startAnnotationChangedListener((action, annotations) 
2{
3  print("flutter annotation action: ${action}");
4  for (Annot annot in annotations) {
5    print("annotation has id: ${annot.id}");
6    print("annotation is in page: ${annot.pageNumber}");
7  }
8});

Event is raised when annotations are selected.

Event Parameters:

1var annotsSelectedCancel = startAnnotationsSelectedListener((annotationWithRects) 
2{
3  for (AnnotWithRect annotWithRect in annotationWithRects) {
4    print("annotation has id: ${annotWithRect.id}");
5    print("annotation is in page: ${annotWithRect.pageNumber}");
6    print("annotation has width: ${annotWithRect.rect.width}");
7  }
8});

Event is raised when there are changes to form field values.

Event Parameters:

1var fieldChangedCancel = startFormFieldValueChangedListener((fields)
2{
3  for (Field field in fields) {
4    print("Field has name ${field.fieldName}");
5    print("Field has value ${field.fieldValue}");
6  }
7});

Event is raised on annotation menu pressed if it is passed into overrideAnnotationMenuBehavior.

Event Parameters:

1var annotationMenuPressedCancel = startAnnotationMenuPressedListener((annotationMenuItem, annotations) 
2{
3  print("Annotation menu item " + annotationMenuItem + " has been pressed");
4  for (Annot annotation in annotations) {
5    print("Annotation has id: ${annotation.id}");
6    print("Annotation is in page: ${annotation.pageNumber}");
7  }
8});

Event is raised on long press menu pressed if it is passed into overrideLongPressMenuBehavior.

Event Parameters:

1var longPressMenuPressedCancel = startLongPressMenuPressedListener((longPressMenuItem, longPressText)
2{
3  print("Long press menu item " + longPressMenuItem + " has been pressed");
4  if (longPressText.length > 0) {
5    print("The selected text is: " + longPressText);
6  }
7});

Event is raised on certain behaviors, if any is passed into overrideBehavior.

action | String, one of the Behaviors constants | The behavior which has been activated data | map | detailed information regarding the behavior

1var behaviorActivatedCancel = startBehaviorActivatedListener((action, data) {
2  print('action is ' + action);
3  print('url is ' + data['url']);

Event is raised when user bookmark changes committed to the document.

Event Parameters:

1var bookmarkCancel = startExportBookmarkListener((bookmarkJson) {
2  print("flutter bookmark: ${bookmarkJson}");
3});

Event is raised when zoom ratio is changed in the current document.

Event Parameters:

1var zoomChangedCancel = startZoomChangedListener((zoom) 
2{
3  print("flutter zoom changed. Current zoom is: $zoom");
4});

This section is the configuration part of the openDocument function. You could also refer to Config for all mutable properties.

map<string, string>, defaults to empty.

Defines custom headers to use with HTTP/HTTPS requests.

config.customHeaders = {'headerName': 'headerValue'};

bool, defaults to false.

Defines whether the viewer is read-only. If true, the UI will not allow the user to change the document.

config.readOnly = true;

one of the DefaultEraserType constants, optional

Sets the default eraser tool type. Value only applied after a clean install.

Eraser TypeDescriptionannotationEraserErases everything as an object; if you touch ink, the entire object is erased.hybrideEraserErases ink by pixel, but erases other annotation types as objects.inkEraserErases ink by pixel only. Android only.

config.defaultEraserType = DefaultEraserType.inkEraser;

bool, defaults to false.

If true, document in openDocument will be treated as a base64 string.

When viewing a document initialized with a base64 string (i.e. a memory buffer), a temporary file is created on Android, but not on iOS. (If you need access to a file-backed PDF on iOS, save the base64 string to disk, and open the file located at that path.)

config.isBase64String = true;

String, defaults to .pdf, required if using base64 string of a non-pdf file.

Defines the file extension for the base64 string in document, if isBase64String is true.

array of Buttons constants, defaults to none.

Defines buttons to be disabled for the viewer.

var disabledElements = [Buttons.shareButton, Buttons.searchButton];
config.disabledElements = disabledElements;

array of Tools constants, defaults to none.

Defines tools to be disabled for the viewer.

var disabledTools = [Tools.annotationCreateLine, Tools.annotationCreateRectangle];
config.disabledTools = disabledTools;

bool, defaults to true.

Defines whether to show the leading navigation button.

config.showLeadingNavButton = true;

array of CustomToolbar objects or DefaultToolbars constants.

Defines custom toolbars. If passed in, the set of default toolbars will no longer appear. It is possible to mix and match with default toolbars. See example below:

1// Viewer will use a custom defined toolbar and a default annotate toolbar in this case
2var customToolbar = new CustomToolbar('myToolbar', 'myToolbar', [Tools.annotationCreateArrow, Tools.annotationCreateCallout], ToolbarIcons.favorite);
3var annotationToolbars = [DefaultToolbars.annotate, customToolbar];

array of DefaultToolbars constants, defaults to none.

Defines which default annotation toolbars should be hidden. Note that this should be used when annotationToolbars is not defined.

1// Viewer will use all the default toolbars except annotate or draw in this case
2var hideDefaultAnnotationToolbars = [DefaultToolbars.annotate, DefaultToolbars.draw];
3config.hideDefaultAnnotationToolbars = hideDefaultAnnotationToolbars;

bool, defaults to false.

Defines whether to show the toolbar switcher in the top toolbar.

config.hideAnnotationToolbarSwitcher = true;

bool, defaults to false.

Defines whether to hide both the top app nav bar and the annotation toolbar.

config.hideTopToolbars = true;

bool, defaults to false.

Defines whether to hide the top navigation app bar.

config.hideTopAppNavBar = true;

bool, defaults to false.

Defines whether to hide the bottom toolbar for the current viewer.

config.hideBottomToolbar = true;

one of the FitModes constants, default value is 'FitWidth'.

Defines the fit mode (default zoom level) of the viewer.

config.fitMode = FitModes.fitHeight;

one of the LayoutModes constants, default value is 'Continuous'.

Defines the layout mode of the viewer.

config.layoutMode = LayoutModes.facingCover;

number, optional.

Defines the initial page number that viewer displays when the document is opened. Note that page numbers are 1-indexed.

config.initialPageNumber = 5;

bool, defaults to true.

Defines whether the viewer should change pages when the user taps the edge of a page, while the viewer is in a horizontal viewing mode.

config.pageChangeOnTap = true;

bool, defaults to true.

Defines whether to show the page indicator for the viewer.

config.pageIndicatorEnabled = true;

bool, defaults to false.

Defines whether the page indicator will always be visible.

config.pageNumberIndicatorAlwaysVisible = true;

bool, defaults to false.

Defines whether annotation's flags will be taken into account when it is selected, for example, an annotation with a locked flag can not be resized or moved.

config.annotationPermissionCheckEnabled = true;

String.

Defines the author name for all annotations created on the current document. Exported xfdfCommand will include this piece of information.

config.annotationAuthor = 'Apryse';

bool, 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.

config.continuousAnnotationEditing = true;

bool, defaults to true.

Defines whether an annotation is selected after it is created. On iOS, this functions for shape and text markup annotations only.

config.selectAnnotationAfterCreation = true;

array of Tools constants, defaults to none.

Defines annotation types that cannot be edited after creation.

config.disableEditingByAnnotationType = [Tools.annotationCreateTextSquiggly, Tools.annotationCreateTextHighlight, Tools.annotationCreateEllipse];

array of Tools constants, defaults to none

Defines annotation types that will not show the default annotation menu.

config.hideAnnotationMenu = [Tools.annotationCreateArrow, Tools.annotationEraserTool];

array of AnnotationMenuItems constants, default contains all items

Defines the menu items that can show when an annotation is selected.

config.annotationMenuItems = [AnnotationMenuItems.search, AnnotationMenuItems.share];

array of AnnotationMenuItems constants, 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 event handler startAnnotationMenuPressedListener will be called from which custom behavior can be implemented.

config.overrideAnnotationMenuBehavior = [AnnotationMenuItems.copy];

bool, defaults to true

Defines whether to show the popup menu of options after the user long presses on text or blank space on the document.

config.longPressMenuEnabled = false;

array of LongPressMenuItems constants, optional, default contains all the items

Defines menu items that can be shown when long pressing on text or blank space.

config.longPressMenuItems = [LongPressMenuItems.search, LongPressMenuItems.share];

array of LongPressMenuItems 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 event handler startLongPressMenuPressedListener will be called where custom behavior can be implemented.

config.overrideLongPressMenuBehavior = [LongPressMenuItems.copy];

array of Behaviors constants, defaults to false.

Defines actions that should skip default behavior, such as external link click. The event handler startBehaviorActivatedListener will be called when the behavior is activated, where custom behavior can be implemented.

config.overrideBehavior = [Behaviors.linkPress];

bool, defaults to false.

Defines whether viewer will use tabs in order to have more than one document open simultaneously (like a web browser). Calling openDocument with this value being true will cause a new tab to be opened with the associated document.

config.multiTabEnabled = true;

String, default is the file name.

Sets the tab title if multiTabEnabled is true. (For Android, tabTitle is only supported on the widget viewer)

config.tabTitle = 'tab1';

bool, defaults to false.

Defines whether signature fields will be signed with image stamps. This is useful if you are saving XFDF to remote source.

config.signSignatureFieldsWithStamps = true;

bool, defaults to true.

Defines whether to show saved signatures for re-use when using the signing tool.

config.showSavedSignatures = true;

bool, defaults to true.

Defines whether user can modify the document using the thumbnail view (e.g. add/remove/rotate pages).

config.thumbnailViewEditingEnabled = false;

array of ThumbnailFilterModes constants, defaults to none.

Defines filter Modes that should be hidden in the thumbnails browser.

config.hideThumbnailFilterModes = [ThumbnailFilterModes.annotated];

array of ViewModePickerItem constants, optional, defaults to none.

Defines view mode items to be hidden in the view mode dialog.

config.hideViewModeItems=[ViewModePickerItem.ColorMode, ViewModePickerItem.Crop];

bool, dafaults to true.

Defines whether document is automatically saved by the viewer.

config.autoSaveEnabled = true;

bool, defaults to true.

Defines whether a stylus should act as a pen when in pan mode. If false, it will act as a finger.

config.useStylusAsPen = true;

bool, Android 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.

config.followSystemDarkMode = false;