PDF SDK Documentation

Comprehensive Guide for Developers: Features, Integration, and API Reference

Loading...
Searching...
No Matches

Represents a font in a PDF document. More...

#include <pdfsdk/cxx/font.h>

Inheritance diagram for PDF::Font:

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< PDFontInfoFindSubstFontInfo (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.

Detailed Description

Represents a font in a PDF document.

ISO 32000-2:2020 - 9.2 Organization and use of fonts

Member Function Documentation

◆ CanTypeUnicode()

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.

Parameters
unicodeA reference to the Unicode string, in wide character string format.
Returns
True if the font can type the Unicode string, false otherwise.

◆ CharToUnicode() [1/2]

std::wstring PDF::Font::CharToUnicode ( const char * codepoint,
size_t codepointLen,
bool useOnlyToUnicode = false ) const

Convert the specified character code to its Unicode equivalent.

Parameters
codepointThe character code.
codepointLenThe number of bytes that represent the character code.
useOnlyToUnicodeIf true, only the /ToUnicode map will be used for conversion. If false, the method will attempt to use other font information.
Returns
The Unicode value, in wide character string format.

◆ CharToUnicode() [2/2]

std::wstring PDF::Font::CharToUnicode ( const std::string & codepoint,
bool useOnlyToUnicode = false ) const

Convert the specified character code to its Unicode equivalent.

Parameters
codepointA reference to the character code.
useOnlyToUnicodeIf true, only the /ToUnicode map will be used for conversion. If false, the method will attempt to use other font information.
Returns
The Unicode value, in wide character string format.

◆ CreateCharSet()

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.

Parameters
documentThe document where the font resides.
Exceptions
PDF::Exceptionif CharSet generation failed for the font.

◆ CreateCIDSet()

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.

See also
kPDEFontCreateNeedSubset

◆ CreateFromPdfObject()

Font PDF::Font::CreateFromPdfObject ( const Object & object)
static

Creates a font from the specified PDF object.

Parameters
[in]objectA reference to the PDF object to create the font from.
Returns
The newly created font.

◆ CreateToUnicodeMap()

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.

See also
kPDEFontCreateNeedSubset
Parameters
documentThe document where the font resides.
createFlagsFlags controlling map generation; see PDEFontToUnicodeCreateFlagsBits. Pass kPDEFontToUnicodeCreateDefault (0) to generate the full map with no filtering.
Exceptions
PDF::Exceptionwith error code kPDErrInternalError if failed to create the ToUnicode map for the font.

◆ CreateWidths()

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.

Parameters
documentThe document where the font resides.
Exceptions
PDF::Exceptionwith error code kPDErrInternalError if widths generation failed for the font.

◆ EnumCharOutline() [1/2]

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.

Parameters
codepointThe character code.
codepointLenThe number of bytes that represent the character code.
monThe outline enumeration monitor. Theses are the vector path instructions that define the shape of the glyph.

◆ EnumCharOutline() [2/2]

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.

Parameters
codepointThe character code.
monThe outline enumeration monitor. Theses are the vector path instructions that define the shape of the glyph.

◆ FindSubstFontInfo()

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.

See also
AddFontNameSubstitution, AddCIDFontSubstitution
Parameters
[in]forceBoldLook for a bold face regardless of the font's own style.
[in]forceItalicLook for an italic face regardless of the font's own style.
Returns
The substitute's family, style and format, or std::nullopt when no system font matches.
See also
PDFontInfo

◆ GetCharVertMetric() [1/2]

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

Parameters
codepointThe character code.
codepointLenThe number of bytes that represent the character code.
Returns
The vertical metrics of the character.
See also
PDEGlyphVertMetric

◆ GetCharVertMetric() [2/2]

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

Parameters
codepointA reference to the character code, in wide character string format.
Returns
The vertical metrics of the character.
See also
PDEGlyphVertMetric

◆ GetCharWidth() [1/2]

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

Parameters
codepointThe character code.
codepointLenThe number of bytes that represent the character code.
Returns
The width of the character in typographic Em units.

◆ GetCharWidth() [2/2]

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

Parameters
codepointA reference to the character code.
Returns
The width of the character in typographic Em units.

◆ GetEncodingName()

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

Returns
The encoding name of the font.

◆ GetFauxFontInfo()

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.

Returns
The faux font info.
See also
PDFontInfo

◆ GetFontBBox()

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'.

Returns
The font bounding box.
See also
RectF

◆ GetFontFileData()

std::vector< Byte > PDF::Font::GetFontFileData ( ) const

Get the embedded font program bytes.

See ISO 32000-2:2020 - 9.9 Embedded font programs

Returns
The decoded embedded font program bytes, or an empty buffer if the font is not embedded (including Type 3 fonts).
See also
IsEmbedded, GetFontFileFormat, PDEFontFileFormat

◆ GetFontFileFormat()

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

Returns
The embedded font program format, or kPDEFontFileFormatNone if the font is not embedded.
See also
PDEFontFileFormat, IsEmbedded

◆ GetFontFileSize()

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

Returns
The size of the decoded embedded font program in bytes, or 0 if the font is not embedded (including Type 3 fonts).
See also
GetFontFileData

◆ GetFontInfo()

PDFontInfo PDF::Font::GetFontInfo ( ) const

Get the font info.

Returns
The font info.
See also
PDFontInfo

◆ GetFontMatrix()

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.

Returns
The font transformation matrix.
See also
Matrix

◆ GetMetrics()

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.

Returns
The metrics of the font.
See also
PDEFontMetrics

◆ GetName()

PDAtom PDF::Font::GetName ( ) const

Get the name of the font.

Returns
The name of the font.

◆ GetPdfObject()

Object PDF::Font::GetPdfObject ( ) const

Get the PDF object associated with this Font object.

Returns
The PDF object associated with the Font object.

◆ GetStyle()

PDFontStyle PDF::Font::GetStyle ( ) const

Get the style of the font.

Returns
The style of the font.
See also
PDFontStyle

◆ GetSubtype()

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

See also
PDECIDFontType
Returns
The subtype of the font.
See also
PDEFontSubtype

◆ GetType3CharProc()

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

Parameters
codepointThe character code, whose glyph description to retrieve.
Returns
The Content object containing the character code's glyph description.

◆ GetType3GlyphInfo()

PDEType3GlyphInfo PDF::Font::GetType3GlyphInfo ( uint8_t charcode) const

Get the glyph info associated with the specified character.

Parameters
charcodeThe character code.
Returns
The glyph info associated with the character.

◆ GetType3GlyphsBBox()

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'

Returns
The bounding box of the Type 3 glyphs.

◆ GetWritingMode()

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.

Returns
The writing mode of the font.
See also
PDEWritingMode

◆ HasRenderableGlyphs()

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.

Returns
true if at least one non-.notdef glyph has an outline, or the font has no inspectable glyph program (e.g. Type3); false if the font can render nothing.

◆ HasValidCharSet()

bool PDF::Font::HasValidCharSet ( ) const

Validates the font's CharSet entry in the FontDescriptor for correctness and presence.

This method checks that:

  • For Type1 fonts: /CharSet entry exists in the FontDescriptor dictionary

Note: This validation is only applicable to Type1 fonts.

Returns
true if valid CharSet information is present (or not applicable), false otherwise.

◆ HasValidCIDSet()

bool PDF::Font::HasValidCIDSet ( ) const

Validates the font's CIDSet entry in the FontDescriptor for correctness and presence.

This method verifies that:

  • /CIDSet stream exists in the FontDescriptor dictionary
  • The CIDSet correctly identifies which CIDs are present in the embedded font file
  • All CIDs referenced in the embedded font are included in the CIDSet
Returns
true if a valid CIDSet is present and correct, false if CIDSet is missing/invalid or not applicable (non-Type0 font, non-embedded font)

◆ HasValidToUnicodeMap()

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:

Parameters
checkFlagsCombination of PDEFontToUnicodeCheckFlagsBits values.
See also
PDEFontToUnicodeCheckFlagsBits
Returns
true if the map exists, is not empty, and passes all requested checks.

◆ HasValidWidths()

bool PDF::Font::HasValidWidths ( ) const

Validates the font's glyph width information for correctness and presence.

This method checks that:

  • For simple fonts (Type1, TrueType): /Widths array exists and is valid
  • For composite fonts (Type0): /W array exists in the descendant font and is valid
Returns
true if valid width information is present, false otherwise.

◆ IsEmbedded()

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

Returns
True if the font has an embedded font program, false otherwise.

◆ IsFauxed()

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.

Returns
True if the font is fauxed, false otherwise.

◆ IsGlyphPresent() [1/2]

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:

  • It maps to .notdef glyph (GID 0 for TrueType/CFF)
  • The glyph name doesn't exist in Type1 font program
  • The CID doesn't exist in CIDFont program
Parameters
codepointThe character code (as it appears in PDF content stream).
codepointLenThe length of the codepoint.
Returns
true if the glyph is present in the font program, false otherwise (including .notdef).

◆ IsGlyphPresent() [2/2]

bool PDF::Font::IsGlyphPresent ( const std::string & codepoint) const

Check if the glyph for the specified codepoint is present in the font program.

Parameters
codepointThe character code (as it appears in PDF content stream).
Returns
true if the glyph is present in the font program, false otherwise (including .notdef).

◆ OpenFontFileStream()

ReadStream PDF::Font::OpenFontFileStream ( ) const

Open the embedded font program as a read stream.

See ISO 32000-2:2020 - 9.9 Embedded font programs

Returns
A read stream over the decoded embedded font program.
See also
ReadStream, IsEmbedded, GetFontFileFormat, PDEFontFileFormat

◆ SetType3CharProc()

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.

Parameters
charcodeThe character code.
glyphInfoThe glyph info to set for the character.
contentThe content to set for the character.

◆ UnicodeToChar() [1/2]

std::string PDF::Font::UnicodeToChar ( const std::wstring & unicode) const

Convert the specified Unicode value to its character code equivalent.

Parameters
unicodeThe Unicode value.
Returns
The character code.

◆ UnicodeToChar() [2/2]

std::string PDF::Font::UnicodeToChar ( const UnicodeChar * unicode,
size_t unicodeLen ) const

Convert the specified Unicode value to its character code equivalent.

Parameters
unicodeThe Unicode value.
unicodeLenThe byte length of the Unicode value.
Returns
The character code.

The documentation for this class was generated from the following file: