oracular (3) Text::Layout::FontConfig.3pm.gz

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.