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:

PdftronFlutter.initialize('your_license_key');

Obtains Apryse SDK version.

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

Obtains the current platform version.

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

Initializes Apryse SDK with your Apryse commercial license key. You can run Apryse in demo mode by not passing in a string, or by passing an empty string.

Parameters:

Returns a Future.

Demo mode:

PdftronFlutter.initialize();

Using commercial license key:

PdftronFlutter.initialize('your_licensey_key');

Changes the orientation of this activity. Android only.

For more information on the native API, see the Android API reference.

Parameters:

Returns a Future.

PdftronFlutter.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:

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

Widget (DocumentViewController):

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

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.

Opens a document in the viewer with configurations.

Parameters:

Returns a Future that would resolve when document is loaded.

For details regarding the config, please see Viewer Configurations.

Example:

var disabledElements = [Buttons.shareButton, Buttons.searchButton];
var disabledTools = [Tools.annotationCreateLine, Tools.annotationCreateRectangle];
var hideDefaultAnnotationToolbars = [DefaultToolbars.annotate, DefaultToolbars.draw];

var config = Config();
config.disabledElements = disabledElements;
config.disabledTools = disabledTools;
config.multiTabEnabled = false;
config.customHeaders = {'headerName': 'headerValue'};
config.hideDefaultAnnotationToolbars = hideDefaultAnnotationToolbars;
config.hideAnnotationToolbarSwitcher = true;
config.continuousAnnotationEditing = true;

var password = 'pdf_password';
await PdftronFlutter.openDocument(_document, password: password, config: config);

Saves the currently opened document in the viewer and get the absolute path to the document. Must only be called when the document is opened in the viewer.

Returns a Future.

Future Parameters:

var path = await PdftronFlutter.saveDocument();

Returns the path of the current document.

Returns a Future.

Future Parameters:

var path = await PdftronFlutter.getDocumentPath();

Displays the annotation tab of the existing list container. If this tab has been disabled, the method does nothing.

Returns a Future that resolves when the view has loaded.

await PdftronFlutter.openAnnotationList();

Displays the bookmark tab of the existing list container. If this tab has been disabled, the method does nothing.

Returns a Future that resolves when the view has loaded.

await PdftronFlutter.openBookmarkList();

Displays the outline tab of the existing list container. If this tab has been disabled, the method does nothing.

Returns a Future that resolves when the view has loaded.

await PdftronFlutter.openOutlineList();

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 Future that resolves when the view has loaded.

await PdftronFlutter.openLayersList();

Displays the existing list container. Its current tab will be the one last opened.

Returns a Future that resolves when the view has loaded.

await PdftronFlutter.openNavigationLists();

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:

Returns a Future.

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

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

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.

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.

Sets the current tool mode.

Parameters:

Returns a Future.

PdftronFlutter.setToolMode(Tools.annotationCreateEllipse);

Commits the current tool, only available for multi-stroke ink and poly-shape.

Returns a Future.

Future Parameters:

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

Sets current page of the document. Page numbers are 1-indexed.

Parameters:

Returns a Future.

Future Parameters:

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

Gets current page of the document. Page numbers are 1-indexed.

Returns a Future.

Future Parameters:

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

Gets the total number of pages in the currently displayed document.

Returns a Future.

Future Parameters:

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

Gets a map object of the crop box for specified page.

Parameters:

Returns a Future.

Future Parameters:

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

Gets the rotation value of the specified page in the current document.

Parameters:

Returns a Future.

Future Parameters:

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

Go to the previous page of the document. If on first page, it will stay on first page.

Returns a Future.

Future Parameters:

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

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

Returns a Future.

Future Parameters:

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

Go to the first page of the document.

Returns a Future.

Future Parameters:

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

Go to the last page of the document.

Returns a Future.

Future Parameters:

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

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

Parameters:

Returns a Future.

var 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>';
PdftronFlutter.importAnnotationCommand(xfdfCommand);

Imports XFDF annotation string to current document.

Parameters:

Returns a Future.

var 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>';
PdftronFlutter.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:

var xfdf = await PdftronFlutter.exportAnnotations(null);

Exports specified annotations:

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

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

Parameters:

Returns a Future.

PdftronFlutter.flattenAnnotations(true);

Deletes the specified annotations in the current document.

Parameters:

Returns a Future.

List<Annot> annotList = new List<Annot>.empty(growable: true);
annotList.add(new Annot('Hello', 1));
annotList.add(new Annot('World', 2));
PdftronFlutter.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.

List<AnnotWithFlags> annotsWithFlags = new List<AnnotWithFlags>.empty(growable: true);

Annot hello = new Annot('Hello', 1);
Annot world = new Annot('World', 3);
AnnotFlag printOn = new AnnotFlag(AnnotationFlags.print, true);
AnnotFlag unlock = new AnnotFlag(AnnotationFlags.locked, false);

// you can add an AnnotWithFlags object flexibly like this:
annotsWithFlags.add(new AnnotWithFlags.fromAnnotAndFlags(hello, [printOn, unlock]));
annotsWithFlags.add(new AnnotWithFlags.fromAnnotAndFlags(world, [unlock]));

// Or simply use the constructor like this:
annotsWithFlags.add(new AnnotWithFlags('Pdftron', 10, AnnotationFlags.no_zoom, true));
PdftronFlutter.setFlagsForAnnotations(annotsWithFlags);

Sets properties for specified annotation in the current document.

Parameters:

For settable properties:

Annot pdf = new Annot('pdf', 1);
AnnotProperty property = new AnnotProperty();
property.rect = new Rect.fromCoordinates(1, 1.5, 100.2, 100);
property.contents = 'Hello World';
property.subject = 'sample';
property.title = 'set-props-for-annot';
property.rotation = 90;
PdftronFlutter.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.

PdftronFlutter.setValuesForFields([
      new Field('textField1', "Pdftron"),
      new Field('textField2', 12.34),
      new Field('checkboxField1', true),
      new Field('checkboxField2', false),
      new Field('radioField', 'Yes'),
      new Field('choiceField', 'No')
    ]);

Handles the back button in search mode. Android only.

Returns a Future.

Future Parameters:

var handled = await PdftronFlutter.handleBackButton();
print("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:

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

Event is raised when the document has errors when loading.

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

Event is raised when the leading navigation button is pressed.

var navPressedCancel = startLeadingNavButtonPressedListener(()
{
  print("flutter nav button pressed");
});

Event is raised when the current page changes.

Event Parameters:

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

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

Event Parameters:

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

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

Event Parameters:

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

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

Event Parameters:

var annotChangedCancel = startAnnotationChangedListener((action, annotations) 
{
  print("flutter annotation action: ${action}");
  for (Annot annot in annotations) {
    print("annotation has id: ${annot.id}");
    print("annotation is in page: ${annot.pageNumber}");
  }
});

Event is raised when annotations are selected.

Event Parameters:

var annotsSelectedCancel = startAnnotationsSelectedListener((annotationWithRects) 
{
  for (AnnotWithRect annotWithRect in annotationWithRects) {
    print("annotation has id: ${annotWithRect.id}");
    print("annotation is in page: ${annotWithRect.pageNumber}");
    print("annotation has width: ${annotWithRect.rect.width}");
  }
});

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

Event Parameters:

var fieldChangedCancel = startFormFieldValueChangedListener((fields)
{
  for (Field field in fields) {
    print("Field has name ${field.fieldName}");
    print("Field has value ${field.fieldValue}");
  }
});

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

Event Parameters:

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

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

Event Parameters:

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

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

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

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

Event Parameters:

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

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

Event Parameters:

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

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.

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:

// Viewer will use a custom defined toolbar and a default annotate toolbar in this case
var customToolbar = new CustomToolbar('myToolbar', 'myToolbar', [Tools.annotationCreateArrow, Tools.annotationCreateCallout], ToolbarIcons.favorite);
var 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.

// Viewer will use all the default toolbars except annotate or draw in this case
var hideDefaultAnnotationToolbars = [DefaultToolbars.annotate, DefaultToolbars.draw];
config.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;