1PDF::Builder::FontManagUesre(r3)Contributed Perl DocumenPtDaFt:i:oBnuilder::FontManager(3)
2
6 PDF::Builder::FontManager - Managing the font library for PDF::Builder
7
9 These routines are called from the PDF::Builder class (see get_font(),
10 add_font() methods).
11 # core fonts come pre-loaded
13 # Add new a new font face and variants
14 my $rc = $pdf->add_font(
15 'face' => $unique_face_name, # font family, e.g., Times
16 'type' => 'core', # note that core fonts preloaded
17 'style' => 'serif', # also sans-serif, script (cursive),
18 # and symbol
19 'width' => 'proportional', # also constant
20 'settings' => { 'encode' => $encoding },
21 # note that these are actual core font names rather than file paths
22 'file' => { 'roman' => 'Times-Roman',
23 'italic' => 'Times-Italic',
24 'bold' => 'Times-Bold',
25 'bold-italic' => 'Times-BoldItalic' },
26 # for non-core these would be the actual file paths
27 # prefixed with font search paths
28 );
29 $rc = $pdf->add_font(
30 'face' => 'DejaVuSans', # Deja Vu sans serif family
31 'type' => 'ttf', # otf uses 'ttf'
32 'style' => 'sans-serif',
33 'width' => 'proportional',
34 'settings' => { 'encode' => 'utf8' },
35 # the defined font paths will be prepended to find the actual path
36 'file' => { 'roman' => 'DejaVuSans.ttf',
37 'italic' => 'DejaVuSans-Oblique.ttf',
38 'bold' => 'DejaVuSans-Bold.ttf',
39 'bold-italic' => 'DejaVuSans-BoldOblique.ttf' }
40 );
41 Some of the global data, which can be reset via the font_settings()
43 method:
44 * default-face: initialized to Times-Roman (core), used if you start
46 formatting text without explicitly setting a face
47 * default-serif: initialized to Times-Roman (core), used if you want
48 a "generic" serif typeface
49 * default-sansserif: initialized to Helvetica (core), used if you want
50 a "generic" sans-serif typeface
51 * default-constant: initialized to Courier (core), used if you want
52 a "generic" constant-width typeface
53 * default-script: NOT initialized (no default), used if you want
54 a "generic" script (cursive) typeface
55 * default-symbol initialized to Symbol (core), used if you want
56 a "generic" symbol typeface
57 * font-paths: C:/Windows/Fonts for Windows systems for TTF, other types
58 are in non-standard paths, and for non-Windows, anything goes
59 Usage of get_font() is to specify the face and variants, and then each
61 time, specify italic and bold to be on or off. If the desired file is
62 not yet opened, it will be, and the $font returned. If the font was
63 already created earlier, the saved $font will be returned.
64 my $font = $pdf->get_font(
66 'face' => 'Times',
67 'italic' => 0, # desire Roman (upright)
68 'bold' => 0, # desire medium weight
69 );
70 # if $font is undef, we have a problem...
71 $text->font($font, $font_size);
72 $text->... # use this font (medium weight Times-Roman core font)
73 $font = $pdf->get_font('italic' => 1);
74 $text->... # switched to italic
75 $font = $pdf->get_font('italic' => 0);
76 $text->... # back to Roman (upright) text
77
79 PDF::Builder::FontManager->new(%opts)
80 This is called from Builder.pm's new(). Currently there are no
81 options selectable. It will set up the font manager system and
82 preload it with the core fonts. Various defaults will be set for
83 the face (core Times-Roman), serif face (core Times-Roman), sans-
84 serif face (core Helvetica), constant width (fixed pitch) face
85 (core Courier), and a symbol font (core Symbol). There is no
86 default for a script (cursive) font unless you set one using the
87 font_settings() method.
88 @list = $pdf->font_settings() # Get
90 $pdf->font_settings(%info) # Set
91 Get or set some information about fonts, particularly the fonts to
92 be used for "generic" purposes.
93 "Get" returns a list (array) of the default font face name, the
95 default generic serif face, the default generic sans-serif face,
96 the default generic constant width face, the default generic symbol
97 face, and the default generic script (cursive) face. It is possible
98 for an element to be undefined (e.g., the generic script face is
99 "undef").
100 "Set" changes one or more default settings:
102 'font' => face to use for the default font face (initialized to Times)
104 'serif' => face to use for the generic serif face (initialized to Times)
105 'sans-serif' => face to use for the generic sans serif face
106 (initialized to Helvetica)
107 'constant' => face to use for the generic constant width face
108 (initialized to Courier)
109 'script' => face to use for the generic script face (uninitialized)
110 'symbol' => face to use for the generic symbol face
111 (initialized to Symbol)
112 $rc = $pdf->add_font_path("a directory path", %opts)
114 This method adds one search path to the list of paths to search. In
115 the get_font() method, each defined search path will be prepended
116 to the "file" entry (except for core fonts) in turn, until the font
117 file is found. However, if the "file" entry starts with / or ./ or
118 ../, it will be used alone. A "file" entry starting with .../ is a
119 special case, which is turned into ../ before the search path is
120 prepended. This permits you to give a search path that you expect
121 to move up one or more directories.
122 The font path search list always includes the current directory
124 (.), and is initialized in "Builder.pm" as @font_path. For the
125 Windows operating system, "/Windows/Fonts" usually contains a
126 number of TTF fonts that come standard with Windows, so it is added
127 by default. Anything else, including all Linux (and other non-
128 Windows operating systems), will have to be added depending on your
129 particular system. Some common places are:
130 Windows (NOTE: use / and not \\ in Windows paths!). Linux systems
132 may or may not handle spaces in directory names gracefully!
133 /Windows/Fonts
135 /WinNT/Fonts
136 /Program Files/MikTex 2.9/fonts/type1/urw/bookman (URW Bookman for MikTex)
137 /Program Files (x86)/MikTex 2.9/fonts/type1/urw/bookman (older versions)
138 /Program Files/Adobe/Acrobat DC/Resource/CIDFont (Adobe Reader fonts)
139 GhostScript may have its own directories
140 Note that directory names with spaces (e.g., "/Program Files") may
142 not play nice with some Linux systems, so they are not included by
143 default.
144 Linux, etc.
146 /usr/share/fonts (common base)
148 /usr/local/share/fonts (common base)
149 /usr/share/fonts/dejavu-sans-fonts (Deja Vu Sans TTF specifically)
150 /usr/share/fonts/truetype/ttf-dejavu
151 /usr/share/fonts/truetype/dejavu
152 /usr/lib/defoma/gs.d/devs/fonts (GhostScript?)
153 /usr/share/fonts/type1/gsfonts (GhostScript PS)
154 /usr/share/X11/fonts/urw-fonts (URW PS)
155 Third-party application installations, such as Adobe's Acrobat
157 Reader, may be a source of installed fonts, too.
158 A return code of 0 means the path was successfully added, while 1
160 means there was a problem encountered (and a message was issued).
161 No options are currently defined.
163 $rc = add_font(%info)
165 Add a new font entry (by face and variants) to the Font Manager's
166 list of known fonts.
167 %info items to be defined:
169 face => 'face name'
171 This should be a unique string to identify just one entry in
172 the Font Manager fonts table. I.e., you should not have two
173 "Times" (one a core font and the other a TTF font). Give them
174 different names (face names are case sensitive, so 'Times' is
175 different from 'times'). The "face" name is used to retrieve
176 the desired font.
177 type => 'type string'
179 This tells which Builder font routine to use to load the font.
180 The allowed entries are:
181 core
183 This is a core font, and is loaded via the CoreFont()
184 routine. Note that the core fonts are automatically pre-
185 loaded (including additional ones on Windows systems), so
186 you should not need to explicitly load any core fonts (at
187 least, the 14 basic ones). All PDF installation are
188 supposed to include these 14 basic core fonts, but the
189 precise actual file type may vary among installations, and
190 substitutions may be made (so long as the metrics match).
191 Currently, core fonts are limited to single byte encodings.
192 On Windows systems, there are an additional 14 core fonts
194 which are normally loaded. These are Georgia, Verdana,
195 Trebuchet, Wingdings, and Webdings faces. Use caution if
196 making use of these additional core fonts, as non-Windows
197 systems may not include them without explicit manual
198 installation of these fonts. These fonts may be safe to use
199 if you know that all your PDF readers will be running on
200 Windows systems.
201 ttf This is a TrueType (.ttf) or OpenType (.otf) font, loaded
203 with ttfont(). Currently this is the only type which can
204 be used with multibyte (e.g., utf8) encodings, as well as
205 with single byte encodings such as Latin-1. It is also the
206 only font type that can be used with HarfBuzz::Shaper. Many
207 systems include a number of TTF fonts, but unlike core
208 fonts, none are automatically loaded by the PDF::Builder
209 Font Manager, and must be explicitly loaded via add_font().
210 type1
212 This is a PostScript (Type1) font, loaded with psfont(),
213 which used to be quite commonly used, but is fairly rarely
214 used today, having mostly been supplanted by the more
215 capable TTF format. Some systems may include some Type1
216 fonts, but Windows, for example, does not normally come
217 with any. No Type1 fonts are automatically loaded by the
218 PDF::Builder Font Manager, and must be explicitly loaded
219 via add_font().
220 It is assumed that the font metrics file (.afm or .pfm) has
222 the same base file name as the glyph file (.pfa or .pfb),
223 is found in the same directory, and either can work with
224 either. If you have need for a different directory, a
225 different base name, or a specific metrics file to go with
226 a specific glyph file, let us know, so we can add such
227 functionality. Otherwise, you will need to directly use the
228 psfont() method in order to specify such different paths.
229 cjk This is an East Asian (Chinese-Japanese-Korean) type font,
231 loaded with the cjkfont() method. Note that CJK fonts have
232 never been well supported by PDF::Builder, and depend on
233 some fairly old (obsolete) features and external files
234 (.cmap and .data). We suggest that, rather than going
235 directly to CJK files, you first try directly using the
236 (usually) TTF files, in the TTF format. Few systems come
237 with CJK fonts installed. No CJK fonts are automatically
238 loaded by the PDF::Builder Font Manager, and must be
239 explicitly loaded via add_font().
240 bdf This is an Adobe Bitmap Distribution Format font, loaded
242 with the bdfont() method, a very old bitmapped format
243 dating back to the early days of the X11 system. Unlike the
244 filled smooth outlines used in most modern fonts, BDF's are
245 a coarse grid of on/off pixels. Please be kind to your
246 readers and use this format sparingly, such as only for
247 chapter titles or headings! Few systems come with BDF fonts
248 installed any more. No BDF fonts are automatically loaded
249 by the PDF::Builder Font Manager, and must be explicitly
250 loaded via add_font().
251 settings => { 'encode' => string, ... }
253 This is a collection of any other settings, flags, etc.
254 accepted by this particular font type. See the POD for
255 "corefont", "ttfont", etc. (per type for the allowable entries.
256 An important one will be the encoding, which you will need to
257 specify, if you use any characters beyond basic ASCII.
258 Currently, all fonts may use any single byte encoding you
260 desire (the default is CP-1252). Only TTF type fonts (which
261 includes OTF and CJK fonts) may currently specify a multibyte
262 encoding such as utf8. Needless to say, the text data that you
263 pass to text routines must conform to the given encoding. You
264 are not forced to use the same encoding for all defined fonts,
265 but if you wish to mix-and-match encodings, it is up to you to
266 define your text that uses the encoding specified for the
267 particular font used!
268 Note in particular when you use entities that (if numeric) they
270 are given in the Unicode number. When out of the single byte
271 range (x00-xFF), results are unpredictable if you give an
272 entity that does not fall within the encoding's range! Also
273 check results for Unicode points within the range x80-xFF if
274 you are using utf8 encoding.
275 style => 'styling'
277 This specifies the styling of the font: serif, sans-serif,
278 constant (constant width, or fixed pitch), script (cursive), or
279 symbol (non-alphabetic). It has no effect on how a font is
280 loaded or used, but may be useful to you for defining a generic
281 style font.
282 width => 'relative widths'
284 Currently, proportional (variable width) and constant (constant
285 width) may be specified. It has no effect on how a font is
286 loaded or used, but may be useful to you for defining a generic
287 style font.
288 file => {anonymous hash of source files}
290 This tells the Font Manager where to find the actual font file.
291 For core fonts, it is the standard name, rather than a file
292 (and remember, they are pre-loaded). For all other types, it
293 lists from one to four of the following variants:
294 roman => 'path to Roman'
296 This specifies the "Roman" or "regular" posture variant of
297 the font. Almost all available fonts include a Roman
298 (normal, upright posture) variant at normal (medium)
299 weight.
300 italic => 'path to Italic'
302 This specifies the "Italic", "slanted", or "oblique"
303 posture variant of the font. Most available fonts include
304 an italic variant at normal (medium) weight.
305 bold => 'path to Bold'
307 This specifies the "Bold" or "heavy" variant of the font.
308 Most available fonts include a bold (heavy weight) variant
309 with normal (Roman) posture.
310 bold-italic => 'path to BoldItalic'
312 This specifies the "Bold" and "Italic" variant of the font.
313 Many available fonts include a bold (heavy weight) variant
314 with italic posture.
315 symbol => 'path to Symbol'
317 For symbol type fonts (non-alphabetic), rather than risk
318 confusion by reusing the "roman" term, the "symbol" term is
319 used to specify what is usually the only variant of a
320 symbol font. It is possible that there are bold, italic,
321 and even bold-italic variants of a symbol file, but if so,
322 they are not currently supported.
323 You can give the entire path of the font's source file, in an
325 absolute path, if you wish. However, it's usually less typing
326 to use add_font_path() to specify a list of font directories to
327 search, and only give the name (and perhaps a subdirectory) for
328 the path here in add_font().
329 @current = $pdf->get_font() # Get
331 $font = $pdf->get_font(%info) # Set
332 If no parameters are given ("@current = $pdf->get_font()"), a list
333 (array) is returned giving the current font setting: face name,
334 italic flag 0/1, bold flag 0/1, type ('core', 'ttf', etc.), a hash
335 reference of settings, such as the encoding ('utf8', etc.), style
336 value, width value, and an array reference (list) of variants
337 (roman, bold, etc.). If no font has yet been explicitly set, the
338 current font will be the default font.
339 If at least one parameter is given (%info hash), the font manager
341 will attempt to discover the appropriate font (from within the font
342 list), load it if not already done, and return the $font value. If
343 undef is returned, there was an error.
344 %info fields:
346 face => face name string
348 This is the font family (face) name loaded up with the core
349 fonts (e.g., Times), or by "$pdf->add_font()" calls. In
350 addition, the current font face or the default face can be
351 requested, the serif generic serif face, the sans-serif generic
352 sans-serif face, the constant generic constant width face, or
353 the script generic script (cursive) face (if defined) may be
354 requested.
355 If you give the "face" entry, the other settings ("italic",
357 "bold", etc.) are not reset, unless it is impossible to use
358 the existing setting. If you do not give the "face" entry, the
359 current entry will be updated (bold, italic switched on/off,
360 etc.). You may always explicitly give current to make it clear
361 in your code that you don't want to change the face.
362 italic => flag
364 This requests use of the italic (slanted, oblique) variant of
365 the font, in either the current face ("face" not given in this
366 call) or the new face. The value is 0 or 1 for "off"
367 (Roman/upright posture) and "on" (italic posture).
368 bold => flag
370 This requests use of the bold (heavy weight) variant of the
371 font, in either the current face ("face" not given in this
372 call) or the new face. The value is 0 or 1 for "off" (medium
373 weight) and "on" (heavy weight).
374 $pdf->dump_font_tables()
376 Print (to STDOUT) all the Font Manager font information on hand.
377perl v5.36.0 2023-01-23 PDF::Builder::FontManager(3)