pdftron::PDF::Font Class Reference

A font that is used to draw text on a page. More...

#include <Font.h>

List of all members.

Public Types
enum	StandardType1Font {   e_times_roman = 0, e_times_bold, e_times_italic, e_times_bold_italic,   e_helvetica, e_helvetica_bold, e_helvetica_oblique, e_helvetica_bold_oblique,   e_courier, e_courier_bold, e_courier_oblique, e_courier_bold_oblique,   e_symbol, e_zapf_dingbats, e_null }
enum	Type {   e_Type1, e_TrueType, e_MMType1, e_Type3,   e_Type0, e_CIDType0, e_CIDType2 }
Public Member Functions
	Font (SDF::Obj font_dict=0)
	Create a PDF::Font object from an existing SDF font object that is embedded in the document.
	Font (const Font &c)
Font &	operator= (const Font &c)
Type	GetType ()
	Returns: Font Type
bool	IsSimple ()
	Returns: true for non-CID based fonts such as Type1, TrueType, and Type3
SDF::Obj	GetSDFObj ()
	Returns: a SDF/Cos object of this Font.
SDF::Obj	GetDescriptor ()
	Returns: a SDF/Cos object representing FontDescriptor or NULL is FontDescriptor is not present.
const char *	GetName ()
	Returns: the name of a font.
const char *	GetFamilyName ()
	Returns: the face's family name.
bool	IsFixedWidth ()
	Returns: true if all glyphs have the same width
bool	IsSerif ()
	Returns: true if glyphs have serifs
bool	IsSymbolic ()
	Returns: true if font contains characters outside the Adobe standard Latin character set.
bool	IsItalic ()
	Returns: true if glyphs have dominant vertical strokes that are slanted.
bool	IsAllCap ()
	Returns: true if font contains no lowercase letters
bool	IsForceBold ()
	Returns: true if bold glyphs should be painted with extra pixels at very small text sizes.
bool	IsHorizontalMode ()
	Returns: true if the font uses horizontal writing mode, false for vertical writing mode.
double	GetWidth (UInt char_code)
	Returns: advance width, measured in character space units for the glyph matching given character code.
double	GetMaxWidth ()
	Returns: the maximal advance width, in font units, for all glyphs in this face.
double	GetMissingWidth ()
	Returns: the default width to use for character codes whose widths are not specified in a font dictionary’s Widths array.
Common::Iterator< UInt >	GetCharCodeIterator ()
	GetCharCodeIterator represents an iterator interface used to traverse a list of char codes for which there is a glyph outline in the embedded font.
bool	GetGlyphPath (UInt char_code, std::vector< UChar > &out_oprs, std::vector< double > &out_data, bool conics2cubics, Common::Matrix2D *transform=0)
	The function retrieves the glyph outline for a given character code.
bool	MapToUnicode (UInt char_code, Unicode *out_uni_arr, const int in_uni_sz, int &out_chars)
	Maps the encoding specific 'charcode' to Unicode.
const char **	GetEncoding ()
	Returns: the font’s encoding array (the mapping of character codes to glyphs).
bool	IsEmbedded ()
	Tests whether or not the specified font is stored as a font file in a stream embedded in the PDF file.
const char *	GetEmbeddedFontName ()
	Returns: the PostScript font name for the embedded font.
SDF::Obj	GetEmbeddedFont ()
	Returns: the stream object of the embedded font or NULL if there if the font is not embedded.
int	GetEmbeddedFontBufSize ()
	Returns: the size of decoded buffer containing embedded font data or 0 if this information is not known in advance.
UShort	GetUnitsPerEm ()
	Returns: the number of font units per EM square for this face.
Rect	GetBBox ()
	Returns: A rectangle expressed in the glyph coordinate system, specifying the font bounding box.
double	GetAscent ()
	The face's ascender is the vertical distance from the baseline to the topmost point of any glyph in the face.
double	GetDescent ()
	The face's descender is the vertical distance from the baseline to the bottommost point of any glyph in the face.
int	GetStandardType1FontType ()
	Returns: Font::e_null if the font is not a standard Type1 font or some other StandardType1Font value for a standard Type1 font.
bool	IsCFF ()
	Returns: true if the embedded font is represented as CFF (Compact Font Format).
Common::Matrix2D	GetType3FontMatrix ()
	Returns: Type3 font matrix, mapping glyph space to text space A common practice is to define glyphs in terms of a 1000-unit glyph coordinate system, in which case the font matrix is [0.001 0 0 0.001 0 0].
SDF::Obj	GetType3GlyphStream (UInt char_code)
	Returns: a SDF/Cos glyph stream for the given char_code.
double	GetVerticalAdvance (UInt char_code, double &out_pos_vect_x, double &out_pos_vect_y)
	Returns: vertical advance.
Font	GetDescendant ()
	Returns: descendant CIDFont.
UInt	MapToCID (UInt char_code)
	Returns: a CID matching specified charcode.
int	MapToCID (const UChar *char_data, int char_data_avail, UInt &out_charcode, UInt &out_cid)
	The function maps charcode (out_charcode) from char_data buffer to a CID (out_cid) and return the number of bytes representing the CID in the buffer.
Static Public Member Functions
static Font	Create (SDF::SDFDoc &doc, StandardType1Font type)
	Create a PDF::Font object for the given standard (also known as base 14 font).
static Font	CreateTrueTypeFont (SDF::SDFDoc &doc, const UString &font_path, bool embed=true, bool subset=true)
	Embed an external TrueType font in the document as a Simple font.
static Font	CreateCIDTrueTypeFont (SDF::SDFDoc &doc, const UString &font_path, bool embed=true, bool subset=true, const char *encoding="Identity-H")
	Create a TrueType PDF font with the characteristics specified in the LOGFONT structure.
static Font	CreateType1Font (SDF::SDFDoc &doc, const UString &font_path, bool embed=true)
	Create a CID TrueType PDF font with the characteristics specified in the LOGFONT structure.
static Type	GetType (SDF::Obj font_dict)
	Returns: The type of a given SDF/Cos font dictionary

---

Detailed Description

A font that is used to draw text on a page.

It corresponds to a Font Resource in a PDF file. More than one page may reference the same Font object. A Font has a number of attributes, including an array of widths, the character encoding, and the font’s resource name.

PDF document can contain several different types of fonts and Font class represents a single, flat interface around all PDF font types.

There are two main classes of fonts in PDF: simple and composite fonts.

Simple fonts are Type1, TrueType, and Type3 fonts. All simple fonts have the following properties:

• Glyphs in the font are selected by single-byte character codes obtained from a string that is shown by the text-showing operators. Logically, these codes index into a table of 256 glyphs; the mapping from codes to glyphs is called the font’s encoding. Each font program has a built-in encoding. Under some circumstances, the encoding can be altered by means described in Section 5.5.5 "Character Encoding" in PDF Reference Manual.
  
  

• Each glyph has a single set of metrics. Therefore simple fonts support only horizontal writing mode.
  
  

A composite font is one whose glyphs are obtained from a font like object called a CIDFont (e.g. CIDType0Font and CIDType0Font). A composite font is represented by a font dictionary whose Subtype value is Type0. The Type 0 font is known as the root font, while its associated CIDFont is called its descendant. CID-keyed fonts provide a convenient and efficient method for defining multiple-byte character encodings and fonts with a large number of glyphs. These capabilities provide great flexibility for representing text in writing systems for languages with large character sets, such as Chinese, Japanese, and Korean (CJK).

---

Member Enumeration Documentation

enum pdftron::PDF::Font::StandardType1Font

Enumerator:

e_times_roman
e_times_bold
e_times_italic
e_times_bold_italic
e_helvetica
e_helvetica_bold
e_helvetica_oblique
e_helvetica_bold_oblique
e_courier
e_courier_bold
e_courier_oblique
e_courier_bold_oblique
e_symbol
e_zapf_dingbats
e_null

enum pdftron::PDF::Font::Type

Enumerator:

e_Type1
e_TrueType
e_MMType1
e_Type3
e_Type0
e_CIDType0
e_CIDType2

---

Constructor & Destructor Documentation

pdftron::PDF::Font::Font

(

SDF::Obj

font_dict = 0

)

Create a PDF::Font object from an existing SDF font object that is embedded in the document.

If font_dict is null, a non valid font is created.

pdftron::PDF::Font::Font

(

const Font &

c

)

---

Member Function Documentation

static Font pdftron::PDF::Font::Create	(	SDF::SDFDoc &	doc,
		StandardType1Font	type
	)			[static]

Create a PDF::Font object for the given standard (also known as base 14 font).

static Font pdftron::PDF::Font::CreateTrueTypeFont	(	SDF::SDFDoc &	doc,
		const UString &	font_path,
		bool	embed = true,
		bool	subset = true
	)			[static]

Embed an external TrueType font in the document as a Simple font.

Note:

glyphs in the Simple font are selected by single-byte character codes. If you want to work with multi-byte character codes (e.g. UTF16) you need to create a CID font.

Parameters:

	doc	Document in which the external font should be embedded.
	font_path	Path to the external font file.
	embed	A boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to 'true'.
	subset	A boolean indicating whether the embedded font should be subsetted.

static Font pdftron::PDF::Font::CreateCIDTrueTypeFont	(	SDF::SDFDoc &	doc,
		const UString &	font_path,
		bool	embed = true,
		bool	subset = true,
		const char *	encoding = "Identity-H"
	)			[static]

Create a TrueType PDF font with the characteristics specified in the LOGFONT structure.

Parameters:

	doc	Document in which the external font should be embedded.
	logfont	A pointer to a Windows LOGFONT structure that defines the characteristics of the logical font.
	embed	A boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to 'true'.
	subset	A boolean indicating whether the embedded font should be subsetted.

Note:

This method is available only on Windows platforms. Embed an external TrueType font in the document as a CID font. By default the function selects "Identity-H" encoding that maps 2-byte character codes ranging from 0 to 65,535 to the same Unicode value. Other predefined encodings are listed in Table 5.15 'Predefined CMap names' in PDF Reference Manual.

Parameters:

	doc	- document in which the external font should be embedded.
	font_path	- path to the external font file.
	embed	- a boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to 'true'.
	subset	- a boolean indicating whether the embedded font should be subsetted

static Font pdftron::PDF::Font::CreateType1Font	(	SDF::SDFDoc &	doc,
		const UString &	font_path,
		bool	embed = true
	)			[static]

Create a CID TrueType PDF font with the characteristics specified in the LOGFONT structure.

Parameters:

	doc	- document in which the external font should be embedded.
	logfont	A pointer to a Windows LOGFONT structure that defines the characteristics of the logical font.
	embed	- a boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to 'true'.
	subset	- a boolean indicating whether the embedded font should be subsetted

Note:

This method is available only on Windows platforms. Embed an external Type1 font in the document.

Parameters:

	doc	- document in which the external font should be embedded.
	font_path	- path to the external font file.
	embed	- a boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to 'true'.

Font& pdftron::PDF::Font::operator=

(

const Font &

c

)

Type pdftron::PDF::Font::GetType

(

)

Returns:

Font Type

bool pdftron::PDF::Font::IsSimple

(

)

Returns:

true for non-CID based fonts such as Type1, TrueType, and Type3

All simple fonts have the following properties:

• Glyphs in the font are selected by single-byte character codes obtained from a string that is shown by the text-showing operators. Logically, these codes index into a table of 256 glyphs; the mapping from codes to glyphs is called the font’s encoding. Each font program has a built-in encoding. Under some circumstances, the encoding can be altered by means described in Section 5.5.5 "Character Encoding" in PDF Reference Manual.
  
  

• Each glyph has a single set of metrics. Therefore simple fonts support only horizontal writing mode.
  
  

static Type pdftron::PDF::Font::GetType

(

SDF::Obj

font_dict

)

[static]

Returns:

The type of a given SDF/Cos font dictionary

SDF::Obj pdftron::PDF::Font::GetSDFObj

(

)

Returns:

a SDF/Cos object of this Font.

SDF::Obj pdftron::PDF::Font::GetDescriptor

(

)

Returns:

a SDF/Cos object representing FontDescriptor or NULL is FontDescriptor is not present.

const char* pdftron::PDF::Font::GetName

(

)

Returns:

the name of a font.

The behavior depends on the font type; for a Type 3 font it gets the value of the Name key in a PDF Font resource. For other types it gets the value of the BaseFont key in a PDF font resource.

const char* pdftron::PDF::Font::GetFamilyName

(

)

Returns:

the face's family name.

This is an ASCII string, usually in English, which describes the typeface's family (like 'Times New Roman', 'Bodoni', 'Garamond', etc). This is a least common denominator used to list fonts.

bool pdftron::PDF::Font::IsFixedWidth

(

)

Returns:

true if all glyphs have the same width

bool pdftron::PDF::Font::IsSerif

(

)

Returns:

true if glyphs have serifs

bool pdftron::PDF::Font::IsSymbolic

(

)

Returns:

true if font contains characters outside the Adobe standard Latin character set.

bool pdftron::PDF::Font::IsItalic

(

)

Returns:

true if glyphs have dominant vertical strokes that are slanted.

bool pdftron::PDF::Font::IsAllCap

(

)

Returns:

true if font contains no lowercase letters

bool pdftron::PDF::Font::IsForceBold

(

)

Returns:

true if bold glyphs should be painted with extra pixels at very small text sizes.

bool pdftron::PDF::Font::IsHorizontalMode

(

)

Returns:

true if the font uses horizontal writing mode, false for vertical writing mode.

double pdftron::PDF::Font::GetWidth

(

UInt

char_code

)

Returns:

advance width, measured in character space units for the glyph matching given character code.

The function gets the advance width of the font glyph. The advance width is the amount by which the current point advances when the glyph is drawn. The advance width may not correspond to the visible width of the glyph and for this reason, the advance width cannot be used to determine the glyphs’ bounding boxes.

double pdftron::PDF::Font::GetMaxWidth

(

)

Returns:

the maximal advance width, in font units, for all glyphs in this face.

double pdftron::PDF::Font::GetMissingWidth

(

)

Returns:

the default width to use for character codes whose widths are not specified in a font dictionary’s Widths array.

Common::Iterator<UInt> pdftron::PDF::Font::GetCharCodeIterator

(

)

GetCharCodeIterator represents an iterator interface used to traverse a list of char codes for which there is a glyph outline in the embedded font.

bool pdftron::PDF::Font::GetGlyphPath	(	UInt	char_code,
		std::vector< UChar > &	out_oprs,
		std::vector< double > &	out_data,
		bool	conics2cubics,
		Common::Matrix2D *	transform = 0
	)

The function retrieves the glyph outline for a given character code.

Returns:

false if the char_code was mapped to 'undefined character code'. In some fonts 'undefined character code' corresponds to a space, in some fonts it is a box, and in others it may be a more complicated glyph.

Parameters:

	char_code	character to query
	out_oprs	a vector of operators. The array is filled in by the method.
	out_data	a vector of data points that represent arguments for operators. The array is filled in by the method.
	conics2cubics	if set to true converts all quadratic Bezier curves to cubic Beziers, otherwise no conversion is performed.
	An	optional matrix used to transform glyph data coordinates. If null/unspecified, glyph data points will not be transformed.

Note:

the function can return only the following operators (Element::e_moveto, Element::e_lineto, Element::e_cubicto and optionally Element::e_conicto if conics2cubics parameter is set to true.

This function is not applicable to Type3 font and will throw an exception. Use GetType3GlyphStream instead.

bool pdftron::PDF::Font::MapToUnicode	(	UInt	char_code,
		Unicode *	out_uni_arr,
		const int	in_uni_sz,
		int &	out_chars
	)

Maps the encoding specific 'charcode' to Unicode.

Conversion of 'charcode' to Unicode can result in up to four Unicode characters.

Parameters:

	char_code	encoding specific 'charcode' that needs to be converted to Unicode.
	out_uni_arr	A pointer to an array of Unicode characters where the conversion result will be stored.
	in_uni_sz	The number of characters that can be written to out_uni_arr. You can assume that the function will never map to more than 10 characters.
	out_char_num	The function will modify this value to return the number of Unicode characters written in 'out_uni_arr' array.

Returns:

true if char_code was mapped to Unicode public area or false if the char_code was mapped to Unicode private area.

A char_code is mapped to Unicode private area when the information required for proper mapping is missing in PDF document (e.g. a predefined encoding or ToUnicode CMap).

Note:

This function is not applicable to CIDFonts (e_CIDType0 and e_CIDType2) and will throw an exception if called.

const char** pdftron::PDF::Font::GetEncoding

(

)

Returns:

the font’s encoding array (the mapping of character codes to glyphs).

The array contains 256 pointers. If a pointer is not NULL, it points to a C string containing the name of the glyph for the code point corresponding to the index. If it is NULL, then the name of the glyph is unchanged from that specified by the font's built-in encoding.

For a Type 3 font, all glyph names will be present in the encoding array, and NULL entries correspond to unencoded code points.

Note:

The Font object is the owner of the array.

This function is not applicable to composite fonts (e_type0, e_CIDType0, and e_CIDType2) and will throw an exception.

bool pdftron::PDF::Font::IsEmbedded

(

)

Tests whether or not the specified font is stored as a font file in a stream embedded in the PDF file.

Returns:

true if the font is embedded in the file, false otherwise.

const char* pdftron::PDF::Font::GetEmbeddedFontName

(

)

Returns:

the PostScript font name for the embedded font.

If the embedded font name is not available the function returns the empty string .

SDF::Obj pdftron::PDF::Font::GetEmbeddedFont

(

)

Returns:

the stream object of the embedded font or NULL if there if the font is not embedded.

Note:

This function is not applicable to Type3 font and will throw exception.

int pdftron::PDF::Font::GetEmbeddedFontBufSize

(

)

Returns:

the size of decoded buffer containing embedded font data or 0 if this information is not known in advance.

Note:

The size of decoded buffer may not be known in advance for all fonts and may not be correct.

This function is not applicable to Type3 font and will throw exception.

UShort pdftron::PDF::Font::GetUnitsPerEm

(

)

Returns:

the number of font units per EM square for this face.

This is typically 2048 for TrueType fonts, 1000 for Type1 fonts

Note:

Only relevant for scalable formats (such as TrueType and Type1).

This function is not applicable to Type3 font and will throw an exception. Use GetType3FontMatrix instead.

Rect pdftron::PDF::Font::GetBBox

(

)

Returns:

A rectangle expressed in the glyph coordinate system, specifying the font bounding box.

This is the smallest rectangle enclosing the shape that would result if all of the glyphs of the font were placed with their origins coincident and then filled.

double pdftron::PDF::Font::GetAscent

(

)

The face's ascender is the vertical distance from the baseline to the topmost point of any glyph in the face.

This field's value is a positive number, expressed in the glyph coordinate system. For all font types except Type 3, the units of glyph space are one-thousandth of a unit of text space. Some font designs use a value different from 'bbox.yMax'.

Note:

Only relevant for scalable formats.

double pdftron::PDF::Font::GetDescent

(

)

The face's descender is the vertical distance from the baseline to the bottommost point of any glyph in the face.

This field's value is a negative number expressed in the glyph coordinate system. For all font types except Type 3, the units of glyph space are one-thousandth of a unit of text space. Some font designs use a value different from 'bbox.yMin'.

Note:

Only relevant for scalable formats.

int pdftron::PDF::Font::GetStandardType1FontType

(

)

Returns:

Font::e_null if the font is not a standard Type1 font or some other StandardType1Font value for a standard Type1 font.

bool pdftron::PDF::Font::IsCFF

(

)

Returns:

true if the embedded font is represented as CFF (Compact Font Format).

Note:

Only Type1 and Type1C fonts can be represented in CFF format

Common::Matrix2D pdftron::PDF::Font::GetType3FontMatrix

(

)

Returns:

Type3 font matrix, mapping glyph space to text space A common practice is to define glyphs in terms of a 1000-unit glyph coordinate system, in which case the font matrix is [0.001 0 0 0.001 0 0].

Note:

Relevant only for a Type3 font.

SDF::Obj pdftron::PDF::Font::GetType3GlyphStream

(

UInt

char_code

)

Returns:

a SDF/Cos glyph stream for the given char_code.

If specified char_code is not found in CharPorcs dictionary the function returns NULL.

Note:

Relevant only for a Type3 font.

double pdftron::PDF::Font::GetVerticalAdvance	(	UInt	char_code,
		double &	out_pos_vect_x,
		double &	out_pos_vect_y
	)

Returns:

vertical advance.

vertical advance is a displacement vector for vertical writing mode (i.e. writing mode 1); its horizontal component is always 0.

Parameters:

	char_code	character to query for vertical advance
	out_pos_vect_x	- initialized by the method. horizontal component of the position vector defining the position of the vertical writing mode origin relative to horizontal writing mode origin.
	out_pos_vect_y	- initialized by the method. vertical component of the position vector defining the position of the vertical writing mode origin relative to horizontal writing mode origin.

Note:

Use this method only for composite fonts with vertical writing mode (i.e. if Font.IsHorizontalMode() returns false). The method will return 0 as vertical advance for simple fonts or for composite fonts with only horizontal writing mode.

Relevant only for a Type0 font.

Font pdftron::PDF::Font::GetDescendant

(

)

Returns:

descendant CIDFont.

Note:

Relevant only for a Type0 font.

UInt pdftron::PDF::Font::MapToCID

(

UInt

char_code

)

Returns:

a CID matching specified charcode.

Note:

Relevant only for a Type0 font.

int pdftron::PDF::Font::MapToCID	(	const UChar *	char_data,
		int	char_data_avail,
		UInt &	out_charcode,
		UInt &	out_cid
	)

The function maps charcode (out_charcode) from char_data buffer to a CID (out_cid) and return the number of bytes representing the CID in the buffer.

Parameters:

	char_data	the input data buffer containing one or more bytes of input charcode
	char_data_avail	the number of bytes in the char_data buffer
	out_charcode	the first charcode in char_data buffer.
	out_cid	CID corresponding to the out_charcode parsed from char_data buffer.

Returns:

the number of bytes consumed by out_cid. This number must be less than or equal to char_data_avail

Note:

Relevant only for a Type0 font.

---

© 2002-2008 PDFTron Systems Inc.