.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder::FontManager 3"
.TH PDF::Builder::FontManager 3 2023-12-21 "perl v5.38.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
PDF::Builder::FontManager \- Managing the font library for PDF::Builder
.SH SYNOPSIS
.IX Header "SYNOPSIS"
These routines are called from the PDF::Builder class (see \f(CWget_font(),
add_font()\fR methods).
.PP
.Vb 10
\&    # core fonts come pre\-loaded
\&    # Add new a new font face and variants
\&    my $rc = $pdf\->add_font(
\&        \*(Aqface\*(Aq => $unique_face_name,  # font family, e.g., Times
\&        \*(Aqtype\*(Aq => \*(Aqcore\*(Aq,             # note that core fonts preloaded
\&        \*(Aqstyle\*(Aq => \*(Aqserif\*(Aq,           # also sans\-serif, script (cursive),
\&                                      #  and symbol
\&        \*(Aqwidth\*(Aq => \*(Aqproportional\*(Aq,    # also constant
\&        \*(Aqsettings\*(Aq => { \*(Aqencode\*(Aq => $encoding },
\&        # note that these are actual core font names rather than file paths
\&        \*(Aqfile\*(Aq => { \*(Aqroman\*(Aq       => \*(AqTimes\-Roman\*(Aq,      
\&                    \*(Aqitalic\*(Aq      => \*(AqTimes\-Italic\*(Aq,
\&                    \*(Aqbold\*(Aq        => \*(AqTimes\-Bold\*(Aq,
\&                    \*(Aqbold\-italic\*(Aq => \*(AqTimes\-BoldItalic\*(Aq },
\&                # for non\-core these would be the actual file paths
\&                # prefixed with font search paths 
\&    );
\&    $rc = $pdf\->add_font(
\&        \*(Aqface\*(Aq => \*(AqDejaVuSans\*(Aq,       # Deja Vu  sans serif family
\&        \*(Aqtype\*(Aq => \*(Aqttf\*(Aq,              # otf uses \*(Aqttf\*(Aq
\&        \*(Aqstyle\*(Aq => \*(Aqsans\-serif\*(Aq,
\&        \*(Aqwidth\*(Aq => \*(Aqproportional\*(Aq,
\&        \*(Aqsettings\*(Aq => { \*(Aqencode\*(Aq => \*(Aqutf8\*(Aq },
\&        # the defined font paths will be prepended to find the actual path
\&        \*(Aqfile\*(Aq => { \*(Aqroman\*(Aq       => \*(AqDejaVuSans.ttf\*(Aq,
\&                    \*(Aqitalic\*(Aq      => \*(AqDejaVuSans\-Oblique.ttf\*(Aq,
\&                    \*(Aqbold\*(Aq        => \*(AqDejaVuSans\-Bold.ttf\*(Aq,
\&                    \*(Aqbold\-italic\*(Aq => \*(AqDejaVuSans\-BoldOblique.ttf\*(Aq }
\&    );
.Ve
.PP
Some of the global data, which can be reset via the \f(CWfont_settings()\fR method:
.PP
.Vb 10
\&    * default\-face:  initialized to Times\-Roman (core), used if you start
\&      formatting text without explicitly setting a face
\&    * default\-serif: initialized to Times\-Roman (core), used if you want
\&      a "generic" serif typeface
\&    * default\-sansserif: initialized to Helvetica (core), used if you want
\&      a "generic" sans\-serif typeface
\&    * default\-constant: initialized to Courier (core), used if you want
\&      a "generic" constant\-width typeface
\&    * default\-script: NOT initialized (no default), used if you want
\&      a "generic" script (cursive) typeface
\&    * default\-symbol initialized to Symbol (core), used if you want
\&      a "generic" symbol typeface
\&    * font\-paths: C:/Windows/Fonts for Windows systems for TTF, other types
\&      are in non\-standard paths, and for non\-Windows, anything goes
.Ve
.PP
Usage of \f(CWget_font()\fR is to specify the face and variants, and then each time,
specify \fIitalic\fR and \fIbold\fR to be on or off. If the desired file is not yet
opened, it will be, and the \f(CW$font\fR returned. If the font was already
created earlier, the saved \f(CW$font\fR will be returned.
.PP
.Vb 12
\&    my $font = $pdf\->get_font(
\&         \*(Aqface\*(Aq => \*(AqTimes\*(Aq,
\&         \*(Aqitalic\*(Aq => 0,     # desire Roman (upright)
\&         \*(Aqbold\*(Aq => 0,       # desire medium weight
\&    );
\&    # if $font is undef, we have a problem...
\&    $text\->font($font, $font_size);
\&    $text\->...  # use this font (medium weight Times\-Roman core font)
\&    $font = $pdf\->get_font(\*(Aqitalic\*(Aq => 1);
\&    $text\->...  # switched to italic
\&    $font = $pdf\->get_font(\*(Aqitalic\*(Aq => 0);
\&    $text\->...  # back to Roman (upright) text
.Ve
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    PDF::Builder::FontManager\->new(%opts)
.Ve
.Sp
.RS 4
This is called from Builder.pm's \f(CWnew()\fR. Currently there are no options
selectable. It will set up the font manager system and preload it with the
core fonts. Various defaults will be set for the face (core Times-Roman),
serif face (core Times-Roman), sans-serif face (core Helvetica), constant
width (fixed pitch) face (core Courier), and a symbol font (core Symbol).
There is no default for a script (cursive) font unless you set one using
the \f(CWfont_settings()\fR method.
.RE
.SS font_settings
.IX Subsection "font_settings"
.Vb 1
\&    @list = $pdf\->font_settings()  # Get
\&
\&    $pdf\->font_settings(%info)  # Set
.Ve
.Sp
.RS 4
Get or set some information about fonts, particularly the fonts to be used for
"generic" purposes.
.Sp
"Get" returns a list (array) of the default font face name, the default generic
serif face, the default generic sans-serif face, the default generic constant
width face, the default generic symbol face, and the default generic script
(cursive) face. It is possible for an element to be undefined (e.g., the
generic script face is \f(CW\*(C`undef\*(C'\fR).
.Sp
"Set" changes one or more default settings:
.Sp
.Vb 9
\&    \*(Aqfont\*(Aq => face to use for the default font face (initialized to Times)
\&    \*(Aqserif\*(Aq => face to use for the generic serif face (initialized to Times)
\&    \*(Aqsans\-serif\*(Aq => face to use for the generic sans serif face 
\&                    (initialized to Helvetica)
\&    \*(Aqconstant\*(Aq => face to use for the generic constant width face 
\&                  (initialized to Courier)
\&    \*(Aqscript\*(Aq => face to use for the generic script face (uninitialized)
\&    \*(Aqsymbol\*(Aq => face to use for the generic symbol face 
\&                (initialized to Symbol)
.Ve
.RE
.SS add_font_path
.IX Subsection "add_font_path"
.Vb 1
\&    $rc = $pdf\->add_font_path("a directory path", %opts)
.Ve
.Sp
.RS 4
This method adds one search path to the list of paths to search. In the
\&\f(CWget_font()\fR method, each defined search path will be prepended to the \f(CW\*(C`file\*(C'\fR 
entry (except for core fonts) in turn, until the font file is found. However, 
if the \f(CW\*(C`file\*(C'\fR entry starts with / or ./ or ../, it will be used alone.
A \f(CW\*(C`file\*(C'\fR entry starting with .../ is a special case, which is turned into ../
before the search path is prepended. This permits you to give a search path
that you expect to move up one or more directories.
.Sp
The font path search list always includes the current directory (.), and is
initialized in \f(CW\*(C`Builder.pm\*(C'\fR as \f(CW@font_path\fR. For the
Windows operating system, \f(CW\*(C`/Windows/Fonts\*(C'\fR usually contains a number of TTF
fonts that come standard with Windows, so it is added by default. Anything
else, including all Linux (and other non-Windows operating systems), will have
to be added depending on your particular system. Some common places are:
.Sp
Windows (\fBNOTE:\fR use / and not \e\e in Windows paths!). Linux systems may or
may not handle spaces in directory names gracefully!
.Sp
.Vb 6
\&    /Windows/Fonts
\&    /WinNT/Fonts
\&    /Program Files/MikTex 2.9/fonts/type1/urw/bookman (URW Bookman for MikTex)
\&    /Program Files (x86)/MikTex 2.9/fonts/type1/urw/bookman (older versions)
\&    /Program Files/Adobe/Acrobat DC/Resource/CIDFont (Adobe Reader fonts)
\&    GhostScript may have its own directories
.Ve
.Sp
Note that directory names with spaces (e.g., \f(CW\*(C`/Program Files\*(C'\fR) may not play
nice with some Linux systems, so they are not included by default.
.Sp
Linux, etc.
.Sp
.Vb 8
\&    /usr/share/fonts (common base)
\&    /usr/local/share/fonts (common base)
\&    /usr/share/fonts/dejavu\-sans\-fonts  (Deja Vu Sans TTF specifically)
\&    /usr/share/fonts/truetype/ttf\-dejavu
\&    /usr/share/fonts/truetype/dejavu
\&    /usr/lib/defoma/gs.d/devs/fonts   (GhostScript?)
\&    /usr/share/fonts/type1/gsfonts    (GhostScript PS)
\&    /usr/share/X11/fonts/urw\-fonts    (URW PS)
.Ve
.Sp
Third-party application installations, such as Adobe's Acrobat Reader, may be
a source of installed fonts, too.
.Sp
A return code of 0 means the path was successfully added, while 1 means there
was a problem encountered (and a message was issued).
.Sp
No options are currently defined.
.RE
.SS add_font
.IX Subsection "add_font"
.Vb 1
\&    $rc = add_font(%info)
.Ve
.Sp
.RS 4
Add a new font entry (by face and variants) to the Font Manager's list of
known fonts.
.Sp
\&\f(CW%info\fR items to be defined:
.IP "face => 'face name'" 4
.IX Item "face => 'face name'"
This should be a unique string to identify just one entry in the Font
Manager fonts table. I.e., you should not have two "Times" (one a core font
and the other a TTF font). Give them different names (face names are case 
\&\fIsensitive\fR, so 'Times' is different from 'times'). The \f(CW\*(C`face\*(C'\fR name is
used to retrieve the desired font.
.IP "type => 'type string'" 4
.IX Item "type => 'type string'"
This tells which Builder font routine to use to load the font. The allowed
entries are:
.RS 4
.IP \fBcore\fR 4
.IX Item "core"
This is a core font, and is loaded via the \f(CWCoreFont()\fR routine. Note that
the core fonts are automatically pre-loaded (including additional ones on
Windows systems), so you should not need to explicitly load any core fonts
(at least, the 14 basic ones). All PDF installation are supposed to include
these 14 basic core fonts, but the precise actual file type may vary among
installations, and substitutions may be made (so long as the metrics match).
Currently, core fonts are limited to single byte encodings.
.Sp
On Windows systems, there are an additional 14 core fonts which are normally
loaded. These are Georgia, Verdana, Trebuchet, Wingdings, and Webdings faces.
Use caution if making use of these additional core fonts, as non-Windows
systems may not include them without explicit manual installation of these
fonts. These fonts may be safe to use if you know that all your PDF readers
will be running on Windows systems.
.IP \fBttf\fR 4
.IX Item "ttf"
This is a TrueType (.ttf) or OpenType (.otf) font, loaded with \f(CWttfont()\fR. 
Currently this is the only
type which can be used with multibyte (e.g., \fIutf8\fR) encodings, as well as 
with single byte encodings such as \fILatin\-1\fR. It is also the only font type
that can be used with HarfBuzz::Shaper. Many systems include a number of TTF
fonts, but unlike core fonts, none are automatically loaded by the PDF::Builder
Font Manager, and must be explicitly loaded via \f(CWadd_font()\fR.
.IP \fBtype1\fR 4
.IX Item "type1"
This is a PostScript (Type1) font, loaded with \f(CWpsfont()\fR, which used to be 
quite commonly used, but is
fairly rarely used today, having mostly been supplanted by the more capable
TTF format. Some systems may include some Type1 fonts, but Windows, 
for example, does not normally come with any. No Type1 fonts are automatically
loaded by the PDF::Builder Font Manager, and must be explicitly loaded via
\&\f(CWadd_font()\fR.
.Sp
It is assumed that the font metrics file (.afm or .pfm) has the same base file
name as the glyph file (.pfa or .pfb), is found in the same directory, \fIand\fR
either can work with either.
If you have need for a different directory, a different base name, or a 
specific metrics file to go with a specific glyph file, let us know, so we can 
add such functionality. Otherwise, you will need to directly use the \f(CWpsfont()\fR
method in order to specify such different paths.
.IP \fBcjk\fR 4
.IX Item "cjk"
This is an East Asian (Chinese-Japanese-Korean) type font, loaded with the
\&\f(CWcjkfont()\fR method. Note that CJK fonts
have never been well supported by PDF::Builder, and depend on some fairly old
(obsolete) features and external files (.cmap and .data). We suggest that,
rather than going directly to CJK files, you first try directly using the
(usually) TTF files, in the TTF format. Few systems come with CJK fonts
installed. No CJK fonts are automatically loaded by the PDF::Builder Font 
Manager, and must be explicitly loaded via \f(CWadd_font()\fR.
.IP \fBbdf\fR 4
.IX Item "bdf"
This is an Adobe Bitmap Distribution Format font, loaded with the \f(CWbdfont()\fR
method, a very old bitmapped format 
dating back to the early days of the X11 system. Unlike the filled smooth 
outlines used in most modern fonts, BDF's are a coarse grid of on/off pixels.
Please be kind to your readers and use this format sparingly, such as only for
chapter titles or headings! Few systems come with BDF fonts installed any more. 
No BDF fonts are automatically loaded by the PDF::Builder Font Manager, and 
must be explicitly loaded via \f(CWadd_font()\fR.
.RE
.RS 4
.RE
.IP "settings => { 'encode' => string, ... }" 4
.IX Item "settings => { 'encode' => string, ... }"
This is a collection of any other settings, flags, etc. accepted by this
particular font type. See the POD for \f(CW\*(C`corefont\*(C'\fR, \f(CW\*(C`ttfont\*(C'\fR, etc. (per
\&\fItype\fR for the allowable entries. An important one will be the encoding,
which you will need to specify, if you use any characters beyond basic ASCII.
.Sp
Currently, all fonts may use any single byte encoding you
desire (the default is \fICP\-1252\fR). Only TTF type fonts (which includes OTF and 
CJK fonts) may currently specify a multibyte encoding such as \fIutf8\fR. Needless
to say, the text data that you pass to text routines must conform to the given
encoding. You are \fInot\fR forced to use the same encoding for all defined fonts,
but if you wish to mix-and-match encodings, it is up to you to define your
text that uses the encoding specified for the particular font used!
.Sp
Note in particular when you use \fIentities\fR that (if numeric) they are given 
in the Unicode number. When out of the single byte range (x00\-xFF), results are 
unpredictable if you give an entity that does not fall within the encoding's
range! Also check results for Unicode points within the range x80\-xFF if you
are using \fIutf8\fR encoding.
.IP "style => 'styling'" 4
.IX Item "style => 'styling'"
This specifies the styling of the font: \fBserif\fR, \fBsans-serif\fR, \fBconstant\fR 
(constant width, or fixed pitch), \fBscript\fR (cursive), or \fBsymbol\fR 
(non-alphabetic). It has no effect on how a font is loaded or used, but may 
be useful to you for defining a generic style font.
.IP "width => 'relative widths'" 4
.IX Item "width => 'relative widths'"
Currently, \fBproportional\fR (variable width) and \fBconstant\fR (constant width) 
may be specified. It has no effect on how a font is loaded or used, but may be 
useful to you for defining a generic style font.
.IP "file => {anonymous hash of source files}" 4
.IX Item "file => {anonymous hash of source files}"
This tells the Font Manager where to find the actual font file. For core fonts,
it is the standard name, rather than a file (and remember, they are pre-loaded).
For all other types, it lists from one to four of the following variants:
.RS 4
.IP "\fBroman\fR => 'path to Roman'" 4
.IX Item "roman => 'path to Roman'"
This specifies the "Roman" or "regular" posture variant of the font. Almost all 
available fonts include a Roman (normal, upright posture) variant at normal 
(medium) weight.
.IP "\fBitalic\fR => 'path to Italic'" 4
.IX Item "italic => 'path to Italic'"
This specifies the "Italic", "slanted", or "oblique" posture variant of the 
font. Most available fonts include an italic variant at normal (medium) weight.
.IP "\fBbold\fR => 'path to Bold'" 4
.IX Item "bold => 'path to Bold'"
This specifies the "Bold" or "heavy" variant of the font. Most available fonts 
include a bold (heavy weight) variant with normal (Roman) posture.
.IP "\fBbold-italic\fR => 'path to BoldItalic'" 4
.IX Item "bold-italic => 'path to BoldItalic'"
This specifies the "Bold" \fIand\fR "Italic" variant of the font. Many
available fonts include a bold (heavy weight) variant with italic posture.
.IP "\fBsymbol\fR => 'path to Symbol'" 4
.IX Item "symbol => 'path to Symbol'"
For symbol type fonts (non-alphabetic), rather than risk confusion by reusing
the "roman" term, the "symbol" term is used to specify what is usually the
only variant of a symbol font. It is possible that there are bold, italic, and
even bold-italic variants of a symbol file, but if so, they are not
currently supported.
.RE
.RS 4
.Sp
You \fIcan\fR give the entire path of the font's source file, in an absolute
path, if you wish. However, it's usually less typing to use \f(CWadd_font_path()\fR
to specify a list of font directories to search, and only give the name (and
perhaps a subdirectory) for the path here in \f(CWadd_font()\fR.
.RE
.RE
.RS 4
.RE
.SS get_font
.IX Subsection "get_font"
.Vb 1
\&    @current = $pdf\->get_font()  # Get
\&
\&    $font = $pdf\->get_font(%info)  # Set
.Ve
.Sp
.RS 4
If no parameters are given (\f(CW\*(C`@current = $pdf\->get_font()\*(C'\fR), a list
(array) is returned giving the \fIcurrent\fR font setting: \fIface\fR name, \fIitalic\fR 
flag 0/1, \fIbold\fR flag 0/1, \fItype\fR ('core', 'ttf', etc.), a hash reference of
\&\fIsettings\fR, such as the \fIencoding\fR ('utf8',
etc.), \fIstyle\fR value, \fIwidth\fR value, and an array reference (list) of 
variants (roman, bold, etc.). If no font has yet been explicitly set, the 
current font will be the default font.
.Sp
If at least one parameter is given (\f(CW%info\fR hash), the font manager will
attempt to discover the appropriate font (from within the font list), load it
if not already done, and return the \f(CW$font\fR value. If \fIundef\fR is returned,
there was an error.
.Sp
\&\f(CW%info\fR fields:
.IP "face => face name string" 4
.IX Item "face => face name string"
This is the font family (face) name loaded up with the core fonts (e.g., Times),
or by \f(CW\*(C`$pdf\->add_font()\*(C'\fR calls. In addition, the \fIcurrent\fR font face or
the \fIdefault\fR face can be 
requested, the \fIserif\fR generic serif face, the \fIsans-serif\fR generic sans-serif
face, the \fIconstant\fR generic constant width face, or the \fIscript\fR generic
script (cursive) face (\fBif defined\fR) may be requested.
.Sp
If you give the \f(CW\*(C`face\*(C'\fR entry, the other settings (\f(CW\*(C`italic\*(C'\fR, \f(CW\*(C`bold\*(C'\fR, etc.)
are \fInot\fR reset, unless it is impossible to use the existing setting.
If you do \fInot\fR give the \f(CW\*(C`face\*(C'\fR entry, the \fIcurrent\fR entry will be updated
(bold, italic switched on/off, etc.). You may always explicitly give 
\&\fIcurrent\fR to make it clear in your code that you \fIdon't\fR want to change 
the face.
.IP "italic => flag" 4
.IX Item "italic => flag"
This requests use of the italic (slanted, oblique) variant of the font, in
either the current face (\f(CW\*(C`face\*(C'\fR not given in this call) or the new face. The
value is 0 or 1 for "off" (Roman/upright posture) and "on" (italic posture).
.IP "bold => flag" 4
.IX Item "bold => flag"
This requests use of the bold (heavy weight) variant of the font, in
either the current face (\f(CW\*(C`face\*(C'\fR not given in this call) or the new face. The
value is 0 or 1 for "off" (medium weight) and "on" (heavy weight).
.RE
.RS 4
.RE
.SS dump_font_tables
.IX Subsection "dump_font_tables"
.Vb 1
\&    $pdf\->dump_font_tables()
.Ve
.Sp
.RS 4
Print (to STDOUT) all the Font Manager font information on hand.
.RE