NPW Usage

Nyctergatis PDF Writer (NPW) - C library to write simple PDF files.

Author:

Yves Piguet

See also:

http://nyctergatis.com (home of NPW project)

Features

The main goal of NPW is simplicity, to the cost of completeness. PDF files are more difficult to write than Postscript files, because they require cross-reference tables and the computation of file offsets.

NPW is made of a base set of functions and data structures, NPWBase, which can be used as a wrapper around the graphics and text commands which define page contents. NPWGraphics provides support for most of the graphical and textual PDF commands. NPWText adds support for text layout based on font metrics, including wordwrap and text flow across multiple rectangles and pages, with optional support for markup to have multiple character styles and paragraph formats; NPWTextMarkup implements such a markup. NPWInfo adds support for information metadata such as author and creation date.

Usage

NPW requires the definition of two callback functions, one for memory allocation/reallocation/deallocation, and one for output. Callbacks based on malloc/realloc/free and fwrite are defined in NPWStdAlloc.c and NPWStdOutput.c, respectively.

Here is how NPW's main data structure, of type NPW, can be initialized to write a PDF file as "doc.pdf":

    #include "NPWBase.h"
    #include "NPWStdAlloc.h"
    #include "NPWStdOutput.h"
    #include <stdio.h>

    NPW npw;
    FILE *fp;
    fp = fopen("doc.pdf", "wb");
    NPWInit(&npw);
    NPWSetAllocCallback(&npw, NPWAllocStdlib, NULL);
    NPWSetWriteCallback(&npw, NPWWriteStdOutput, (void *)fp);

Each page is added with a pair of calls to NPWBeginPage and NPWEndPage, with commands which produce displayed material inbetween. Each page can have a different size, given (like all other sizes and positions) in points (1/72 inch).

    NPWBeginPage(&npw, kNPWPaperWidthA4, kNPWPaperHeightA4);
    ...
    NPWEndPage(&npw);

To add graphical commands, you can either do it by hand with calls to NPWWrite, NPWWriteInt, NPWWriteFloat or NPWWriteString, or rely on commands defined in NPWGraphics.h:

    NPWWrite(&npw, "10 10 m 100 100 l S\n", -1);

is equivalent to

    #include "NPWGraphics.h"
    NPWGraphicsMove(&npw, 10, 10);
    NPWGraphicsLine(&npw, 100, 100);
    NPWGraphicsStroke(&npw);

To add meta-informations such as the author or the creation date, enclose calls to NPWInfoAddEntry between NPWInfoBegin and NPWInfoEnd, outside a page creation:

    #include "NPWInfo.h"
    NPWInfoBegin(&npw);
    NPWInfoAddEntry(&npw, kNPWInfoKeyTitle, "The Title");
    NPWInfoAddEntry(&npw, kNPWInfoKeyAuthor, "The Author");
    NPWInfoEnd(&npw);

Finally, to terminate the PDF and deallocate data structures allocated with previous calls, the NPWTerminate function is executed:

    NPWTerminate(&npw);
    fclose(fp);