PDFlib 8 Windows COM/.NET Tutorial

5.4 Loading Fonts
5.4.1 Selecting an Encoding for Text Fonts
Fonts can be loaded explicitly with the load_font( ) function or implicitly by supplying
the fontname and encoding options to certain functions such as add/create_textflow( ) or
fill_textblock( ). Regardless of the method used for loading a font, a suitable encoding
must be specified. The encoding determines
> in which text formats PDFlib expects the supplied text;
> which glyphs in a font can be used;
> how text on the page and the glyph data in the font will be stored in the PDF output
document.
PDFlib’s text handling is based on the Unicode standard 1 , almost identical to ISO 10646.
Since most modern development environments support the Unicode standard our goal
is to make it as easy as possible to use Unicode strings for creating PDF output. However,
developers who don’t work with Unicode are not required to switch their application
to Unicode since legacy encodings can be used as well.
The choice of encoding depends on the font, the available text data, and some programming
aspects. In the remainder of this section we will provide an overview of the
different classes of encodings as an aid for selecting a suitable encoding.
Unicode encoding. With encoding=unicode you can pass Unicode strings to PDFlib. This
encoding is supported for all font formats. Depending on the language binding in use,
the Unicode string data type provided by the programming language (e.g. Java) can be
used, or byte arrays containing Unicode in one of the UTF-8, UTF-16, or UTF-32 formats
with little- or big-endian byte ordering (e.g. C).
With encoding=unicode all glyphs in a font can be addressed; complex script shaping
and OpenType layout features are supported. PDFlib checks whether the font contains a
glyph for a requested Unicode value. If no glyph is available, a substitute glyph can be
pulled from the same or another font (see Section 5.4.6, »Fallback Fonts«, page 139).
Some font types in PDF (Type 1, Type 3, and OpenType fonts based on glyph names)
support only single-byte text. However, PDFlib takes care of this situation to make sure
that more than 255 different characters can be used even for these font types.
The disadvantage of encoding=unicode is that text in traditional single- or multi-byte
encodings (except ISO 8859-1) cannot be used.
Single-byte encodings. 8-bit encodings (also called single-byte encodings) map each
byte in a text string to a single character, and are thus limited to 255 different characters
at a time (the value 0 is not available). This type of encoding is supported for all font formats.
PDFlib checks whether the font contains glyphs which match the selected encoding.
If a minimum number of usable glyphs is not reached, PDFlib will log a warning
message. If no usable glyph at all for the selected encoding is available in the font, font
loading will fail with the message font doesn’t support encoding. PDFlib checks whether
the font contains a glyph for a requested input value. If no glyph is available, a substitute
glyph can be pulled from the same or another font (see Section 5.4.6, »Fallback
Fonts«, page 139).
1. See www.unicode.org
5.4 Loading Fonts 127