This Getting Started document is for users of the PDFNet version 6.7 and greater. For users of earlier version of PDFNet, please refer to Getting Started (2014).

Introduction

This tutorial shows the minimum steps needed to add a PDF viewing and annotating component to a Xamarin.Android app using PDFNet SDK. In this tutorial, you will create a simple PDF viewing and annotating app. You will also learn about an Android Java Bindings Library Project that allows you to customize our Tools library.

Note the completed sample project described in Part 2-4 is available by request from here.

The tutorial is divided into 5 parts:

Part 1: Things you should know about the library distribution
Part 2: Showing a PDF
Part 3: Adding support for Annotations, Text Selection and Form Filling
Part 4: Create customized Tools.dll from the open source Tools library
Part 5: Next steps

Part 1: Things you should know about the library distribution

• Full version vs. Standard version: The PDFNet for Xamarin.Android library is available in two different versions, the Standard version and the Full version. The Standard library offers the same viewing, annotation, and editing capabilities of the Full version, however it is much smaller. The main differences are:
  • The Full version has a built-in digital signature handler, which can be used by calling PDFDoc.AddStdSignatureHandler(); the Standard version does not have built-in signature handler. However, even with the Standard version, you will still be able to use the DigitalSignature tool because the pre-built Tools library includes Spongy Castle.
  • The Standard version does not support converting PDF pages to TIFF and PNG formats (i.e. PDFDraw will not work when using these formats.)
  • A number of features will only be available using the Full version due to their complexity. For example, universal document conversion (i.e. convert .docx, .doc, and .pptx to .pdf), reflow, and document preview cache generation. The detailed class list can be found in Release notes.

• Best for app development vs. Best for app deployment: To provide a user-friendly framework for both development and deployment, PDFNet provides two options for using the PDFNetAndroid.dll. (To learn more about Android CPU architecture, please refer to this article.)
  • Best for app development: a single PDFNetAndroid.dll that contains arm64-v8a, armeabi-v7a, x86, and x86_64 architectures that can be used to create a single APK that works on all armeabi-v7a, arm64-v8a, x86 or x86_64 devices/emulators running Android 2.2 or greater. This .dll is located in Lib/Full and Lib/Standard.
  • Best for app deployment: five separate PDFNetAndroid.dlls for each architecture (arm64-v8a, armeabi, armeabi-v7a, x86, x86_64) that can be used to build five separate APKs. This allows an absolute minimum APK download size, and allows you to create APKs that work on armeabi, armeabi-v7a, arm64-v8a, x86 and x86_64 devices/emulators running Android 2.2 or greater. These .dlls are found in the /arm64-v8a, /armeabi, /armeabi-v7a, /x86 and /x86_64 folders respectively. (These five folders are themselves located in /Lib/Full and /Lib/Standard.)
• Minumum Android API required: PDFNetAndroid.dll requires minimum API 11 (HONEYCOMB). Tools.dll requires minimum API 16 (JELLY_BEAN).

Part 2: Showing a PDF

• Create a new app

Open Xamarin Studio or Visual Studio and create a new Xamarin.Android project. If this is your first Xamarin.Android project, check out the getting started with Xamarin.Android guide here: https://developer.xamarin.com/guides/android/getting_started/hello,android/

• Add required dependency, resource and a PDF file to the project

Add the PDFNetAndroid.dll to the References list. Add a sample file “sample.pdf” to the Resources/raw  folder of your application. Set the Build Action of the sample file to AndroidResource. Find pdfnet.res file in resource/android folder and add this file to the Resources/raw folder of your application. Set the Build Action of the res file to AndroidResource.

• Add code to show a PDF

Change MainActivity.cs to the following.

using System;
using System.IO;
using System.Collections;
using Android.App;
using Android.Content;
using Android.Runtime;
using Android.Views;
using Android.Widget;
using Android.OS;

using pdftron;
using pdftron.PDF;
using pdftron.PDF.Tools;
using pdftron.PDF.Controls;

using Android.Support.V4.App;

using com.xamarin.recipes.filepicker;
using pdftron.Common;

namespace PDFNetAndroidXamarinSample
{
[Activity(Label = "@string/app_name", MainLauncher = true, Icon = "@drawable/pdf_icon", HardwareAccelerated = true,
ConfigurationChanges = Android.Content.PM.ConfigChanges.ScreenSize | Android.Content.PM.ConfigChanges.Orientation | Android.Content.PM.ConfigChanges.KeyboardHidden,
WindowSoftInputMode = SoftInput.AdjustPan,
Theme = "@style/AppTheme")]
public class MainActivity : FragmentActivity
{
private pdftron.PDF.PDFViewCtrl mPdfViewCtrl;

protected override void OnCreate(Bundle bundle)
{
base.OnCreate(bundle);

// Set our view from the "main" layout resource
try
{
PDFNet.Initialize(this, Resource.Raw.pdfnet); // No license key, will produce water-marks
//PDFNet.Initialize(this, Resource.Raw.pdfnet, "your license key"); // Full version mode
// Disk caching should be disabled if write-external-storage is not permitted.
// To add the permission, add
// to the manifest file.
Console.WriteLine(PDFNet.GetVersion());
}
catch (PDFNetException e)
{
Console.WriteLine(e.GetMessage());
return;
}

SetContentView(Resource.Layout.Main);
mPdfViewCtrl = FindViewById(Resource.Id.pdfviewctrl);
mPdfViewCtrl.PagePresentationMode = PDFViewCtrl.PagePresentationModes.e_single_continuous;

// Load file from resource
Stream fis = this.Resources.OpenRawResource(Resource.Raw.sample);
PDFDoc docToOpen = new PDFDoc(fis);
mPdfViewCtrl.Doc = docToOpen;
}

protected override void OnPause()
{
base.OnPause();
if (mPdfViewCtrl != null)
{
mPdfViewCtrl.Pause();
}
}

protected override void OnResume()
{
base.OnResume();
if (mPdfViewCtrl != null)
{
mPdfViewCtrl.Resume();
}
}

protected override void OnDestroy()
{
base.OnDestroy();

if (mPdfViewCtrl != null)
{
mPdfViewCtrl.Destroy();
mPdfViewCtrl = null;
}
}

public override void OnLowMemory()
{
base.OnLowMemory();
if (mPdfViewCtrl != null)
{
mPdfViewCtrl.PurgeMemory();
}
}
}

}

• Run the app

You can now run the app. If you run in the emulator, you will see the following. Note that the PDF can be scrolled and zoomed.

Part 3: Adding support for Annotations, Text Selection and Form Filling

PDFNet comes with built-in support for text selection, interactive annotation creation and editing, form filling and link following. These features have been implemented in an open source project using the PDFNet API, and are included as a project that builds the Tools.dll. Because the source is provided, implementers have complete flexibility and control to customize how users interact with the PDF so that it can fit their requirements exactly. To add support for annotations, text selection, etc:

• Add the dependency

Add the Tools.dll to the References list.

• Add the following lines as the last lines of the OnCreate method in MainActivity.cs

mToolManager = new ToolManager(mPdfViewCtrl);
mPdfViewCtrl.ToolManager = mToolManager;

You are now ready to run the project again. Now, when you run the project, you can select text, follow links and create and edit annotations. To create a new annotation, long press on an area of the document to trigger a popup with annotation types to create. This example behavior is shown in the below screenshot.

Part 4: Create customized Tools.dll from the open source Tools library

In the previous section you have seen how to use PDFViewCtrl with the tools add-on. However, if you wish to customize the Tools behavior, you will need to do so using the open source Java Tools project and then prepare the Android Archive file for building Tools.dll in Xamarin. This section demonstrates how to create Tools.dll from PDFViewCtrlTools.aar.

Please note that the following section will require some understanding on what an Android Archive is and how to build one. As well as what a Xamarin binding project is and how to build one. Please refer to this article for more information on Android Archive file. And please refer to this article for more information on Xamarin binding project.

You will need the PDFNet Android SDK package and PDFNet Android native binaries built for Xamarin.Android to proceed. It is available by request from here.

In addition, Xamarin.Android is becoming more and more strict on binding rules, users will no longer be able to create customized Tools.dll with only the Tools project. PDFNetAndroid binding project will also be required. This is because PDFNetAndroid binding project uses PDFNet.jar for internal binding but this PDFNet.jar needs to match the PDFNet.jar inside the PDFViewCtrlTools.aar. PDFNetAndroid binding project is available by request from here.

• In the requested PDFNet Android SDK package, browse to /lib folder. Copy PDFNet.jar file to /lib/src/PDFViewCtrlTools/libs folder.
• Import the PDFViewCtrlTools project to Android Studio and make the desired changes. Compile an Android Archive file PDFViewCtrlTools.aar.
• Unzip PDFViewCtrlTools.aar and find PDFNet.jar file located in /libs folder of the unzipped PDFViewCtrlTools folder. This PDFNet.jar will be the EmbeddedJar used for PDFNetAndroid binding project.
• In /lib/android/Native folder, add the PDFNet.jar file obtained from previous step. In the same directory, remove the PDFViewCtrlTools.aar file and replace it with the PDFViewCtrlTools.aar file obtained from first step.
• In the requested PDFNet Android native binaries package, copy either full version or standard version of the native libraries to /lib/android/Native/nativeLib.
• Browse to /projectSrc/PDFNetAndroidXamarin. Open the PDFNetAndroidXamarin.sln provided in Xamarin Studio or Visual Studio. Check the Build Action for PDFNet.jar file, and make sure it is set to EmbeddedJar. Check the Build Action for PDFViewCtrlTools.aar file, and make sure it is set to LibraryProjectZip. Set Build Action for all native binaries to EmbeddedNativeLibrary.
• Clean and build PDFNetAndroid binding solution. A new PDFNetAndroid.dll and Tools.dll will be created in /lib/android/ folder. Use this new PDFNetAndroid.dll and Tools.dll in your application. Alternatively, you can also include the PDFNetAndroid project, FloatingActionButton project and PDFViewCtrlTools project in your application and make the binding project a project reference in your application project.

Part 5: Next steps

This concludes our introductory PDFNet for Xamarin.Android Tutorial. The completed tutorial project is available by request from here. For more help, please see the sample code, and other tutorials. You can also browse our public forum for more information about PDFNet. For details related to technical support, please refer to PDFTron support page.