plucky (3) PDF::Builder::FontManager.3pm.gz

Provided by: libpdf-builder-perl_3.026-1_all bug

NAME

       PDF::Builder::FontManager - Managing the font library for PDF::Builder

SYNOPSIS

       These routines are called from the PDF::Builder class (see "get_font(), add_font()" methods).

           # core fonts come pre-loaded
           # Add new a new font face and variants
           my $rc = $pdf->add_font(
               'face' => $unique_face_name,  # font family, e.g., Times
               'type' => 'core',             # note that core fonts preloaded
               'style' => 'serif',           # also sans-serif, script (cursive),
                                             #  and symbol
               'width' => 'proportional',    # also constant
               'settings' => { 'encode' => $encoding },
               # note that these are actual core font names rather than file paths
               'file' => { 'roman'       => 'Times-Roman',
                           'italic'      => 'Times-Italic',
                           'bold'        => 'Times-Bold',
                           'bold-italic' => 'Times-BoldItalic' },
                       # for non-core these would be the actual file paths
                       # prefixed with font search paths
           );
           $rc = $pdf->add_font(
               'face' => 'DejaVuSans',       # Deja Vu  sans serif family
               'type' => 'ttf',              # otf uses 'ttf'
               'style' => 'sans-serif',
               'width' => 'proportional',
               'settings' => { 'encode' => 'utf8' },
               # the defined font paths will be prepended to find the actual path
               'file' => { 'roman'       => 'DejaVuSans.ttf',
                           'italic'      => 'DejaVuSans-Oblique.ttf',
                           'bold'        => 'DejaVuSans-Bold.ttf',
                           'bold-italic' => 'DejaVuSans-BoldOblique.ttf' }
           );

       Some of the global data, which can be reset via the "font_settings()" method:

           * 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

       Usage of "get_font()" is to specify the face and variants, and then each time, specify italic and bold to
       be on or off. If the desired file is not yet opened, it will be, and the $font returned. If the font was
       already created earlier, the saved $font will be returned.

           my $font = $pdf->get_font(
                'face' => 'Times',
                'italic' => 0,     # desire Roman (upright)
                'bold' => 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('italic' => 1);
           $text->...  # switched to italic
           $font = $pdf->get_font('italic' => 0);
           $text->...  # back to Roman (upright) text

METHODS

   new
           PDF::Builder::FontManager->new(%opts)

           This is called from Builder.pm's "new()". 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 "font_settings()" method.

   font_settings
           @list = $pdf->font_settings()  # Get

           $pdf->font_settings(%info)  # Set

           Get or set some information about fonts, particularly the fonts to be used for "generic" purposes.

           "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 "undef").

           "Set" changes one or more default settings:

               'font' => face to use for the default font face (initialized to Times)
               'serif' => face to use for the generic serif face (initialized to Times)
               'sans-serif' => face to use for the generic sans serif face
                               (initialized to Helvetica)
               'constant' => face to use for the generic constant width face
                             (initialized to Courier)
               'script' => face to use for the generic script face (uninitialized)
               'symbol' => face to use for the generic symbol face
                           (initialized to Symbol)

   add_font_path
           $rc = $pdf->add_font_path("a directory path", %opts)

           This method adds one search path to the list of paths to search. In the "get_font()" method, each
           defined search path will be prepended to the "file" entry (except for core fonts) in turn, until the
           font file is found. However, if the "file" entry starts with / or ./ or ../, it will be used alone.
           A "file" 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.

           The font path search list always includes the current directory (.), and is initialized in
           "Builder.pm" as @font_path. For the Windows operating system, "/Windows/Fonts" 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:

           Windows (NOTE: use / and not \\ in Windows paths!). Linux systems may or may not handle spaces in
           directory names gracefully!

               /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

           Note that directory names with spaces (e.g., "/Program Files") may not play nice with some Linux
           systems, so they are not included by default.

           Linux, etc.

               /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)

           Third-party application installations, such as Adobe's Acrobat Reader, may be a source of installed
           fonts, too.

           A return code of 0 means the path was successfully added, while 1 means there was a problem
           encountered (and a message was issued).

           No options are currently defined.

   add_font
           $rc = add_font(%info)

           Add a new font entry (by face and variants) to the Font Manager's list of known fonts.

           %info items to be defined:

           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 sensitive, so 'Times' is different from 'times'). The "face" name is
               used to retrieve the desired font.

           type => 'type string'
               This tells which Builder font routine to use to load the font. The allowed entries are:

               core
                   This is a core font, and is loaded via the "CoreFont()" 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.

                   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.

               ttf This is a TrueType (.ttf) or OpenType (.otf) font, loaded with "ttfont()".  Currently this is
                   the only type which can be used with multibyte (e.g., utf8) encodings, as well as with single
                   byte encodings such as Latin-1. 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
                   "add_font()".

               type1
                   This is a PostScript (Type1) font, loaded with "psfont()", 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 "add_font()".

                   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, and 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 "psfont()" method in order to specify such different paths.

               cjk This is an East Asian (Chinese-Japanese-Korean) type font, loaded with the "cjkfont()"
                   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
                   "add_font()".

               bdf This is an Adobe Bitmap Distribution Format font, loaded with the "bdfont()" 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 "add_font()".

           settings => { 'encode' => string, ... }
               This is a collection of any other settings, flags, etc. accepted by this particular font type.
               See the POD for "corefont", "ttfont", etc. (per type 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.

               Currently, all fonts may use any single byte encoding you desire (the default is CP-1252). Only
               TTF type fonts (which includes OTF and CJK fonts) may currently specify a multibyte encoding such
               as utf8. Needless to say, the text data that you pass to text routines must conform to the given
               encoding. You are not 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!

               Note in particular when you use entities 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 utf8 encoding.

           style => 'styling'
               This specifies the styling of the font: serif, sans-serif, constant (constant width, or fixed
               pitch), script (cursive), or symbol (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.

           width => 'relative widths'
               Currently, proportional (variable width) and constant (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.

           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:

               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.

               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.

               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.

               bold-italic => 'path to BoldItalic'
                   This specifies the "Bold" and "Italic" variant of the font. Many available fonts include a
                   bold (heavy weight) variant with italic posture.

               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.

               You can 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 "add_font_path()" to specify a list of font directories
               to search, and only give the name (and perhaps a subdirectory) for the path here in "add_font()".

   get_font
           @current = $pdf->get_font()  # Get

           $font = $pdf->get_font(%info)  # Set

           If no parameters are given ("@current = $pdf->get_font()"), a list (array) is returned giving the
           current font setting: face name, italic flag 0/1, bold flag 0/1, type ('core', 'ttf', etc.), a hash
           reference of settings, such as the encoding ('utf8', etc.), style value, width 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.

           If at least one parameter is given (%info 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 $font
           value. If undef is returned, there was an error.

           %info fields:

           face => face name string
               This is the font family (face) name loaded up with the core fonts (e.g., Times), or by
               "$pdf->add_font()" calls. In addition, the current font face or the default face can be
               requested, the serif generic serif face, the sans-serif generic sans-serif face, the constant
               generic constant width face, or the script generic script (cursive) face (if defined) may be
               requested.

               If you give the "face" entry, the other settings ("italic", "bold", etc.)  are not reset, unless
               it is impossible to use the existing setting.  If you do not give the "face" entry, the current
               entry will be updated (bold, italic switched on/off, etc.). You may always explicitly give
               current to make it clear in your code that you don't want to change the face.

           italic => flag
               This requests use of the italic (slanted, oblique) variant of the font, in either the current
               face ("face" not given in this call) or the new face. The value is 0 or 1 for "off"
               (Roman/upright posture) and "on" (italic posture).

           bold => flag
               This requests use of the bold (heavy weight) variant of the font, in either the current face
               ("face" not given in this call) or the new face. The value is 0 or 1 for "off" (medium weight)
               and "on" (heavy weight).

   dump_font_tables
           $pdf->dump_font_tables()

           Print (to STDOUT) all the Font Manager font information on hand.