JagPDF
Prev Up Home Next

3.1.  Quick Start

In this section we will create a simple hello world PDF document. Let's first show the complete code for individual languages:

Python
import jagpdf

doc = jagpdf.create_file("hello.pdf")
doc.page_start(597.6, 848.68)
doc.page().canvas().text(50, 800, "Hello, world!")
doc.page_end()
doc.finalize()
C++
#include <jagpdf/api.h>
using namespace jag;

int main(int argc, char** const argv)
{
    pdf::Document doc(pdf::create_file("hello.pdf"));
    doc.page_start(597.6, 848.68);
    doc.page().canvas().text(50, 800, "Hello, world!");
    doc.page_end();
    doc.finalize();
    return 0;
}
Java
import com.jagpdf.jagpdf;
import com.jagpdf.Document;

public class helloworld {
    public static void main(String argv[]) {
        Document doc = jagpdf.create_file("hello.pdf");
        doc.page_start(597.6, 848.68);
        doc.page().canvas().text(50, 800, "Hello, world!");
        doc.page_end();
        doc.finalize_doc();
    }
}
C
#include <jagpdf/api.h>

int main(int argc, char** argv)
{
    jag_Document doc;
    jag_Page page;
    jag_Canvas canvas; 
    doc = jag_create_file("hello.pdf", 0);
    jag_Document_page_start(doc, 597.6, 848.68);
    page = jag_Document_page(doc);
    canvas = jag_Page_canvas(page);
    jag_Canvas_text_simple(canvas, 50, 800, "Hello, world!");
    jag_Document_page_end(doc);
    jag_Document_finalize(doc);
    jag_release(doc);
    return 0;
} 

All examples produce an identical PDF document. Let's take the Python script and explain step by step what is going on.

doc = jagpdf.create_file("hello.pdf")

In the first step, we created a PDF document object. It is associated with a file but we could bind it to a custom stream instead. We could also supply a document profile which affects things like PDF version, encryption, etc. Because we did not provide any profile a default one was used.

doc.page_start(597.6, 848.68)

In the next step we created an A4 page. Note how we actually specified the page dimensions. PDF uses a device independent coordinate system called user space (see section Coordinate Systems). The page size is expressed in default user space units which is 1/72 inch.

doc.page().canvas().text(50, 800, "Hello, world!")

The active page provides a Canvas. A canvas is an object which represents visible content of a page so we place text on the canvas. We did not specify a font so the text is showed using a default font. And again, we use user space units to define the text position. Refer to Text for more details about showing text.

doc.page_end()
doc.finalize()

Finally, we finished the page and the document. Now, there should be file pdficon_small hello.pdf in the current directory.

We intentionally omitted error handling in the examples. However, you should always check for errors in production code. You can find more details about language specific issues in the chapter Language Specific Notes.

[Note]

The JagPDF API is driver-like. Pages are inserted into a document sequentially and there can be at most one active page at a time. It is not possible to modify or otherwise access a page once it is finished by calling page_end().

You do not find functionality like random access to pages, editing [1] of page content, etc. in JagPDF. These things belong to another layer (often called document object model) which can use JagPDF as one of its possible visual presentations.

Note for C users

As you might have already noticed the C example is much more verbose than other examples. There are several reasons:

  • Firstly, JagPDF is aimed at C++ and Python and possibly at other object oriented programming languages in the future.
  • JagPDF is written in C++. The C API is generated automatically from C++ interfaces. The C API user friendliness certainly suffers from this fact.
  • The verbosity stems also from the fact that JagPDF internally reference counts some objects. In contrast to other languages, there is no construct in C that would hide it from users.

On the other hand, the C API provides the same feature set as APIs for other languages so the facts above should not discourage you from using JagPDF.

[1] Editing means here operations like deletion of previously inserted object, undo/redo, etc.

Prev Up Home Next