10.3. Text

Text is the heart of a PDF file. As such,
there are many options for changing the appearance and layout of
text. In this section, we'll discuss the coordinate
system used in PDF documents, functions for inserting text and
changing text attributes, and font usage.

10.3.1. Coordinates

The origin
((0,0)) in a PDF document is in the bottom-left
corner. All of the measurements are specified in
DTP points. A DTP
point is equal to 1/72 of an inch, or 0.35277777778 mm.

Figure 10-3. Changing the origin

The pdf_translate(
) function moves the origin to the top
of the page, and pdf_scale(
) inverts the Y-axis coordinates. To
avoid producing text that can be read only in a mirror, we set the
horizscaling parameter.

10.3.2. Text Functions

PDF files have the concept of
the current text position.
It's like a cursor—unless you specify another
location, when you insert text it appears at the current text
location. You set the text location with the
pdf_set_textpos(
) function:

pdf_set_textpos(pdf, x, y);

Once you have positioned the cursor, use the pdf_show(
) function to draw text there:

pdf_show(pdf, text);

After you call pdf_show( ), the cursor moves to
the end of the inserted text.

You can also move the location and draw text in one function, with
pdf_show_xy( ):

pdf_show_xy(pdf, text, x, y);

The pdf_continue_text(
) function moves to the next line and
outputs text:

pdf_continue_text(pdf, text);

Set the leading parameter with
pdf_set_parameter( ) to change the vertical
separation between lines.

The pdf_show_boxed(
) function lets you define a rectangular
area within which a string of text is formatted:

The mode parameter controls the
alignment of the text within the box, and
can be "left", "right",
"center", "justify", or
"fulljustify". The difference between
"justify" and "fulljustify" is
in the treatment of the last line. The last line in a
"justify"-formatted area is not justified, whereas
in a "fulljustify" area it is. Example 10-4 shows all five cases.

Figure 10-4. Different text alignments

The pdf_show_boxed( ) function returns the number
of characters that did not fit in the box. If the
feature parameter is present, it must be
set to the string "blind". This prevents the text
from being drawn on the page and is useful for checking whether a
string will fit in the box without actually drawing it.

10.3.3. Text Attributes

There are three common ways to
alter the appearance of text. One is to
underline, overline, or strike out the
text using parameters. Another is to change the stroking and filling.
The third is to change the text's color.

Each of the underline,
overline, and strikeout
parameters may be set to "true" or
"false" independently of the others. For example:

pdf_set_parameter($pdf, "underline", "true"); // enable underlining

Stroking
text means drawing a line around the path defined by the text. The
effect is an outline of the text.
Filling
text means to fill the shape defined by the text. You can set whether
text should be stroked or filled with the
textrendering parameter. The valid values are
shown in Table 10-2.

Table 10-2. Values for the textrendering parameter

Value

Effect

0

Normal

1

Stroke (outline)

2

Fill and stroke

3

Invisible

4

Normal, add to clipping path

5

Fill and stroke, add to clipping path

6

Invisible, add to clipping path

You can select the text
color using the pdf_setcolor(
) function:

pdf_setcolor(pdf, type, colorspace, c1 [, c2, c3 [, c4]]);

The type parameter is either
"stroke", "fill", or
"both", indicating whether you're
specifying the color to be used for outlining the letters, filling
the letters, or both. The colorspace
parameter is one of "gray",
"rgb", "cmyk",
"spot", or "pattern". The
"gray", "spot", and
"pattern" colorspaces take only one color
parameter, whereas "rgb" takes three and
"cmyk" takes all four.

Figure 10-5. Lining, stroking, filling, and coloring text

10.3.4. Fonts

There are 14
built-in fonts in PDF, as listed in Table 10-3. If
you use only these fonts, the documents you create will be smaller
and more portable than if you use nonstandard fonts.

Table 10-3. Standard PDF fonts

Courier

Courier-Bold

Courier-BoldOblique

Courier-Oblique

Helvetica

Helvetica-Bold

Helvetica-BoldOblique

Helvetica-Oblique

Times-Bold

Times-BoldItalic

Times-Italic

Times-Roman

Symbol

ZapfDingbats

You can select a font with the pdf_findfont(
) function:

$font = pdf_findfont(pdf, fontname, encoding, embed);

The encoding parameter indicates how the
internal numeric codes for characters map onto the
font's characters. The built-in encodings are
"winansi" (Windows, a superset of ISO 8859-1,
which is itself a superset of ASCII), "macroman"
(Macintosh), "ebcdic" (IBM mainframe),
"builtin" (for symbol fonts), and
"host" ("macroman" on the Mac,
"ebcdic" on EBCDIC-based systems, and
"winansi" on everything else). When using built-in
fonts, stick to "host".

You can load nonstandard fonts if you have the
PostScript
font metrics or TrueType files. If you want to embed the nonstandard
fonts in the PDF file, rather than using whatever fonts on the
viewer's system most resemble them, set the
embed parameter to 1.
You do not need to embed the standard fonts.

Using nonstandard fonts without embedding them makes your documents
much less portable, while embedding them makes your generated PDF
files much larger. You also need to be careful of not violating any
font license terms, because some fonts are not supposed to be
embedded. TrueType font files have an indicator that is set if the
font should not be embedded. This is honored by
pdflib, which produces an error if you try
to embed such a font.

10.3.5. Embedding Fonts

To use nonstandard fonts, you must tell pdflib
where they are with the FontAFM,
FontPFM, or FontOutline
parameters. For example, to use a TrueType font, you can do this:

The double equals sign in this code tells pdflib
that you are specifying an absolute path. A single equals sign would
indicate a path relative to the default font directory.

Instead of using explicit pdf_set_parameter(
) calls each time you want to use a
nonstandard font, you can tell your pdflib
installation about these extra fonts by adding the
FontAFM,
FontPFM, and FontOutline
settings to pdflib's
pdflib.upr file.

Here's a sample set of additions to the
FontAFM and FontOutline
sections of the pdflib.upr file. The line that
starts with two slashes (//) indicates the default
directory for font files. The format for the other lines is simply
fontname=filename:

Example 10-6shows most of the built-in fonts
along with the five extra AFM (Adobe Font Metric) and two extra
TrueType fonts installed in the pdflib.upr file
above. It displays new Euro currency symbol along with a collection
of accented characters used in French.