Comprehensive Guide for Developers: Features, Integration, and API Reference
Represents a font in a PDF document. More...
#include <pdfsdk/cxx/font.h>
Public Member Functions | |
| Object | GetPdfObject () const |
| Get the PDF object associated with this Font object. | |
| PDEFontSubtype | GetSubtype () const |
| Get the subtype of the font. | |
| PDAtom | GetName () const |
| Get the name of the font. | |
| PDEFontMetrics | GetMetrics () const |
| Get the metrics of the font. | |
| Matrix | GetFontMatrix () const |
| Get the font transformation matrix. | |
| RectF | GetFontBBox () const |
| Get the font bounding box. | |
| bool | IsEmbedded () const |
| Check if the font has an embedded font program. | |
| PDEFontFileFormat | GetFontFileFormat () const |
| Get the format of the embedded font program. | |
| ReadStream | OpenFontFileStream () const |
| Open the embedded font program as a read stream. | |
| std::vector< Byte > | GetFontFileData () const |
| Get the embedded font program bytes. | |
| size_t | GetFontFileSize () const |
| Get the size, in bytes, of the decoded embedded font program. | |
| PDEWritingMode | GetWritingMode () const |
| Get the writing mode of the font. | |
| PDEType3GlyphInfo | GetType3GlyphInfo (uint8_t charcode) const |
| Content | GetType3CharProc (uint8_t charcode) const |
| Retrieves the glyph description for a character code. | |
| void | SetType3CharProc (uint8_t charcode, const PDEType3GlyphInfo &glyphInfo, const Content &content) |
| void | EnumCharOutline (const char *codepoint, size_t codepointLen, OutlineEnumMonitor &mon) const |
| Enumerate the outline of a character by specifying its character code and number of bytes used to represent it. | |
| void | EnumCharOutline (const std::string &codepoint, OutlineEnumMonitor &mon) const |
| Enumerate the outline of a character by specifying its character code. | |
| int16_t | GetCharWidth (const char *codepoint, size_t codepointLen) const |
| Get the width of the character represented by the specified character code and the number of bytes used to represent it. | |
| int16_t | GetCharWidth (const std::string &codepoint) const |
| Get the width of the character represented by the specified character code. | |
| bool | IsGlyphPresent (const char *codepoint, size_t codepointLen) const |
| bool | IsGlyphPresent (const std::string &codepoint) const |
| PDEGlyphVertMetric | GetCharVertMetric (const char *codepoint, size_t codepointLen) const |
| Get the vertical metrics of the character represented by the character code and the number of bytes used to represent it. | |
| PDEGlyphVertMetric | GetCharVertMetric (const std::string &codepoint) const |
| Get the vertical metrics of the character represented by the character code. | |
| PDFontStyle | GetStyle () const |
| Get the style of the font. | |
| PDFontInfo | GetFontInfo () const |
| Get the font info. | |
| PDECIDSystemInfo | GetCIDSystemInfo () const |
| PDAtom | GetEncodingName () const |
| Get the encoding name of the font. | |
| bool | CanTypeUnicode (const std::wstring &unicode) const |
| Check if the font can type the specified Unicode string. | |
| bool | IsFauxed () const |
| Check if the font is fauxed. | |
| PDFontInfo | GetFauxFontInfo () const |
| Get the substitute faux font info. | |
| std::optional< PDFontInfo > | FindSubstFontInfo (bool forceBold=false, bool forceItalic=false) const |
| Finds the system font that would be substituted for this font. | |
| bool | HasValidToUnicodeMap (PDEFontToUnicodeCheckFlags checkFlags=0) const |
| void | CreateToUnicodeMap (PDF::Document document, PDEFontToUnicodeCreateFlags createFlags=kPDEFontToUnicodeCreateDefault) |
| bool | HasValidWidths () const |
| void | CreateWidths (PDF::Document document) |
| bool | HasValidCIDSet () const |
| bool | HasRenderableGlyphs () const |
| void | CreateCIDSet (PDF::Document document) |
| bool | HasValidCharSet () const |
| void | CreateCharSet (PDF::Document document) |
| std::wstring | CharToUnicode (const char *codepoint, size_t codepointLen, bool useOnlyToUnicode=false) const |
| Convert the specified character code to its Unicode equivalent. | |
| std::wstring | CharToUnicode (const std::string &codepoint, bool useOnlyToUnicode=false) const |
| Convert the specified character code to its Unicode equivalent. | |
| std::string | UnicodeToChar (const UnicodeChar *unicode, size_t unicodeLen) const |
| Convert the specified Unicode value to its character code equivalent. | |
| std::string | UnicodeToChar (const std::wstring &unicode) const |
| Convert the specified Unicode value to its character code equivalent. | |
| RectF | GetType3GlyphsBBox () const |
| Get the bounding box of the Type 3 glyphs. | |
| Font (PDEFont handle, bool adopt=false) noexcept | |
| Font (const Font &rhs) noexcept | |
| Font & | operator= (const Font &rhs) noexcept |
| Font (Font &&rhs) noexcept | |
| Font & | operator= (Font &&rhs) noexcept |
Static Public Member Functions | |
| static Font | CreateFromPdfObject (const Object &object) |
| Creates a font from the specified PDF object. | |
Represents a font in a PDF document.
ISO 32000-2:2020 - 9.2 Organization and use of fonts
| bool PDF::Font::CanTypeUnicode | ( | const std::wstring & | unicode | ) | const |
Check if the font can type the specified Unicode string.
A Unicode string is a string whose character(s) are represented by the Unicode Standard character codes that range from U+0000 to U+10FFFF. This function checks if a font can map the character(s) to glyph(s). It is a font’s cmap table that maps character codes to glyphs i.e. glyph IDs.
| unicode | A reference to the Unicode string, in wide character string format. |
| std::wstring PDF::Font::CharToUnicode | ( | const char * | codepoint, |
| size_t | codepointLen, | ||
| bool | useOnlyToUnicode = false ) const |
Convert the specified character code to its Unicode equivalent.
| codepoint | The character code. |
| codepointLen | The number of bytes that represent the character code. |
| useOnlyToUnicode | If true, only the /ToUnicode map will be used for conversion. If false, the method will attempt to use other font information. |
| std::wstring PDF::Font::CharToUnicode | ( | const std::string & | codepoint, |
| bool | useOnlyToUnicode = false ) const |
Convert the specified character code to its Unicode equivalent.
| codepoint | A reference to the character code. |
| useOnlyToUnicode | If true, only the /ToUnicode map will be used for conversion. If false, the method will attempt to use other font information. |
| void PDF::Font::CreateCharSet | ( | PDF::Document | document | ) |
Creates a CharSet entry in the font's FontDescriptor dictionary.
For Type1 fonts, this creates a /CharSet string in the FontDescriptor dictionary listing all character names present in the embedded font program, as described in PDF Reference Table 5.18 and required by PDF/A-1 (ISO 19005-1:2005, Clause 6.3.5).
The CharSet string format is: /glyphname1/glyphname2/glyphname3...
Note: This operation is only applicable to Type1 fonts.
| document | The document where the font resides. |
| PDF::Exception | if CharSet generation failed for the font. |
| void PDF::Font::CreateCIDSet | ( | PDF::Document | document | ) |
Creates a /CIDSet stream identifying the set of CIDs present in the embedded CIDFont file and writes it into the CIDFont's FontDescriptor dictionary, as described in PDF Reference Table 5.20.
The created CIDSet may later be subsetted during document save to include only the CIDs used in the document.
|
static |
Creates a font from the specified PDF object.
| [in] | object | A reference to the PDF object to create the font from. |
| void PDF::Font::CreateToUnicodeMap | ( | PDF::Document | document, |
| PDEFontToUnicodeCreateFlags | createFlags = kPDEFontToUnicodeCreateDefault ) |
Creates a /ToUnicode entry whose value is a CMap stream object that maps character codes to Unicode values, and writes it into the font dictionary, as described in PDF Reference 5.9.
The generated map reflects the font's full encoding. During document save this map may be subsetted to include only the glyphs actually used.
| document | The document where the font resides. |
| createFlags | Flags controlling map generation; see PDEFontToUnicodeCreateFlagsBits. Pass kPDEFontToUnicodeCreateDefault (0) to generate the full map with no filtering. |
| PDF::Exception | with error code kPDErrInternalError if failed to create the ToUnicode map for the font. |
| void PDF::Font::CreateWidths | ( | PDF::Document | document | ) |
Creates glyph width entries in the font dictionary.
For simple fonts (Type1, TrueType), this creates a /Widths array and /FirstChar, /LastChar entries in the font dictionary, as described in PDF Reference 5.5.
For composite fonts (Type0), this creates a /W array in the descendant CIDFont dictionary, as described in PDF Reference 5.6.3.
The generated width information reflects the actual glyph metrics from the embedded or substitute font.
| document | The document where the font resides. |
| PDF::Exception | with error code kPDErrInternalError if widths generation failed for the font. |
| void PDF::Font::EnumCharOutline | ( | const char * | codepoint, |
| size_t | codepointLen, | ||
| OutlineEnumMonitor & | mon ) const |
Enumerate the outline of a character by specifying its character code and number of bytes used to represent it.
This function takes in a character code, along with the number of bytes that represent it, resolves it to a glyph and then iterates through the vector path instructions that define its shape.
| codepoint | The character code. |
| codepointLen | The number of bytes that represent the character code. |
| mon | The outline enumeration monitor. Theses are the vector path instructions that define the shape of the glyph. |
| void PDF::Font::EnumCharOutline | ( | const std::string & | codepoint, |
| OutlineEnumMonitor & | mon ) const |
Enumerate the outline of a character by specifying its character code.
This function takes in a character code, resolves it to a glyph and then iterates through the vector path instructions that define its shape.
| codepoint | The character code. |
| mon | The outline enumeration monitor. Theses are the vector path instructions that define the shape of the glyph. |
| std::optional< PDFontInfo > PDF::Font::FindSubstFontInfo | ( | bool | forceBold = false, |
| bool | forceItalic = false ) const |
Finds the system font that would be substituted for this font.
Reports what the substitution would be without changing the font, taking any registered substitution mappings into account.
| [in] | forceBold | Look for a bold face regardless of the font's own style. |
| [in] | forceItalic | Look for an italic face regardless of the font's own style. |
| PDEGlyphVertMetric PDF::Font::GetCharVertMetric | ( | const char * | codepoint, |
| size_t | codepointLen ) const |
Get the vertical metrics of the character represented by the character code and the number of bytes used to represent it.
See ISO 32000-2:2020 - 9.7.4.3 Glyph metrics in CIDFonts
| codepoint | The character code. |
| codepointLen | The number of bytes that represent the character code. |
| PDEGlyphVertMetric PDF::Font::GetCharVertMetric | ( | const std::string & | codepoint | ) | const |
Get the vertical metrics of the character represented by the character code.
See ISO 32000-2:2020 - 9.7.4.3 Glyph metrics in CIDFonts
| codepoint | A reference to the character code, in wide character string format. |
| int16_t PDF::Font::GetCharWidth | ( | const char * | codepoint, |
| size_t | codepointLen ) const |
Get the width of the character represented by the specified character code and the number of bytes used to represent it.
The units used to measure glyph width are 1/1000th of the text space unit. That is to say 1000 units of glyph space is equal to 1 unit of text space. This is the standard mapping defined in the font matrix of most fonts. The font matrix maps is an array of six umbers that maps glyph space to text space.
See ISO 32000-2:2020 - 9.2.4 Glyph positioning and metrics
| codepoint | The character code. |
| codepointLen | The number of bytes that represent the character code. |
| int16_t PDF::Font::GetCharWidth | ( | const std::string & | codepoint | ) | const |
Get the width of the character represented by the specified character code.
The units used to measure glyph width are 1/1000th of the text space unit. That is to say 1000 units of glyph space is equal to 1 unit of text space. This is the standard mapping defined in the font matrix of most fonts. The font matrix maps is an array of six umbers that maps glyph space to text space.
See ISO 32000-2:2020 - 9.2.4 Glyph positioning and metrics
| codepoint | A reference to the character code. |
| PDAtom PDF::Font::GetEncodingName | ( | ) | const |
Get the encoding name of the font.
A font can have a named encoding (one of StandardEncoding, WinAnsiEncoding or MacRomanEncoding) or a custom encoding defined in an encoding dictionary that modifies the BaseEncoding (a named encoding) and is described by the Differences array.
See ISO 32000-2:2020 - 9.6.5 Character encoding
| PDFontInfo PDF::Font::GetFauxFontInfo | ( | ) | const |
Get the substitute faux font info.
For a font to be fauxed means that it has been replaced by a substitute font. This is usually done in cases when the original font or font style is not readily available.
| RectF PDF::Font::GetFontBBox | ( | ) | const |
Get the font bounding box.
The font bounding box is the smallest rectangle that encloses all glyphs in a font, if all glyphs are to be placed with their origins coinciding. It is expressed as '/FontBBox' and is part of the font dictionary of Type 3 fonts. For all other font types the font bounding box is part of the FontDescriptor dictionary.
See ISO 32000-2:2020 - 9.6.4 Type 3 fonts, Table 110 — Entries in a Type 3 font dictionary, key 'FontBBox'.
| std::vector< Byte > PDF::Font::GetFontFileData | ( | ) | const |
Get the embedded font program bytes.
See ISO 32000-2:2020 - 9.9 Embedded font programs
| PDEFontFileFormat PDF::Font::GetFontFileFormat | ( | ) | const |
Get the format of the embedded font program.
See ISO 32000-2:2020 - 9.9 Embedded font programs, Table 124 Embedded font organisation for various font types
| size_t PDF::Font::GetFontFileSize | ( | ) | const |
Get the size, in bytes, of the decoded embedded font program.
See ISO 32000-2:2020 - 9.9 Embedded font programs
| PDFontInfo PDF::Font::GetFontInfo | ( | ) | const |
Get the font info.
| Matrix PDF::Font::GetFontMatrix | ( | ) | const |
Get the font transformation matrix.
A font matrix defines the transformation from glyph space to text space. It defines how glyph outlines are scaled and transformed from a font’s internal coordinate system into user space (the coordinate system of the page). It is a 2 × 3 matrix, written as an array of six numbers and for most fonts the it predefines the mapping of 1000 units of glyph space to 1 unit of text space.
See ISO 32000-2:2020 - 9.2.4 Glyph positioning and metrics.
| PDEFontMetrics PDF::Font::GetMetrics | ( | ) | const |
Get the metrics of the font.
When a font program is unavailable, a substitute font can be synthesized or a similar font can be chosen using font metrics. Font metrics are held within font descriptors. A font descriptor is a dictionary which specifies various font attributes.
See 9.8 ISO 32000-2:2020 - Font descriptors, Table 120 - Entries common to all font descriptors.
| PDAtom PDF::Font::GetName | ( | ) | const |
Get the name of the font.
| Object PDF::Font::GetPdfObject | ( | ) | const |
Get the PDF object associated with this Font object.
| PDFontStyle PDF::Font::GetStyle | ( | ) | const |
Get the style of the font.
| PDEFontSubtype PDF::Font::GetSubtype | ( | ) | const |
Get the subtype of the font.
This is the 'Subtype' entry of the font dictionary. There are 4 font types and 5 font subtypes because Type 1 has two subtypes - Type 1 and MMType 1. See ISO 32000-2:2020 - 9.5 Introduction to font data structures, Table 108 - Font types. For the CIDFont type, there are 2 subtypes - Type 0 and Type2
| Content PDF::Font::GetType3CharProc | ( | uint8_t | charcode | ) | const |
Retrieves the glyph description for a character code.
A font’s encoding is the association between character codes (obtained from text strings that are shown) and glyph descriptions. A glyph description is contained within a content stream object that specifies drawing instructions (lines, curves, fills, images, text, etc.) to render the shape of a single character.
See ISO 32000-2:2020 - 9.6.5 Character encoding
| codepoint | The character code, whose glyph description to retrieve. |
| PDEType3GlyphInfo PDF::Font::GetType3GlyphInfo | ( | uint8_t | charcode | ) | const |
Get the glyph info associated with the specified character.
| charcode | The character code. |
| RectF PDF::Font::GetType3GlyphsBBox | ( | ) | const |
Get the bounding box of the Type 3 glyphs.
A font bounding box, is the smallest rectangle that encloses all glyphs of a font, with their origins coinciding.
See ISO 32000-2:2020 - 9.6.4 Type 3 fonts, Table 110 — Entries in a Type 3 font dictionary, key 'FontBBox'
| PDEWritingMode PDF::Font::GetWritingMode | ( | ) | const |
Get the writing mode of the font.
The writing mode specifies the direction of the displacement vector for glyphs. It is one of either horizontal writing or vertical writing.
| bool PDF::Font::HasRenderableGlyphs | ( | ) | const |
Checks whether the font program contains at least one renderable glyph.
A glyph is considered renderable when it is not the .notdef glyph and has an actual outline. Fonts that contain only .notdef and/or contour-less glyphs (e.g. space) render nothing meaningful.
| bool PDF::Font::HasValidCharSet | ( | ) | const |
Validates the font's CharSet entry in the FontDescriptor for correctness and presence.
This method checks that:
Note: This validation is only applicable to Type1 fonts.
| bool PDF::Font::HasValidCIDSet | ( | ) | const |
Validates the font's CIDSet entry in the FontDescriptor for correctness and presence.
This method verifies that:
| bool PDF::Font::HasValidToUnicodeMap | ( | PDEFontToUnicodeCheckFlags | checkFlags = 0 | ) | const |
Validates the font's /ToUnicode map for correctness and compliance.
Always checks that the /ToUnicode map exists and is not empty. Additional checks are controlled by checkFlags:
| checkFlags | Combination of PDEFontToUnicodeCheckFlagsBits values. |
| bool PDF::Font::HasValidWidths | ( | ) | const |
Validates the font's glyph width information for correctness and presence.
This method checks that:
| bool PDF::Font::IsEmbedded | ( | ) | const |
Check if the font has an embedded font program.
A font program may be embedded in the document as a stream object referenced from the font descriptor - FontFile (Type 1), FontFile2 (TrueType) or FontFile3 (CFF / OpenType). When the font is not embedded a conforming reader substitutes a locally available font, so embedding trades file size for faithful reproduction.
When the font is embedded, the program can be inspected and extracted:
See ISO 32000-2:2020 - 9.9 Embedded font programs
| bool PDF::Font::IsFauxed | ( | ) | const |
Check if the font is fauxed.
For a font to be fauxed means that it has been replaced by a substitute font. This is usually done in cases when the original font or font style is not readily available.
| bool PDF::Font::IsGlyphPresent | ( | const char * | codepoint, |
| size_t | codepointLen ) const |
Check if the glyph for the specified codepoint is present in the font program.
A glyph is considered absent if:
| codepoint | The character code (as it appears in PDF content stream). |
| codepointLen | The length of the codepoint. |
| bool PDF::Font::IsGlyphPresent | ( | const std::string & | codepoint | ) | const |
Check if the glyph for the specified codepoint is present in the font program.
| codepoint | The character code (as it appears in PDF content stream). |
| ReadStream PDF::Font::OpenFontFileStream | ( | ) | const |
Open the embedded font program as a read stream.
See ISO 32000-2:2020 - 9.9 Embedded font programs
| void PDF::Font::SetType3CharProc | ( | uint8_t | charcode, |
| const PDEType3GlyphInfo & | glyphInfo, | ||
| const Content & | content ) |
Set the content and glyph info for the specified character code in a Type 3 font.
| charcode | The character code. |
| glyphInfo | The glyph info to set for the character. |
| content | The content to set for the character. |
| std::string PDF::Font::UnicodeToChar | ( | const std::wstring & | unicode | ) | const |
Convert the specified Unicode value to its character code equivalent.
| unicode | The Unicode value. |
| std::string PDF::Font::UnicodeToChar | ( | const UnicodeChar * | unicode, |
| size_t | unicodeLen ) const |
Convert the specified Unicode value to its character code equivalent.
| unicode | The Unicode value. |
| unicodeLen | The byte length of the Unicode value. |