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.

• interline - If set to a true value, an alternative way to determine glyph height is used. This may improve results for some fonts.

• 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.

SEE ALSO

Text::Layout, Text::Layout::FontDescriptor.

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

See Text::Layout, Text::Layout::FontDescriptor, HarfBuzz::Shaper.