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.

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.