The problem arose while converting an EMF into a PDF or while drawing an HDC-context taken from a PDF. The problem was connected to the Polyline(To) function. The function transformed an array of points with close value coordinates. Then, to draw a set of lines in a PDF, transformation of the
coordinates from HDC to PDF coordinates was necessary. For this transformation the LPtoDP function was used. But LPtoDP returns integer values. For example, this function transforms the (160, 74) and (159, 60) coordinates from EMF to (1, 1) and (1, 2) for a PDF. So a set of lines was generated as shown in the left picture. To improve the results, we have stopped using the LPtoDP function. Now Polyline(To) function gives the correct results.

Artem Golubnichenko

A group is assigned a state, which is either ON or OFF. States can be set programmatically or through the viewer user interface to change the visibility of content. In the typical case, content belonging to a group is visible when the group is ON and invisible when it is OFF. When a piece of optional content in a PDF file is determined to be hidden, the content is not drawn.

You may see all layers in PDF document on Layers tab. (for Adobe Reader) Go into the “View” menu and select “Navigation Tabs” and then choose “Layers”.

So this gives us an instruction on how to create Layered PDFs within PDF Creator Pilot.  In our example we’ve created a PDF with several layers. (example for VBScript)

' create pdf library object
Set PDF = CreateObject("PDFCreatorPilot.PDFDocument4")

' initialize PDF Engine
PDF.SetLicenseData "demo@demo", "demo"

' set document title
PDF.SetTitle "PDF with Layers", 1

' disconnect from library
Set PDF = Nothing

Hopefully from the example code and the example PDFs you should see how useful Layers can be.

Here you can download examples of PDF documents created by PDF Creator Pilot:
http://www.colorpilot.com/downloads/ContentGroupsExample.pdf
http://www.colorpilot.comdownloads/ContentGroupsExample_SourceCode.zip

Artem Golubnichenko
Project Manager of Virtual Printer

Today I want to talk about important improvements in the current version of the PDF Creator Pilot Library.

It was always one of the weakest things about the Library – it demanded huge amounts of memory to work with larger documents. Quite often clients were not able to create a document consisting of more than 100 pages, because they did not have enough memory. In this version, we have managed to open up a bottleneck, which helped us significantly reduce memory requirements. In short, if a page contains a lot of graphics, it also contains a lot of page operation commands. Keeping all these commands in memory was the bottleneck. We cached the commands into a temporary file, and that solved the problem.

The other improvement concerns conversion of EMF files to PDF files. We’ve improved the processing of paths and clipping regions. This was no trivial task, because the path processing toolset of the PDF format isn’t as rich as required by GDI. Clipping regions are the worst supported; there are no other region operations in a PDF except intersection. To adequately process an EMF, we had to support all operations defined in Set theory. For a long time the problem remained unsolved, however we have now left the problem behind us. Now these kinds of EMF files converted correctly.

This last bit of news should be of interest to those who use “non-standard” versions of the Library, such as the 64-bit variant or the static variant (which is for C++ only). We’ve found that the x64 build failed to convert EMF files, and the static library refused to work from VS2005. All of these problems have also been fixed.

Here are the current builds:

http://www.colorpilot.com/~builds/PDFCreatorPilot4_1_2492.zip
http://www.colorpilot.com/~builds/PDFCreatorPilot4_1_2492_x64.zip
http://www.colorpilot.com/~builds/PDFCreatorPilot4_1_2492_static.zip (18 Mb, contains both the Debug and the Release versions)

In the next release, we plan both to improve processing of TIFF files and to add support for CMYK TIFFs.

Vitaly Shibaev
Developer of PDF Library

First, let’s create a Visual C++/ATL project:

Click “OK” and then select “Allow merging of proxy/stub code”:

Click “Finish”. Studio creates a project for us. With the help of Solution Explorer, we can see the following files:

It’s just a shell. If we would compile and build the project at this stage, there would be a DLL-file without a single component.

To add a component to our project, let’s review the “FirstCOM.idl” file. It’s the file that contains the definitions of the interfaces.

So far, this is all that file contains (comments have been removed):

import "oaidl.idl";
import "ocidl.idl";
[
    uuid(0652E0B7-4360-4542-8D22-8F52940AEFCE),
    version(1.0),
    helpstring("FirstCOM 1.0 Type Library")
]
library FirstCOMLib
{
    importlib("stdole2.tlb");
};

This means that there is a library of types named FirstCOM that lacks the types. There are two attributes, though, “version” that holds the version of our library and “helpstring” that should hold a description of the library.

Let’s add a component. Select “Add->Class” from the context menu:

Select “ATL Simple Object”:

Now let’s enter the class information, as illustrated below:

Click “Finish”. Studio will create all the necessary files and add the necessary constants to the resource files. “FirstCOM.idl” should now look like this:

import "oaidl.idl";
import "ocidl.idl";
[
    object,
    uuid(5F9CB782-BDE1-48E3-91CC-E8EC0280EFA0),
    dual,
    nonextensible,
    helpstring("IFirstCOMClass Interface"),
    pointer_default(unique)
]
interface IFirstCOMClass : IDispatch
{
};
[
    uuid(FD0B5C1A-6E02-4EFA-958B-046A0AD17381),
    version(1.0),
    helpstring("FirstCOM 1.0 Type Library")
]
library FirstCOMLib
{
    importlib("stdole2.tlb");
    [
        uuid(61A52F01-320D-41E4-B5F2-A59C6E220292),
        helpstring("FirstCOMClass Class")
    ]
    coclass FirstCOMClass
    {
        [default] interface IFirstCOMClass;
    };
};

We have added a description of a class (component) with some interface IFirstCOMClass to the description section of the library (library FirstCOMLib{…}). The definition of that interface has been automatically added at the beginning of the file.

Now we have created a component (class) FirstCOMClass and declared its interface (IFirstCOMClass). This interface will be used to provide access to our component.

Now let’s define methods and functions for our component. For instance, let’s add two methods, one that would return the sum of two numbers and one to return the length of a string. Also, we’ll add a property “Author” to allow read and write access. To do that, in the section

interface IFirstCOMClass : IDispatch
{
};

we should add definitions of our methods and properties:

interface IFirstCOMClass : IDispatch
{
    [id(1)] HRESULT CalcSumm([in] LONG lParam1, [in] LONG lParam2,
        [out, retval] LONG* retVal);
    [id(2)] HRESULT GetStringLen([in] BSTR strParam,
        [out, retval] LONG* retVal);
   
    [propget, id(3)]
    HRESULT Author([out, retval] BSTR* retVal);
    [propput, id(3)]
    HRESULT Author(BSTR strValue);
};

Where:
[id(N)] – defines the identification number of a method or a property (This number must be unique.);
[in] denotes an input parameter;
[out, retval] – denotes an output parameter.Important: The read properties and the write properties should have the same name and identification (id).

Now let’s declare the methods described in CFirstCOMClass. Locate the “CFirstCOMClass.h” and open it. There is this:

class ATL_NO_VTABLE CFirstCOMClass :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CFirstCOMClass, &CLSID_FirstCOMClass>,
    public IDispatchImpl<IFirstCOMClass, &IID_IFirstCOMClass,
        &LIBID_FirstCOMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>

This declaration allows the compiler to bind the COM class and its interface with a real C++ class.

Add this to the public section:

public:
    STDMETHOD(CalcSumm)(LONG lParam1, LONG lParam2, VARIANT_BOOL* retVal);
    STDMETHOD(GetStringLen)(BSTR strParam, VARIANT_BOOL* retVal;
    STDMETHOD(get_Author)(BSTR* sVal);
    STDMETHOD(put_Author)(BSTR sVal);

It is recommended to declare a constructor and a destructor and then move their implementation into file “CFirstCOMClass.cpp”.

Important: The read and write accessor methods of the property “Author” must begin with the “get_” and “put_” prefixes.

Then we create the private section. Here we will hold the value of the “Author” property.

private:
    CComBSTR m_author;

In “CFirstCOMClass.cpp”:

// FirstCOMClass.cpp : Implementation of CFirstCOMClass
#include "stdafx.h"
#include "FirstCOMClass.h" // CFirstCOMClass CFirstCOMClass::CFirstCOMClass()
{
    // initial value of the property Author
    m_author = OLESTR("Vasya");
}CFirstCOMClass::~CFirstCOMClass()
{
}

STDMETHODIMP CFirstCOMClass::CalcSumm(LONG lParam1, LONG lParam2, LONG* retVal)
{
    // if pointer is invalid - return error
    if (!retVal)
        return S_FALSE;
    *retVal = lParam1 + lParam2;

    // no errors - return OK
    return S_OK;
}

STDMETHODIMP CFirstCOMClass::GetStringLen(BSTR strParam, LONG* retVal)
{
    // if pointer is invalid - return error
    if (!retVal)
        return S_FALSE;

    CComBSTR str(strParam);
    *retVal = (LONG)str.Length();

    // no errors - return OK
    return S_OK;
}

STDMETHODIMP CFirstCOMClass::get_Author(BSTR* retVal)
{
    // if pointer is invalid - return error
    if (!retVal)
        return S_FALSE;

    // don't forget to allocate memory for the result string
    *retVal = SysAllocString((BSTR)m_author);

    // no errors - return OK
    return S_OK;
}

STDMETHODIMP CFirstCOMClass::put_Author(BSTR newVal)
{
    CComBSTR newAuthor(newVal);
    m_author = newAuthor;

    // no errors - return OK
    return S_OK;
}

Our COM library is almost ready. We have created the library itself, a class, and its interface. We’ve also added the implementation of the interface. It would be great to know the name of our COM library and its class. Their names are in the “FirstCOMClass.rgs”. Open it and find “VersionIndependentProgID”:

VersionIndependentProgID = s 'FirstCOM.FirstCOMClass'

The name of our library is FirstCOM, and the class is “FirstCOM.FirstCOMClass”.

When we add more classes, for each there will be an “.rgs” file with the following text:

VersionIndependentProgID = s 'FirstCOM._class_name_'

After building the project, in the “Debug” or “Release” folder we will find “FirstCOM.dll”, our COM library. To use it from another computer, it must be registered in its operating system. That can be done with an installer or with this command:

regsvr32 FirstCOM.dll

Now, let’s check whether it works. Create a text file “test.vbs” and copy the following Visual Basic Script into it:

' create COM object, use library name and class name
Set comObj = CreateObject("FirstCOM.FirstCOMClass") ' test CalcSumm method
res = comObj.CalcSumm(1, 2)
WScript.Echo "1 + 2 = " & res' test GetStringLen method
res = comObj.GetStringLen("QwertY123")
WScript.Echo "Len = " & res

' read property Author
auth = comObj.Author
WScript.Echo "Author = " & auth

' read property Author
comObj.Author = "Petya"
auth = comObj.Author
WScript.Echo "Author = " & auth

' cleanup
Set comObj = Nothing

Save and launch the file this way:

wscript.exe test.vbs

or this:

cscript.exe test.vbs

If we did everything correctly, we should see the results of our tests.

We could execute it from PHP:

<?php
// create COM object, use library name and class name
$comObj = new COM("FirstCOM.FirstCOMClass") or die("Can't create COM."); // test CalcSumm method
$res = $comObj.CalcSumm(1, 2);
echo("1 + 2 = " . $res);// test GetStringLen method
$res = $comObj.GetStringLen("QwertY123");
echo("Len = " . $res);

// read property Author
$auth = $comObj.Author;
$echo("Author = " . $auth);

// read property Author
$comObj.Author = "Petya";
$auth = $comObj.Author;
echo("Author = " . $auth);

// cleanup
$comObj = null;
?>

If you want to learn how to use COM from C/C++ and .NET, look here.

You can download the source of the COM library here.

Max Filimonov.

Development Tools

1. Subversion (SVN) Control

The life of a programmer would be unbearable without a source control manager . As of this writing, we have executed 2387 commits in the PDF Creator project using the Tortoise SVN, (http://tortoisesvn.tigris.org/). Since every mistake would cost a lot, we try to follow this rule – one that we would recommend to everyone: Always commit smaller portions of the code. Every commit must correspond to a single task!

This way it is (a) easier to find an error during rollbacks (every commit changes a small amount of source code), (b) often easy to discover an error before the commit just by looking at it, and (c) easier for colleagues to be aware of the changes in the source code, since all they have to do is read the comments and look at the smaller portions of the code.

Of course, this is not possible in all cases, and sometimes we do have to perform huge commits. Still this is a rule worth following. After all, it is one of the refactoring rules: Change smaller portions of the code, preserving its workability between sessions.

Two more source-control rules:

1. There must always be two versions in the SVN – a version that compiles and a workable version. It is easy to create code that compiles, but the real aim is its correctness.
2. Text comments should be supplied to every commit. This is also a good way to check whether the commit implements only a single task. If a comment describes several targets instead of just one, the rule has been violaled.

2. Bug Tracker

We use Mantis (http://www.mantisbt.org/). PDF Creator is the base for a number of other products – converters, virtual printer, etc. (See http://www.colorpilot.com/developer.html) The number of its users is much higher than the count of those who purchased the base product. We needed to simplify communications between the developers and the users of the products.

To make the things clear for those who have never used a bug tracker, here is a sample of how it works. The virtual printer developers receive (from the users of their product) information about an incorrect conversion into a PDF. The Virtual Printer gets an EMF file from input, then our library converts it. The information from the user is used to create a “ticket” for the library developers. The ticket is accompanied by a description of the problem and the problematic EMF file. Then we investigate the degree of severity of the problem to find out how critical it is and appoint a specific developer to work on a fix. After the problem has been resolved, the ticket gets closed. Everybody concerned is notified and may keep an eye on what is going on.

3. Technical Support

To manage our correspondence with clients, we use RT (http://bestpractical.com/rt/). We need the system for convenient storage of the archive, as well as assurance that every person who should read the messages does receive them.

Ideally, (2) and (3) might have been united into a single service, so that the clients were aware of their problem status. In the example above, the virtual printer user would keep an eye on developers’ correspondence concerning his problem. One such system that could help is FogBugz (http://fogcreek.com/FogBugz/).

4. Technical Documentation

Our internal technical documentation project, Squirrel (http://www.colorpilot.com/squirrel.html), isn’t widely known, however, it is publicly available. The program makes it easier to create a CHM-version of the documentation, integrates with SVN, and permits creation of the online documentation. See http://www.colorpilot.com/pdfcreatorpilotmanual/PDF_Creator_Pilot.html for the results of Squirrel’s work.

5. Development Environment

We use Visual Studio 2008, C++, and C#.

6. Refactoring Tools

There are no built-in tools for C++ refactoring in Visual Assist X (http://www.wholetomato.com/), so we have to use a third party plug-in for Visual Studio.

7. Unit Tests in C++

Here we use UnitTest++ (http://unittest-cpp.sourceforge.net/).

8. Profiling Tools

To diagnose memory leaks, we use http://www.colorpilot.com/~vit.shibaev/mmgr.zip. (I described that tool in one of my previous articles which you can find here: http://www.colorpilot.com/blog/about-pdf-creator-39/.) To control performance, we also use the Intel VTune, from time to time.

Project Organization

PDF Creator is a library for PDF processing: creation, reading, modification, text extraction, etc. Currently, the project exists as a solution with 18 sub-projects in Visual Studio 2008. There are five general types of sub-projects.

1. The Library Core

Here we define all the logic of PDF processing. This project is always in the process of modification. One of our old dreams (and still a dream today) is to make the core cross-platform. The biggest obstacle is the fact that EMF is a private Windows format. To make our dream come true, we should separate the conversion from the cross-platform part.

2. Client Interfaces

Two of the projects implement the client interfaces. One of them implements the COM interface; the other one implements a static library. The COM interface delegates its tasks to the static library; the static library forwards them to the core. No code is duplicated.

The static library isn’t advertised on our site, however every client may receive it together with the COM version. The static library contains some undocumented features that allow users to get some additional information about a document. If you are a developer and your product is intended to view PDFs, these features may be very useful for you.

3. Test Projects

1. Non-automated tests for the COM interface. A set of APIs that form and render PDF documents immediately after their launch.
2. Unit tests for the static library and the core. In addition to those described immediately above, the unit tests check the internal state of the classes, handle errors, etc.
3. Projects that check the EMF-conversion. The first one (written in WTL) converts the specified EMF file into a PDF. Its interafce is minimalistic, looking very much like our online service http://www.colorpilot.com/pdflibrary_convert-emf-to-pdf.html.
   The second one (written in C#) are a work in progress. However, it is already possible to convert all PDFs from a folder and to instantly review the results. This provides a significant speed increase during the testing process, which is especially great since we’ve got hundreds of test metafiles already.

4. Auxiliary Projects

These include a font-processing library (that parses TrueType and Type1 fonts, works with encodings, and modifies the TrueType fonts), font installer, working with the keys, etc.

5. Third Party Open-Source Products

PDF is a complex format. It is based on many areas of science, multiple algorithms, and formats. It involves compression and encryption algorithms, various image and font formats, color spaces, etc. A big part of our implementation is based on open source projects with a free license, for instance, CxImage, ZLib, LibJPEG, Lcms, and UnitTest++.

Vitaly Shibaev
Developer of PDF Library

C:\Windows\system32\regsvr32 PDFCreatorPilot.dll
C:\Windows\system32\regsvr32 HTML2PDF.dll

Second, you need to re-create interop wrappers for these components. This can be done with standard .NET SDK utility – TlbImp.exe (C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin\TlbImp.exe)
Example:

TlbImp.exe PDFCreatorPilot.dll /out:Interop.PDFCreatorPilotLib.dll
TlbImp.exe HTML2PDF.DLL /out:Interop.HTML2PDFAddOn.dll

Note: It is not necessary to regenerate wrappers directly on the server, you may do it on the developer machine and copy theese wrappers to the server.

Third, you need to place these interop wrappers into the appropriate directory on the new server. For ASP.NET it is the “bin” folder of that application. For the rest applications you need to place wrappers near the exe module (at the same folder).

Filimonov MaximDeveloper of PDF Library

We wanted to check whether our library (this one) works well with PHP. Below is the small script that we had created. All it was to do: create a plain PDF Document, and output it into the client’s stream:

<?
  $PDF = new COM("PDFCreatorPilot.PDFDocument4") or die("Unable to load instanciate.");
  $PDF->SetLicenseData("demo", "demo");
  $PDF->Compression = 1; // coFlate

  $fnt = $PDF->AddBuiltInFont(1, false, false);
  $PDF->UseFont($fnt, 14);
  $PDF->ShowTextAt(30, 30, "Hello from PHP!");

  $size = $PDF->GetBufferSize();
  $buffer = $PDF->GetBuffer();
  header("Content-type: application/pdf");
  header("Content-Disposition: attachment; filename=test.pdf");
  header("Content-Length: $size");
  echo $buffer;
  $PDF = null;
?>

The script did not work as expected.

The reason was: PHP does not work well with the VARIANT type representing VT_ARRAY. PHP easily converts all other COM types, and permits you to do with them whatever you wish. This is what the PHP script said about our $buffer:

echo var_dump($buffer)."\n";
echo variant_get_type($buffer)."\n";
// output:
// 8209
// object(variant)#2 (0){
// }

The variable that we received was impossible to convert into any COM type, since PHP reported an “unsupported type”.

We’ve found a solution. PHP seems to be unable to convert a VT_ARRAY into a native PHP array, but it permits us to access a COM array’s data. Both, “for” and “foreach” work fine.

Here is the working script:

<?
  $PDF = new COM("PDFCreatorPilot.PDFDocument4") or die("Unable to load instanciate.");
  $PDF->SetLicenseData("demo", "demo");
  $PDF->Compression = 1; // coFlate

  $fnt = $PDF->AddBuiltInFont(1, false, false);
  $PDF->UseFont($fnt, 14);
  $PDF->ShowTextAt(30, 30, "Hello from PHP!");

  $size = $PDF->GetBufferSize();
  $buffer = $PDF->GetBuffer();

  header("Content-type: application/pdf");
  header("Content-Disposition: attachment; filename=test.pdf");
  header("Content-Length: $size");

  // $PDF->GetBuffer() return a VARIANT array (VT_ARRAY) with elements of type VT_UI1, so we have to
  // transform them into char ourselves.
  foreach ($buffer as $byte)
  echo chr($byte);

  $PDF = null;
?>

It works. Good luck and take care when you have to use COM from PHP.

Filimonov Maxim
Developer of PDF Library

1. Create an Interop-wrapper
2. Copy the wrapper into a specific folder
3. Attach the namespace libraries to the application

To create the Interop-wrapper of PDF Creator Pilot (i.e. a wrapper that would make it possible to call unmanaged COM-object code of the library from the managed code of an ASP.NET application), we should use one of the standard utilities from the .NET SDK – TlbImp.exe (C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin\TlbImp.exe)

Example:

TlbImp.exe PDFCreatorPilot3.dll /out:Interop.PDFCreatorPilot3Lib.dll

Then we need to copy the wrapper into the “bin” subfolder of the web-application root folder. (If that folder does not yet exist, we will have to create it.)

Example:

If our web-application is located in “C:\Inetpub\wwwroot\MyApp”, then we should put the wrapper into “C:\Inetpub\wwwroot\MyApp\bin”.

To attach the web-application to the namespace library, we should append the following line to the “.aspx”-file:

<%@ Import Namespace="Interop.PDFCreatorPilot3Lib.dll" %>

After that, a COM-object of PDF Creator Pilot may be used from ASP.NET.

Example:

<%@ Import Namespace="System" %>
<!-- other import directives are here -->
<%@ Import Namespace="Interop.PDFCreatorPilot3Lib.dll" %>
<HTML> <HEAD>
  <TITLE>Test</TITLE>
  <SCRIPT language="C#" runat="server">
    void ButtonPerform_Click(object sender, System.EventArgs e)
    {
      PDFDocument3Class pdf = new PDFDocument3Class();
      pdf.StartEngine("demo@demo", "demo");
      pdf.AutoCreateURL = true;
      // set other options if needed
      pdf.BeginDoc();
      // do something
      pdf.EndDoc();
    }
  </SCRIPT>
</HEAD>
<BODY>
  <!-- here page content goes -->
  <FORM runat="server">
    <INPUT type="button" id="ButtonPerform" value="Click Me"
      OnServerClick="ButtonPerform_Click" runat="server" />
    <!-- or another vaiant -->
    <asp:Button id="ButtonPerform1" Text="Click Me"
      OnClick="ButtonPerform_Click" runat="server" />
  </FORM>
</BODY>
</HTML>

Maxim Filimonov
Developer of PDF Library

Here I talk about various tools that may be used to develop the unit tests with C++, in particular about those that we use in PDF Creator, and about the way we deploy it.

As PDF Creator evolved, it started to become more evident that there was a need for an easy-to-use testing procedure. The huge code base, lots of clients, quirks of the PDF format and of the library itself — these were the factors that turned every change in the code into a difficult task. Currently, every time we release a new version (actually, even more frequently), we pass the library through a set of visual tests. Some tests produce PDF files; their quality and correctness may be checked visually. Other tests convert EMF files, producing a visible result, too. There are also ASP and VB scripts among the tests. The set of the tests grows constantly, however, even when the library passes through all of them OK, there is no guarantee that all the functions of the library have been retained.

Because of that, while developing PDF Creator 3.9, we paid a lot of attention to the refactoring of our code. One of our refactoring goals was to improve testability of the code. After we determined the goals, we had to choose an environment for creation of the test units. Initially, it was a choice between the classic CppUnit (http://sourceforge.net/projects/cppunit/) and the Boost.Test Library (http://www.boost.org/libs/test/doc/index.html).

Here is a summary of the requirements that we imposed on the testing environment:

1. Writing a test should require minimal preparation.
2. Test results should be clearly revealed and easily observed. Integration into Visual Studio is a plus.
3. The environment must be cross platform. (In the future, we plan to make the PDF library platform independent.)
4. The size of the environment must be small.
5. Test units must be automatically excluded from the Release build.

I’ve had some experience with the CppUnit before, and I was not pleased. It failed to pass requirements 1, 2, and 4. It contains a lot of redundant stuff we did not actually need. The interface of CppUnit is not trivial, and we would have to add a lot of code ourselves. Negative. Especially after nUnit.

We were going to use Boost.Test, however, we discovered that we would have to include the entire Boost Library, with all its bells and whistles. I am not a big expert in Boost. If there is a way to use Boost.Test without adding the entire library to the project, please tell us how. We had to reject Boost.

Then we had to look for an alternative. I think that http://www.gamesfromwithin.com/articles/0412/000061.html is a must read. It is an excellent comparison of various test unit tools.

After reading the article, of course, we looked into CxxTest (http://cxxtest.sourceforge.net/), and it disappointed us. Documentation is huge, but not very understandable. The latest revision was outdated – from 2004! Compilation requires Perl ! Another wrong environment.

We looked into some other variants, and none of them seemed to fit. With our hope of finding anything slowly dying already, we found UnitTest++. (Applause!) You can see it here: http://unittest-cpp.sourceforge.net/. One of the UnitTest++ developers, Noel Llopis, is also the author of the excellent article referenced above. Here is his description of his own product: http://www.gamesfromwithin.com/articles/0603/000108.html

UnitTest++ fits all 5 of our requirements. It’s trivial to write a test. The environment is easy to understand and cross-platform. Whenever a test fails, it is detached into a separate project. The toolset seamlessly integrates into Visual Studio. When the tests are run, the output window displays the number of tests, elapsed time, and reviews of the failed tests. It was like a dream come true.

We started to use UnitTest++ in PDF Creator. Soon we discovered that we did not receive its excellent features “for free”. Let’s look under the hood of a typical test:

TEST(SomeTest)
{
const int expected = 123;
int res = testedFunction();
CHECK_EQUAL(res, expected);
}

During compilation, the TEST macro turns into a class named TestSomeTest, that inherits from an unknown class UnitTest::Test. The last line of the code after that looks like this:

void TestSomeTest::RunImpl(UnitTest::TestResults& testResults_) const

As you can see, the body of the test is created by RunImpl. After we looked inside the CHECK_EQUAL macro, we understood that it may render correct results only under some limited circumstances — only inside methods, defined with the Test macros. That meant that we had to forget about normal refactoring. In particular, it is impossible to separate a test method.

It is also impossible to temporarily disable a method, since it is a macro. To switch a test off, one has to comment it.

Another problem: IntelliSense doesn’t always work properly when a test method is being written. Evil consequences of the use of macros, again. It is also hard to extend and improve the functionalities of UnitTest++. Perhaps that’s the reason why it has not been updated for quite a long time – since April, 2007.

However, it is not a bad environment. Refactoring problems may be by-passed. The other problems may be put up with. In my next article, I plan to provide more details about testing with UnitTest++ and the process of hunting for memory leaks with the help of memleaks.

Vitaly Shibaev
Developer of PDF Library

In my opinion, the most important improvement in this version is how it renders texts. Any kind of text renders correctly, as searchable and clipboard compatible. In general, the library generates smaller output files, especially when the CJK fonts are used.

We also got rid of memory leaks, and along the way we have seriously refactored the code. As a result, the library works faster and is more stable.

Instead of using BoundsChecker to catch the leaks, we used great two code files (http://www.colorpilot.com/~vit.shibaev/mmgr.zip) that actually saved us. Just include them in your project, by adding “#include “mmgr.h”” in a header file, and you’re all set. After that, in the same location as the application executable, three log files will be created (memleaks.log, memory.log and memreport.log). The “memleaks.log” file will report any and all leaks. When you turn on the “memreport.log” in “mmgr.cpp” (by default it’s turned off), it provides detailed reports about all memory allocations and deallocations (when, how much, etc.). I would recommend mmgr to all C++ developers.

There are some more important improvements in the library. It now renders CMYK JPEG images. This feature is vital for users with special image quality requirements, especially in pre-press.

Other improvements are related to interactive forms and annotations. First, file sizes have been optimized. In most cases, their size will be 2-3 times smaller than previously. Second, we’ve improved the rendering of Unicode symbols.

We’ve added the Caption property to the radio button descriptions. Caption is now a part of the control. It’s coded like this:

PDF.PDFPAGE_CreateControl_RadioButton “rb_group”, 0, 0, 100, 20
PDF.PDFANNOTATION_Caption = “Place some text here”

Revealing some of our secrets, we’ve reorganized and improved our code in version 3.9. We added some unit tests (not for all the code yet). The process of choosing a proper unit test environment for C++ was of special interest. It would be a good topic for the next time.

Vitaly Shibaev
Developer of PDF Library