PDFLib: An Introduction

Foreword 

This post assumes you have purchased the PDFLib toolkit and have obtained a license key.  We will be using the .NET version of PDFLib 7.  This post also assumes you have installed Visual Studio and the .Net Framework Version 4.5.1. The .Net Framework can be obtained from Microsoft here.

The PDF Lib Toolkit 

The PDF Lib toolkit is software designed to simplify the programmatic creation of PDF files.  VDS uses this toolkit in some of our solutions to produce PDFs for forms, invoices, and photo albums.  This post will attempt to introduce users to the initial setup of a PDF creation program as well as the basic features and concepts behind the PDFlib toolkit

We will begin by creating a new Console Application in Visual Studio.  Open Visual Studio and select File->New->Project.  In the dialog that appears select Visual C# from the templates menu and then select Console Application.  I named my solution PDFLibIntro.

   

You should now have a solution that looks like this:

   

Before we get started go to your Solution Explorer and find App.Config. Open it and copy what you see below there.

  

Since PDFlib 7 is somewhat old, the useLegacyRuntimeActivationPolicy parameter allows us to load it in .Net Framework 4.5.1. 

Once you have done this go to your Solution Explorer and right click on References and click Add Reference.  Navigate to where you have saved the pdflib_dotnet.dll file and add that reference to the solution.  You should see the reference now in your Solution Explorer.

   

After this you can add a Using reference to PDFlib_dotnet.  Do this as well as copy the following code in the Main method into your solution:

   

Using the PDFlib_dotnet library now lets us create an instance of the PDFlib class.  This class is what allows us to create new pdf documents.  The first call to set_parameter sets the error policy to “return” which means we want methods that encounter an error to return an error code as opposed to throwing an exception.  The second policy sets your license key which allows you to use the class.  Replace “my_license” with the license you obtained in order to use the PDFlib class. 

 Now add the following lines to your solution:

   

Now we need to introduce the idea of scope.  In PDFlib functions can only be called within the proper scope.  When we initialize the PDFlib object we are within the “object” scope.  When we call begin_document we move into the “document” scope.  A second call to begin_document here would throw an error.  The above code shows a way of trapping for these errors so we can catch and rectify them while building our solution.  The call to get_errmsg gets the most recent error the PDFlib object has.  In this case, since we have set the error policy to “return” we are checking for a -1 (the error code) to see if we need to get the error. 

Now add the following code:

 

The set_info method allows us to set properties of this new docume  nt that a user can see by right clicking and selecting properties on the pdf file that is generated.  The load_font method tells the PDFlib program to search your system for the font you specify in the encoding you specify.  Again, we trap for an error code of -1 to insure the PDFlib api can find the font.  If it does, it is assigned to an integer value that the API understands to reference the font you specify. 

Now add the following code:

 

Before we get into these methods we need to discuss the concept of optlists. In PDFlib an optlist is a list of options specific to the method in question that is usually passed as the last parameter to the method.  Optlists allow us to specify a dynamic amount of parameters as a string opposed to having to pass them individually to the method.  When you do not specify a parameter in the optlist the default value for that parameter is chosen by PDFLib.  

We see in the begin_page_ext method that it accepts two parameters and an optlist.  The two parameters at the beginning are width and height in pixels.  Rather than having to find out the width and height of a standard letter sized page I input 0 and instead specify that I want a letter sized page width and height in the optlist. 

Calling the begin_page_ext method also puts me in the “page” scope.  This means that I can now call “page” methods on the page I just created.  It is possible to “suspend” a page so that I can work on another page before coming back and finishing this one.  A good use of this is when you don’t know the total number of pages you will have until the end and need a Page X of Y style footer.  You can suspend each page until you are done placing content then “resume” each page and add the pagination. 

We now have access to the page so let’s put something on it.  We create an optlist string specifying the fontsize parameter as well as the font that we loaded above.  We then call the fit_textline method which places a line of text where the top left of the fitbox starts at the position we specify. 

 Now is a good time to introduce PDFlib’s somewhat unusual positioning system.  A letter sized page is 612 pixels wide by 792 pixels tall.  In PDFlib, the pixel in the x-axis are counted left to right.  So when we see the fit_textline method above using 35 as the second parameter, we are saying we would like the line to start 35 pixels from the left of the page.  However, PDFlib counts the pixels on the Y-axis from bottom to top.  That means that a position of 0 is referring to the very bottom of the page.  In order to get a position near the top of the page I selected 700 as the starting point.  

Knowing all of this, we call fit_textline with the text we want placed, the x position, the y position, and the optlist that specifies the font and size of the text.  The text is now placed on the page so we call end_page_ext to end the page and the “page” scope.

 Now add the following code:

 

You will need to add the using reference for System.IO in order to use the File class.  By calling the end_document method you end the “document” scope.  The get_buffer method gets the binary representation of the file.  Create the saveFile string as whatever location you would like your document saved to.  Then, by calling File.WriteAllBytes you write the entire binary file to the location you specified in saveFile. 

Congratulations! You have just made your first pdf creation program.  You should now be able to run your solution and a pdf should be generated at the location you specified. It should look something like this:

   

Right now you only have the ability to create lines of text but in subsequent posts we will discuss how to fit whole paragraphs, draw images, fit images, places tables and more.