New Tools for Working with PDF Files

For some time now the Synergy/DE Code Exchange has included an item called PDFKIT which essentially contains a set of DBL wrapper code that allows the open source Haru PDF Library to be used from DBL. The work done in PDFKIT was a great start and has been used successfully by several developers, but I don’t think that anyone would disagree with me if I were to suggest that it’s not exactly the most intuitive software to use, and it’s not exactly what you would call well documented either; just like the underlying Haru library!

So as time permitted for the last few weeks I have been working on what I hope is an improved solution. I certainly didn’t want to totally reinvent the wheel by starting from scratch, as I mentioned PDFKIT was a great start, but I did want to take a slightly different approach that I thought would be more useful to a wider number of developers, and I did want to make sure that complete documentation was included. What I came up with is called SynPSG.PDF, and it is available in Code Exchange now.

When you download and extract the zip file (SynPSG_PDF.zip) you will find that it contains these main elements:

• pdfdbl.dbl
  • This is the DBL code that wraps the Haru PDF library and is taken directly from the latest version of PDFKIT.

  Haru PDF Library DLL’s

  • The same DLL’s that are distributed with PDFKIT. Refer to the documentation for instructions on where to place these DLL’s.
• SynPSG.PDF.dbl
  • A source file containing the new API that I have created.
• SynPDG.PDF.vpw
  • A Synergy/DE Workbench workspace that can be used to build the code, as well as build and run several sample programs that are also included (this is a Workbench 10.3.1 workspace and will not work with earlier versions of Workbench).
• SynPSG.PDF.chm
  • A Windows help file containing documentation for the new API 

You don’t need to use the Workbench configuration that I have provided, if you prefer you can simply include the pdfdbl.dbl and SynPSG.PDF.dbl files into the build for your subroutine library. But remember that both of these files contain OO code, so you will need to prototype that code with DBLPROTO.

As you will see when you refer to the documentation, most things in the API revolve around a class called PdfFile. This class lets you basically do four things:

1. Create a PDF file.
2. Save the PDF file to disk.
3. View the PDF file by launching it in a PDF viewer application.
4. Print the PDF file to a printer.

I’m not going to go into a huge amount of detail about creating PDF documents or using the API here because these topics are discussed in the documentation, but I will mention a couple of basic things.

PDF documents inherently use an X,Y coordinates system that is based on a unit called a device independent pixel. These pixels are square and are 1/72 of an inch in each direction. The coordinates system that is used within pages of a PDF document is rooted in the lower left corner of the page which is assigned the X,Y coordinate 0,0. The width and height of the page in pixels depends on the page type as well as the orientation. So for example a standard US Letter page in a portrait orientation is 8.5 x 11 inches, so in device independent pixels it has the dimensions 612 x 792.

With most PDF API’s you work directly with this coordinates system, and you can do so with this API also, but doing so can require a lot of complex calculations, and hence can be a slow process. But often times when we’re writing software it is convenient for us to work in simple “rows and columns” of characters, using a fixed-pitch font. The new API makes it very easy to do just that, meaning that results can be produced very quickly, and also meaning that existing report programs (that already work in terms of rows and columns) can be easily modified to produce PDF output.

Here is an example of a simple row / column based report that took only a few minutes to create:

Of course there are times when you need to produce more complex output, and the new API lets you do that too. To give you an idea of what it is capable of, here’s a screen shot of a mock up of a delivery ticket document that I created while working on a recent customer project:

As you can see this second example is considerably more complex; it uses multiple fonts and font sizes, line drawing, box drawing, custom line and stroke colors, etc. And although not shown on these examples, there is of course support for including images also.

The new API is currently available on Windows under traditional Synergy. It should be possible to make the code portable to other platforms in the near future, and .NET compatibility is definitely in the pipeline. The software requires the latest version of Synergy which at the time of writing is V10.3.1b. You can download the code from here:

https://resourcecenter.synergex.com/devres/code-exchange-details.aspx?id=245

It is early days for this new API and I have many ideas for how it can be extended and enhanced. I am looking forward to working on it some more soon, and also to receiving any feedback or suggestions that you may have.