Getting Started with Cross-Platform PDF Processing Using Xamarin.iOS and PDFNet SDK

Introduction

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

Note that the completed sample project described in Part 1 and Part 2 can be found in the samples folder located inside the PDFNet component package. The completed sample project described in Part 1-3 is available by request from here.

The tutorial is divided into 5 parts:

To complete this tutorial, you will need to install the latest version of XCode, which is required because its compilers are used by Xamarin. If you are using an out of date version of XCode you may encounter linker errors. You will also need to install and setup Xamarin.iOS as described in this article.

Part 1: Run the sample project.

  • Open the sample project: In Xamarin Studio, from the ‘File’ menu select ‘Open…’ and browse to ‘/samples/PDFNetiOSXamarinSample’ folder shown below, select PDFNetiOSXamarinSample.sln and click ‘Open’.
  • The project structure will resemble the following screenshot:
  • The project is now ready to run! Press ‘Run’ button to build the project and start the application. Note that if you don’t need the tools functionalities, you can use only PDFNetiOS.dll library and not set tool for PDFViewCtrl, i.e. remove the following code from the ‘PDFNetiOSXamarinSampleViewController.cs’:
ToolManager toolManager = new ToolManager (mPdfViewCtrl);
mPdfViewCtrl.ToolManager = toolManager;
    • The final application (running in iPhone simulator) will look like the following screenshot:
    • With tools functionality, long press on a blank field will bring up the tools popup menu:

Part 2: Create a new application with PDFNetiOS.dll and Tools.dll.

This part demonstrates how to create a brand new Xamarin.iOS application that uses PDFViewCtrl and Tools add-on to build a PDF viewer with a rich set of functionality. (If this is your first Xamarin.iOS project, it would be worth following Xamarin’s Xamarin.iOS Hello World project in this article before proceeding.)

  • Create a new Xamarin.iOS Application Project, i.e. Single View Application: In Xamarin Studio, from the ‘File’ menu select ‘New’ > ‘Solution’, choose ‘C#’ > ‘iOS’ > ‘Universal’ > ‘Single View Application’ template as shown below:
  • Add a reference to PDFNet: in Xamarin Studio, select ‘Edit References…’, browse to ‘/lib/ios folder, and add PDFNetiOS.dll to the references
  • Add reference to the Tools library: in Xamarin Studio, select ‘Edit References…’, browse to ‘/lib/ios folder, and add Tools.dll to the references
  • Specify compiler information: in the application sample project, select ‘Options’, under ‘iOS Build’ > ‘Additional Options’ > ‘Additional mtouch arguments’, add ‘–-compiler:clang++‘, and repeat this for all the build configurations:
  • Use LLVM optimizing compiler: under ‘iOS Build’ Advanced tab, check ‘Use LLVM optimizing compiler’:
  • You are now ready to use PDFNet and Tools libraries for your application!

Some tips to get started:

    • Initialize PDFNet with the following call before using any other PDFNet method:
PDFNet.Initialize();
PDFNet.SetResourcesPath(“pdfnet.res”);
    • To create a PDFViewCtrl control and set it as content view:
PDFViewCtrl mPdfViewCtrl = new PDFViewCtrl(this.View.Frame);
View.AddSubview(mPdfViewCtrl);
    • To include a PDF document compiled with the project:
      • Add the PDF document to the Resources folder (i.e. Resources/sample.pdf)
      • Make sure the Build Action of the document is set to BundleResource
      • Then this document can be accessed directly by the file name, i.e. “sample.pdf”
    • To set PDFViewCtrl associated with a PDFDoc from resources:
PDFDoc docToOpen = new PDFDoc(“sample.pdf”);
mPdfViewCtrl.Doc = docToOpen;
    • To set PDFViewCtrl associated with a PDFDoc from URL
var documents = Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments)
var cache = Path.Combine (documents, "..", "Library", "Caches", "Cache2.pdf");
mPdfViewCtrl.OpenURL(inUrl, “”, cache);
    • To use Tools with PDFViewCtrl:
ToolManager toolManager = new ToolManager (mPdfViewCtrl);
mPdfViewCtrl.ToolManager = toolManager;

Part 3: Create a new application with PDFNetiOS.dll and customized LibTools.a library.

In the previous section you have seen how to use PDFViewCtrl with the tools add-on. However, if you wish to customize the behavior, you will need to do so using the included Objective-C source code and then prepare the .a library for use in Xamarin. This section demonstrates how to build a Xamarin.iOS application that uses PDFViewCtrl and your own version of libTools.a to build a PDF viewer.

The following section covers the steps to create a .NET bindings for the Tools library and use it in your application. Refer to this article for more information regarding Objective-C binding with Xamarin.

Preparation: To use your own customized version of the PDFViewCtrlTools, you will need to create a static library of the tools using Objective-C. The static library will have the .a file extension, and will be embedded into the .NET assembly of the library project.

    • Create a Xamarin.iOS Binding Project: In Xamarin Studio, from the ‘File’ menu select ‘New’ > ‘Solution’, select ‘iOS Binding Project’ in the dialog shown below:
    • Add the static library to the project: in Xamarin Studio, select ‘Copy the file to the directory’. This should create a special file called libTools.linkwith.cs. Modify the LinkWith attribute to the following:
[assembly: LinkWith ("libTools.a", LinkTarget.ArmV7 | LinkTarget.ArmV7s | LinkTarget.Arm64 | LinkTarget.Simulator | LinkTarget.Simulator64, Frameworks = "SystemConfiguration Foundation CoreFoundation AVFoundation UIKit CoreGraphics CoreText CoreFoundation QuartzCore MediaPlayer", ForceLoad = true, LinkerFlags = "-ObjC -lz")]
    • Add a reference to the PDFNet library: in Xamarin Studio, select ‘Edit References…’, browse to ‘/lib/ios folder, and add PDFNetiOS.dll to the references
    • Create a Tool wrapper class: add a new Tool class file and add the following:
namespace pdftron.PDF.Tools
{
	public partial class ToolManager : pdftronprivate.ToolBase
	{
		private pdftronprivate.ToolManager mTool;
		public ToolManager(PDFViewCtrl ctrl)
		{
			mTool = new pdftronprivate.ToolManager (ctrl.__GetHandle ());
			mTool.ChangeTool (new Class(typeof(pdftronprivate.PanTool)));
		}
		public override UIView Tool
		{
			get
			{
				return mTool;
			}
		}
	}
}
  • The final project structure will look something like the following screenshot:
  • Use the Binding Library
    • Create a new Xamarin.iOS Application Project: i.e. Single View Application
    • Add a reference to the PDFNet library: in Xamarin Studio, select ‘Edit References…’, browse to ‘/lib/ios folder, and add PDFNetiOS.dll to the references
    • Add a reference to the binding project: add PDFViewCtrlTools project to the references
    • Specify compiler information: in the application sample project, select ‘Options’, under ‘iOS Build’…’Additional Options’…’Additional mtouch arguments’, add ‘-–compiler:clang++‘, and repeat this for all the build configurations
    • Use LLVM optimizing compiler: under ‘iOS Build’ Advanced tab, check ‘Use LLVM optimizing compiler’
    • You are now ready to use PDFNet and Tools libraries for your application! See ‘PDFViewCtrlTools’ project in ‘PDFNetiOSXamarinSample’ solution to get started!

Part 4: FAQ.

    • What is the Tools library?

PDFNet comes with built-in support for text selection, interactive annotation creation and editing, form filling and link following. These features have been implemented using PDFNet’s Objective-C API, and mapped to the idioms used in .NET using Xamarin C# bindings of Objective-C APIs. If you are interested in customize how users interact with the PDF, the tools source code is available by request on our website.

      • How come the Binding Objective-C Library described in Part 3 does not work in Visual Studio?
          Due to the interface differences between Xamarin Studio (on Mac) and Visual Studio (on Windows) for iOS binding project, currently iOS binding only works with Xamarin Studio on Mac. However, you will be able to use the libraries in Visual Studio on Windows if your project doesn’t require customized Tools library binding (i.e. You can create an iOS application with Visual Studio and use PDFNetiOS.dll and Tools.dll as references in the project, but you will not be able to bind your own libTools.a in Visual Studio).
      • What is the pdfnet.res file?
          This file contains fonts, CMaps and other standard PDF resources that are needed for the correct displaying of generic PDF documents (e.g., forms, text, free text annotations). If your documents are largely images and do not have text or annotations, then it may not be necessary. Here’s how to properly use this file in your project:
        • You can call PDFNet.Initialize() without the resource parameter, and use:
        PDFNet.SetResourcesPath("pdfnet.res");
        

        With this method you are handling installation of the resource file on your own. For example, the resource file can be downloaded on demand and saved at any location. When the resource file is ready for use it can be loaded using SetResourcesPath().

Part 5: Next steps.

This concludes our introductory PDFNet for Xamarin.iOS 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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s