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( %options )

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.

Options:

aliases

If true, register Serif, Sans and Mono as aliases for Times, Helvetica and Courier.

This is enabled by default and can be cancelled with noaliases.

noaliases

If true, do not register Serif, Sans and Mono as aliases for Times, Helvetica and Courier.

remap

Remap the core fonts to real TrueType or OpenType font files.

Supported values are GNU_Free_Fonts or free to use the GNU Free Fonts (http://ftp.gnu.org/gnu/freefont/) and tex or tex-gyre for the TeX Gyre fonts (https://www.gust.org.pl/projects/e-foundry/tex-gyre/).

remap($font)

remap( $src => $dst, ... )

Handles font remapping. The main purpose is to remap corefonts to real fonts.

With a single argument, returns the remapped value, or undef if none.

With a hash argument, maps each of the targets (keys) to a font file (value). This file must be present in one of the font directories.

Alternatively, the key may be one of Times, Helvetica and Courier and the value an already registered family.

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.