NAME

Text::Layout::FontConfig - Pango style font description for Text::Layout

SYNOPSIS

Font descriptors are strings that identify the characteristics of the desired font. For example, "Sans Italic 20".

The PDF context deals with physical fonts, e.g. built-in fonts like "Times-Bold" and fonts loaded from font files like "/usr/share/fonts/dejavu/DejaVuSans.ttf".

To map font descriptions to physical fonts, these fonts must be registered. This defines a font family, style, and weight for the font.

Note that Text::Layout::FontConfig is a singleton. Creating objects with new() will always return the same object.

METHODS

new( [ atts... ] ): For convenience only. Text::Layout::FontConfig is a singleton. Creating objects with new() will always return the same object.
Attributes:

corefonts: If true, a predefined set of font names (the PDF corefonts) is registered.

register_fonts( $font, $family, $style [ , $weight ] [ , $props ] )

Registers a font fmaily, style and weight for the given font.

$font can be the name of a built-in font, or the name of a TrueType or OpenType font file.

$family is a font family name such as "normal", "sans", "serif", or "monospace". It is possible to specify multiple family names, e.g., "times, serif".

$style is the slant style, one of "normal", "oblique", or "italic".

$weight is the font weight, like "normal", or "bold".

For convenience, style combinations like "bolditalic" are allowed.

A final hash reference can be passed to specify additional properties for this font. Recognized properties are:

"shaping" - If set to a true value, this font will require text shaping. This is required for fonts that deal with complex glyph rendering and ligature handling like Devanagari.
Text shaping requires module HarfBuzz::Shaper.
"ascender" - If set overrides the font ascender. This may be necessary to improve results for some fonts. The value is expressed in 1/1000th of an em.
"descender" - If set overrides the font descender. This may be necessary to improve results for some fonts. The value is expressed in 1/1000th of an em.
"underline_thickness", "underline_position" - Overrides the font specified or calculated values for underline thickness and/or position. This may improve results for some fonts.
"strikeline_thickness", "strikeline_position" - Overrides the font specified or calculated values for strikeline thickness and/or position. This may improve results for some fonts.
Note that strikeline thickness will default to underline thickness, if set.
"overline_thickness", "overline_position" - Overrides the font specified or calculated values for overline thickness and/or position.
This may improve results for some fonts.

Note that overline thickness will default to underline thickness, if set.

add_fontdirs( @dirs )

Adds one or more file paths to be searched for font files.

register_aliases( $family, $aliases, ... )

Adds aliases for existing font families.

Multiple aliases can be specified, e.g.

    $layout->register_aliases( "times", "serif, default" );

or

    $layout->register_aliases( "times", "serif", "default" );

register_corefonts( $noaliases )

This is a convenience method that registers all built-in corefonts.

Aliases for families "serif", "sans", and "monospace" are added unless $noaliases is specified.

You do not need to call this method if you provide your own font registrations.

find_font( $family, $style, $weight )

Returns a font descriptor based on the given family, style and weight.

On Linux, fallback using fontconfig.

from_string( $description )

Returns a font descriptor using a Pango-style font description, e.g. "Sans Italic 14".

On Linux, fallback using fontconfig.

parse( $description )

Parses a Pango-style font description and returns a hash ref with keys "family", "style", "weight", and "size".

Unspecified items are returned as empty strings or, in the case of "size", zero.

from_filename( $filename )

Returns a font descriptor from a filename. Tries to infer Pango data from the name.

AUTHOR

Johan Vromans, "<JV at CPAN dot org>"

SUPPORT

This module is part of <Text::Layout>.

Development takes place on GitHub: <https://github.com/sciurius/perl-Text-Layout>.

You can find documentation for this module with the perldoc command.

  perldoc Text::Layout::FontConfig

Please report any bugs or feature requests using the issue tracker for Text::Layout on GitHub.

LICENSE