JagPDF
Prev Up Home Next
C++
C
Python
Java

Some objects returned by JagPDF are reference counted. Such object is released when its reference count drops to zero. In some languages JagPDF clients do not need to care about reference counting as the language provides constructs that can handle this task automatically. However, for instance C JagPDF clients must maintain reference count manually.

C++

  • All symbols are in namespace jag::pdf.
  • All objects retrieved from JagPDF are just lightweight proxies that internally hold a reference to the actual object. So copying a JagPDF object is cheap.

C

  • All symbols are prefixed with jag_.
  • Reference counting of objects returned from JagPDF must be maintained manually:
    • Use jag_release(obj) to decrement object's reference count.
    • Use jag_addref(obj) to increment object's reference count.
    • Objects returned from JagPDF have already incremented reference count so there is no need to call jag_addref() on the retrieved object.
Overview
Strings
  • All symbols are defined in module jagpdf module.
  • JagPDF reference does not state argument types in Python signatures. You can always refer to the corresponding C++ signature - mapping to Python types should be obvious in most cases.
    • The only non-trivial mapping is from a <pointer to an array, length> C++ argument pair (as for instance here) - it is mapped to a Python sequence.

Text can be passed from Python to JagPDF using either str or unicode Python objects. A unicode object can be passed to JagPDF functions which expect a UTF-8 encoded string. A str object can be used e.g. for passing 8-bit encoded strings. Note that UTF-8 can be represented by str as well.

To illustrate, let's load a standard ISO-8859-2 encoded font.

helv = doc.font_load("standard; enc=iso-8859-2; name=Helvetica; size=24")
canvas.text_font(helv)

One of the languages representable by this encoding is Czech. Now that we have loaded the font, we can pass an ISO-8859-2 encoded string úplněk (full moon). There are two equivalent ways to do so: by encoding a unicode string to ISO-8859 or using a ISO-8859-2 encoded string literal.

full_moon_cze = u"\u00fapln\u011bk"
canvas.text(50, 800, full_moon_cze.encode('iso-8859-2'))
canvas.text(50, 760, "\xfapln\xeck")

JagPDF converts unicode objects to UTF-8 so the following will not be shown correctly because ISO-8859-2 encoded string is expected.

canvas.text(50, 720, full_moon_cze) # wrong

Python correctly raises UnicodeEncodeError when we attempt to encode Swedish fullmåne to ISO-8859-2 as å cannot be represented by this encoding. We must use ISO-8859-1 encoded font instead.

full_moon_swe = u"fullm\u00e5ne"
try:
    canvas.text(50, 680, full_moon_swe.encode('iso-8859-2'))
except UnicodeEncodeError, exc:
    print exc

Let's load a Unicode encoded TrueType font.

dejavu = doc.font_load("enc=utf-8; file=DejaVuSans.ttf; size=24");
canvas.text_font(dejavu);

Now we can mix Czech and Swedish. We can pass either a unicode object or a UTF-8 encoded str object.

canvas.text(50, 680, full_moon_cze)
canvas.text(50, 640, full_moon_swe)
canvas.text(50, 600, full_moon_swe.encode('utf-8'))

Note that in the following case 'full moon' is a UTF-8 encoded str object as all used characters are in the range 0x00-0x7f.

canvas.text(50, 560, "full moon") # ok

You can check the result here pdficon_small.

Overview
Strings
  • All symbols are defined in com.jagpdf namespace.
    • global functions: com.jagpdf.jagpdf.function_name
    • classes: com.jagpdf.ClassName
    • enumerations: com.jagpdf.ENUM_TYPE.ENUM_VALUE

Text is passed from Java to JagPDF via the Java String type. String internally uses UTF-16. That means that currently it is not possible to pass e.g. 8-bit encoded text (using byte[]) from Java to JagPDF, it is always UTF-16 encoded.

Whenever a Java String is passed to a JagPDF function which expects a UTF-8 encoded string, it is converted automatically from UTF-16 to UTF-8.

There is a group of text showing functions which expect an input string whose encoding corresponds to that of the current font. In such cases JagPDF automatically converts passed text so that it matches the encoding of the current font. The client must only ensure that the characters present in the passed string are representable by the font encoding and that they are present in the font.

An example should make it clear. Let's load a standard ISO-8859-2 encoded font.

Font helv = doc.font_load("standard; enc=iso-8859-2; name=Helvetica; size=24");
canvas.text_font(helv);

One of the languages representable by this encoding is Czech. We can pass a Unicode string úplněk (full moon). JagPDF converts the string to ISO-8859-2 and it is shown correctly.

String full_moon_cze = "\u00fapln\u011bk";
canvas.text(50, 800, full_moon_cze); // ok

If we pass Swedish fullmåne, letter å will not be shown because ISO-8859-2 does not represent such character. We should have used ISO-8859-1 encoded font instead.

String full_moon_swe = "fullm\u00e5ne";
canvas.text(50, 760, full_moon_swe); // wrong

Let's load a Unicode encoded TrueType font.

Font dejavu = doc.font_load("enc=utf-8; file=DejaVuSans.ttf; size=24");
canvas.text_font(dejavu);

Now we can mix Czech and Swedish and it will be shown correctly as JagPDF converts the strings to UTF-8.

canvas.text(50, 720, full_moon_swe);
canvas.text(50, 680, full_moon_cze);

You can check the result here pdficon_small.

Prev Up Home Next