NAME

PDF::Cairo::Font - wrapper that adds some useful methods to Cairo fonts

SYNOPSIS

Cairo supports three types of fonts: built-in, Font::FreeType, and Pango, which all have subtly different behaviors. This module hides that complexity while also adding compatibility methods for easily converting scripts from PDF::API2::Lite.

DESCRIPTION

Methods

new $pdf_cairo_ref, $font, [$index|$metrics]

The first argument must be a PDF::Cairo object, in order for Cairo to locate the surface/context, and to stash a reference to a Font::FreeType instance.

ascender $use_exact

Returns the ascender value for the font, assuming size of 1 point. If you supply a non-zero argument, this will be calculated by rendering sample characters in the font and determining exactly how far they extend above the baseline.

bbox

Returns the bounding box of the font (LLx, LLy, URx, URy), assuming size of 1 point.

capheight $use_exact

Returns the capheight value for the font, assuming size of 1 point. If you supply a non-zero argument, this will be calculated by rendering sample upper-case characters in the font and determining exactly how far they extend above the baseline.

descender $use_exact

Returns the descender value for the font, assuming size of 1 point. This is usually negative, reflecting its offset from the baseline. If you supply a non-zero argument, this will be calculated by rendering sample characters in the font and determining exactly how far they extend below the baseline.

xheight $use_exact

Returns the xheight value for the font, assuming size of 1 point. If you supply a non-zero argument, this will be calculated by rendering a lower-case "X" in the font and determining exactly how far it extends above the baseline.

PDF::API2 Compatibility

fontbbox

Alias for bbox().

width $text

Calculate width of text in this font at size of 1 point.

Utility Functions

append_font_path @paths

Add @paths to the end of the font search path.

get_font_path

Returns an array of directories that will be searched for fonts, and for AFM metrics files if you load a PFB font (case-insensitive).

set_font_path @paths

Set the font search path to @paths.

find_api2font $name

Uses Fontconfig to locate a decent match for the PDF::API2 builtin (non-embedded) fonts. The 'core' fonts are Times, Courier, Helvetica, Georgia, and Verdana, which Fontconfig is pretty good at finding matches for. The 'cjk' fonts are more problematic, and I recommend downloading the language-specific OTF files of Source Han from these links and loading them by filename instead:

https://github.com/adobe-fonts/source-han-sans/tree/release
https://github.com/adobe-fonts/source-han-serif/tree/release

Otherwise, the following Fontconfig searches will be used, with results that depend on how sane your fonts.conf is:

traditional|ming = "serif:lang=zh-tw"
simplified|song = "serif:lang=zh-cn"
korean|myungjo = "serif:lang=ko"
japanese|kozmin = "serif:lang=ja"
kozgo = "sans:lang=ja"

AUTHOR

J Greely, <jgreely at cpan.org>

SEE ALSO

PDF::API2, PDF::Builder, Cairo, Font::FreeType, Pango, Fontconfig