Help language development. Donate to The Perl Foundation
Raku interface to the FontConfig native library
use FontConfig;
# optional: fontconfig uses the default system configuration, by default
INIT FontConfig.set-config-file: 'my-fonts.conf';
my FontConfig $patt .= parse: 'Arial,sans:style<italic>';
# -- OR --
$patt .= new: :family<Arial sans>, :style<italic>;
$patt.weight = 'bold';
say $patt.Str;
# Arial,sans:style=italic:weight=205
my FontConfig $match = $patt.match;
say $match.file;
say $match.format('%{file}');
# e.g. /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf
Bindings to the FontConfig library for system-wide font configuration and access.
At this stage, enough library bindings are implemented to enable FontConfig patterns to be parsed or built, and the best matching font to be located.
method new(*%atts --> FontConfig)
Create a new pattern for font matching purposes
method parse(Str $patt --> FontConfig)
Create a new pattern from a parsed FontConfig pattern.
$patt<weight> = 205;
$patt<weight> = 'bold';
say $patt<weight>;
$patt<weight>:delete;
This module provides am associative interface to FontConfig properties.
Numeric values in the pattern may be set to ranges:
$patt<weight> = 195..205;
Values may also hold a list, such as a list of font families:
$patt<family> = <Arial sans>;
method match(--> FontConfig)
This method performs FontConfig matching and returns the system font that best matches this pattern.
The matched object is populated with the actual font properties. The
file property contains the path to the font.
my $match = $pattern.match;
say 'matched font: ' ~ $match<fullname>;
say 'actual weight: ' ~ $match<weight>;
say 'font file: ' ~ $match<file>;
method constant(Str $name --> UInt)
Fontconfig has symbolic constants for numeric properties. For example, in the pattern: Ariel;weight=bold, bold,
evaluates to 200. The constant() method can be used to look-up these constants.
my \bold = FontConfig.constant("bold"); # 200
if $match<bold> >= bold {
say "matching font is bold";
}
Note that the Raku bindings resolve symbolic constants when a string is assigned to a numeric property. So:
$match<weight> = "extrabold";
Is equivalent to:
$match<weight> = FontConfig.constant("extrabold");
method query-ft-face(Pointer() $face, Str() :$file, UInt :$id --> FontConfig)
This method computes a FontConfig pattern based on the attributes of an existing FreeType font. It can be used to discover FontConfig attributes for a specific font.
The match() method will find the best font, reachable by FontConfig's configuration, that matches the original font, which may or may not be the original font.
The following example requires installation of the Font::FreeType module.
use FontConfig;
use Font::FreeType;
my $file = "t/fonts/Vera.ttf";
my Font::FreeType::Face $face = Font::FreeType.face($file);
my FontConfig $patt .= query-ft-face($face, :$file);
say $patt.fullname; # Bitstream Vera Sans
say $patt.file; # t/fonts/Vera.ttf
say $patt.weight; # 80
The Str method serializes a pattern to a string representation;
say $patt.Str; # Arial,sans:style=italic:weight=205
method version returns Version
This method returns the installed fontconfig library version. Please note that
the minimum supported version is v2.13.1.
The Raku FontConfig bindings provide automatic accessors for known properties
$patt.weight = 'bold';
say $patt.weight;
By default, fontconfig follows uses system-wide font configuration files, which may depend on your particular system.
There are several environment variables that can be set to define files and search paths, including: FONTCONFIG_FILE, FONTCONFIG_PATH, and FONTCONFIG_FILE.
This may need to be set, prior to running your programs, to provide a custom configuration file, or if FontConfig is giving an error "Cannot load default config file".
The FontConfig class has one method set-config-file($path) that can be called from the
current process to set FONTCONFIG_FILE. This acts globally and should be called once, before threading.