Font¶
(New in v1.16.18) This class represents a font as defined in MuPDF (fz_font_s structure). It is required for the new class TextWriter and the new Page.writeText()
. Currently, it has no connection to how fonts are used in methods insertText
or insertTextbox``, respectively.
A Font object also contains useful general information, like the font bbox, the number of defined glyphs, glyph names or the bbox of a single glyph.
Class API
-
class
Font
¶ -
__init__(self, fontname=None, fontfile=None,
-
fontbuffer=None, script=0, language=None, ordering=-1, is_bold=0,
-
is_italic=0, is_serif=0)
Font constructor. The large number of parameters are used to locate font, which most closely resembles the requirements. Not all parameters are ever required – see the below pseudo code explaining the logic how the parameters are evaluated.
- Parameters
fontname (str) – one of the PDF Base 14 Fonts or CJK fontnames. Also possible are a select few of other names like (watch the correct spelling): “Arial”, “Times”, “Times Roman”.
filename (str) – the filename of a fontfile somewhere on your system 1.
fontbuffer (bytes,bytearray,io.BytesIO) – a fontfile loaded in memory 1.
script (in) – the number of a UCDN script. Currently supported in PyMuPDF are numbers 24, and 32 through 35.
language (str) – one of the values “zh-Hant” (traditional Chinese), “zh-Hans” (simplified Chinese), “ja” (Japanese) and “ko” (Korean). Otherwise, all ISO 639 codes from the subsets 1, 2, 3 and 5 are also possible, but are currently documentary only.
ordering (int) – an alternative selector for one of the CJK fonts.
is_bold (bool) – look for a bold font.
is_italic (bool) – look for an italic font.
is_serif (bool) – look for a serifed font.
- Returns
a MuPDF font if successful. This is the overall logic, how an appropriate font is located:
- if fontfile:
create font from it ignoring other arguments if not successful -> exception
- if fonbuffer:
create font from it ignoring other arguments if not successful -> exception
- if ordering >= 0:
load “universal” font ignoring other parameters # this will always be successful
- if fontname:
create a Base14 font, or resp. “universal” font, ignoring other parameters # note: values “Arial”, “Times”, “Times Roman” are also possible if not successful -> exception
Finally try to load a “NOTO” font using script and language parameters. if not successful:
look for fallback font
Note
With the usual abbreviations “helv”, “tiro”, etc., you will create fonts with the expected names “Helvetica”, “Times-Roman” and so on.
Using ordering >= 0, or fontnames starting with “china”, “japan” or “korea” will always create the same “universal” font “Droid Sans Fallback Regular”. This font supports all CJK and all Latin characters.
Actually, you would rarely ever need another font than “Droid Sans Fallback Regular”. Except that this font file is relatively large and adds about 1.65 MB (compressed) to your PDF file size. If you do not need CJK support, stick with specifying “helv”, “tiro” etc., and you will get away with about 35 KB compressed.
If you know you have a mixture of CJK and Latin text, consider just using
Font(ordering=0)
because this supports everything and also significantly (by a factor of two to three) speeds up execution: MuPDF will always find any character in this single font and need not check fallbacks.But if you do specify a Base-14 fontname, you will still be able to also write CJK characters! MuPDF automatically detects this situation and silently falls back to the universal font (which will then of course also be included in your PDF).
All fonts mentioned here also support Greek and Cyrillic letters.
Monospaced fonts are an issue: They are written with a too large width, e.g.
" a"
instead of"a"
. This applies to “cour” variants as well as most other mono fonts. The only exception we know of so far isconsola.ttf
. If you want to output monospaced text, we recommend using the Consolas font for the time being.
-
has_glyph
(chr, language=None, script=0)¶ Check whether the unicode chr exists in the font or some fallback. May be used to check whether any “TOFU” symbols will appear on output.
- Parameters
chr (int) – the unicode of the character (i.e. ord()).
language (str) – the language – currently unused.
script (int) – the UCDN script number.
- Returns
True or False.
-
glyph_advance
(chr, language=None, script=0, wmode=0)¶ Calculate the “width” of the character’s glyph (visual representation).
- Parameters
chr (int) – the unicode number of the character. Use
ord(c)
, not the character itself. Again, this should normally work even if a character is not supported by that font, because fallback fonts will be checked where necessary.
The other parameters are not in use currently. This especially means that only horizontal text writing is supported.
- Returns
a float representing the glyph’s width relative to fontsize 1.
-
glyph_name_to_unicode
(name)¶ Return the unicode for a given glyph name. Use it in conjunction with
chr()
if you want to output e.g. a certain symbol.- Parameters
name (str) – The name of the glyph.
- Returns
The unicode integer, or 65533 = 0xFFFD if the name is unknown. Examples:
font.glyph_name_to_unicode("Sigma") = 931
,font.glyph_name_to_unicode("sigma") = 963
. Refer to e.g. this publication for a list of glyph names and their unicode numbers.
-
unicode_to_glyph_name
(chr, language=None, script=0, wmode=0)¶ Show the name of the character’s glyph.
- Parameters
chr (int) – the unicode number of the character. Use
ord(c)
, not the character itself.- Returns
a string representing the glyph’s name. E.g.
font.glyph_name(ord("#")) = "numbersign"
. Depending on how this font was built, the string may be empty, “.notfound” or some generated name.
-
text_length
(text, fontsize=11)¶ Calculate the length of a unicode string.
- Parameters
text (str) – a text string – UTF-8 encoded. For Python 2, you must use unicode here.
fontsize (float) – the fontsize.
- Returns
a float representing the length of the string when stored in the PDF. Internally
glyph_advance()
is used on a by-character level. If the font does not have a character, it will automatically be looked up in a fallback font.
-
flags
¶ A dictionary with various font properties, each represented as bools.
-
name
¶ Name of the font. May be “” or “(null)”.
-
glyph_count
¶ The number of glyphs defined in the font.
-
Footnotes