We should distinguish between the following encoding types:

To show text correctly, the character encoding of text being shown must match the current font's built-in encoding. PDF allows changing the font's built-in encoding. This can be useful for several reasons like for instance in case of text which is encoded by a different encoding.

When a font is loaded by font_load() we can change the font built-in encoding by using the 'enc' option. Note, that we must ensure that the character set (or at least the subset we use in our document) defined by the new encoding is a subset of the character set which is present in the font.

JagPDF internally supports a subset of encodings listed here. For more details see font_load().

Refer to Language Specific Notes for details on how JagPDF handles strings passed from Python and Java.

Before we proceed, let's define a unicode variable which we will be using in the rest of this section. The human readable form of this string is žluťoučký kůň úpěl.

unicode_text = u'\u017elu\u0165ou\u010dk\u00fd k\u016f\u0148 \u00fap\u011bl'

The Type 1 font format supports only 8-bit encodings. However, JagPDF allows to use Unicode text with this type of font.

In the following example we will load the standard Helvetica font, change its built-in encoding to the ISO-8859-2 encoding and set it as the current font:

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

Now, we can show our ISO-8859-2 encoded text on the page:

text = unicode_text.encode('iso-8859-2')
canvas.text(50, 800, text)

Here is an example of using Unicode text with a standard font.

font = doc.font_load("standard; name=Helvetica; size=14; enc=utf-8")
canvas.text_font(font)
canvas.text(50, 780, unicode_text)

	Even though JagPDF allows to change the font built-in encoding to UTF-8, we are in practice limited to the Latin alphabet, because of the character set used by the standard fonts.

If no encoding is specified then a font built-in encoding is used. Character sets, built-in encodings and other details about the standard 14 fonts can be found here.

The TrueType and OpenType formats support various encodings. We can specify any encoding JagPDF internally supports.

In the following example we will load DejaVuSans.ttf (assuming that it resides in the current directory), specify the windows-1250 encoding and set it as the current font:

font = doc.font_load("file=DejaVuSans.ttf; size=14; enc=windows-1250")
canvas.text_font(font)

Now, we can show our windows-1250 encoded text on the page:

text = unicode_text.encode('windows-1250')
canvas.text(50, 800, text)

We can also specify the UTF-8 encoding:

font = doc.font_load("file=DejaVuSans.ttf; size=14; enc=utf-8")
canvas.text_font(font)
text = unicode_text.encode('utf8')
canvas.text(50, 780, text)

Python unicode objects are automatically converted to UTF-8 when passed to JagPDF's text showing functions so we can use unicode_text here as well:

canvas.text(50, 760, unicode_text)

If no encoding is specified then the windows-1252 encoding is used.

So far we have used only a simple method for showing text. We will generalize it by introducing a text object. The following line should be familiar to us:

canvas.text(50, 800, "text")

It is actually a shortcut for the following sequence:

canvas.text_start(50, 800)
canvas.text("text")
canvas.text_end()

Here, we have started a text object with text_start() and moved the origin of text space by (50, 800) Then we shown a text string and closed the text object with text_end().

A text object encloses a sequence of operations that show text, move the text position or adjust the text state. The text state is described in detail in section text state. Here we will mention two of its parameters which are defined only within a text object:

The text coordinates are interpreted in text space. The transformation from text space to user space is specified by the combination of the text matrix and several text state parameters. A text-showing operation shows the first glyph of a text string at the origin of the text space. Initially, the origin of text space corresponds to the origin of user space, just translated by values passed to text_start(). The text matrix is updated by both text-showing and text position moving operations. Text space is described in detail in the PDF Reference, chapter Text | Text Objects | Text Space Details

There are certain restrictions imposed on a text object. Text objects cannot be nested. The following table lists canvas operations that can appear in a text object:

So when should we use a text object? Because text operations inside a text object update the text matrix a text object is suitable for a sequence of text strings like for instance a paragraph of a text.

To illustrate, let's look at the following example

canvas.text_start(50, 800)
for n in ['1st', '2nd', '3rd']:
    canvas.text(n)
    canvas.text(' line')
    canvas.text_translate_line(0, -15)
canvas.text_end()

In this example we have shown three lines of text within a text object. We used text_translate_line() to move to the next line.

The following example is similar. It shows multi-line text, each text is shown in a different color.

canvas.text_start(50, 800)
for perc in range(10, 100, 10):
    canvas.color('f', perc/100.0)
    canvas.text('gray %d%%' % perc)
    canvas.text_translate_line(5, -15)
canvas.text_end()

See other examples of using a text object in the Font Information section.

An instance of class Font retrieved from font_load() provides, besides unique font identification, also information about the font. Let's show an example which explores font properties.

font = doc.font_load('standard; size=14; name=Helvetica')
family = font.family_name()
is_bold = font.is_bold()
is_italic = font.is_italic()
size = font.size()
baseline_distance = font.height()
ascender = font.ascender()
descender = font.descender()
bbox = (font.bbox_xmin(), font.bbox_ymin(), \
        font.bbox_xmax(), font.bbox_ymax())

In the next example we will illustrate font metrics visually. Let's define a function drawing metrics for a given glyph.

def show_glyph_metrics(x, y, font, char):
    advance = font.advance(char)
    # bounding box
    bbox_w = font.bbox_xmax() - font.bbox_xmin()
    bbox_h = font.bbox_ymax() - font.bbox_ymin()
    canvas.rectangle(x+font.bbox_xmin(), y+font.bbox_ymin(), bbox_w, bbox_h)
    # advance
    canvas.move_to(x, y)
    canvas.line_to(x + advance, y)
    # ascender & descender
    canvas.rectangle(x, y + font.descender(), \
                     advance, font.ascender() - font.descender())
    # show it
    canvas.path_paint('s')
    canvas.text(x, y, char)

Note that all numeric values retrieved from Font are in default user space units. Now we can load a font and show glyph metrics e.g. for 'g':

f = doc.font_load('standard; size=60; name=Helvetica')
canvas.text_font(f)
show_glyph_metrics(140, 740, f, 'g')

Font properties are useful when we want to perform more advanced text formatting. In the following example we will show how to use font properties to implement various line alignment styles. Let's start with defining required line width:

line_width = 558

Now we will load a font and retrieve width of a text string which is going to be aligned:

font = doc.font_load('standard; size=16; name=Times-Roman')
txt = "Everything should be made as simple as possible, but no simpler."
text_width = font.advance(txt)

So let's align our text to the left - there is nothing special about it:

canvas.text_start(20, 420)
canvas.text_font(font)
canvas.text(txt)
canvas.text_translate_line(0, font.height())

Now we will calculate padding which represents amount of whitespace that should be added to our text string to match line_width.

gap = line_width - text_width
padding = -1000.0 / font.size() * gap

We can align the string to the right by offsetting the first glyph by padding:

canvas.text(txt, [padding], [0])
canvas.text_translate_line(0, font.height())

Or we can align on the center:

canvas.text(txt, [padding / 2.0], [0])
canvas.text_translate_line(0, font.height())

Finally, a justified text string can be achieved by distributing padding evenly among spaces:

spaces = [i for i in range(len(txt)) if txt[i] == ' ']
num_spaces = len(spaces)
canvas.text(txt, num_spaces * [padding / num_spaces], spaces)
canvas.text_end()

In this example we will construct a very primitive text formatter capable of various paragraph alignment styles.

The first thing we need for achieving of our goal is to implement a line breaking function which for given paragraph and line width finds line breaks and calculates width of individual lines.

def line_breaking(font, para, width):
    lines = []
    space = font.advance(' ')
    line, curr_width = [], 0
    for word in para.split():
        adv = font.advance(word)
        if curr_width + space + adv > width:
            lines.append((' '.join(line), curr_width - space))
            line, curr_width = [], 0
        curr_width += space + adv
        line.append(word)
    if line:
        lines.append((' '.join(line), curr_width - space))
    return lines

Now we can implement a text formating function. We will find line breaks for each paragraph and align it according to alignment.

def format_text(x, y, canvas, font, text, width, alignment):
    canvas.text_font(font)
    canvas.text_start(x, y)
    for para in text.split('\n'):
        lines = line_breaking(font, para, width)
        for line, line_width in lines:
            gap = width - line_width
            padding = -1000.0 / font.size() * gap
            if alignment == 'left':
                canvas.text(line)
            elif alignment == 'right':
                canvas.text(line, [padding], [0])
            elif alignment == 'centered':
                canvas.text(line, [padding / 2.0], [0])
            elif alignment == 'justified':
                spaces = [i for i in range(len(line)) if line[i] == ' ']
                num_spaces = len(spaces)
                if not num_spaces or line == lines[-1][0]:
                    canvas.text(line)
                else:
                    canvas.text(line, num_spaces * [padding / num_spaces], spaces)
            canvas.text_translate_line(0, -font.height())
        canvas.text_translate_line(0, 1.5 * -font.height())
    canvas.text_end()

Now that we have our text formatter, we can try it out. long_text() is a function returning a multi-paragraph text string.

font = doc.font_load('standard; size=10; name=Helvetica')
format_text(20, 822, canvas, font, long_text(), 558, "justified")