All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
pdftron::PDF::Font Class Reference

#include <Font.h>

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  Encoding { e_IdentityH =0, e_Indices }
 
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)
 
 Font (const Font &c)
 
Fontoperator= (const Font &c)
 
Type GetType ()
 
bool IsSimple ()
 
SDF::Obj GetSDFObj ()
 
SDF::Obj GetDescriptor ()
 
const char * GetName ()
 
const char * GetFamilyName ()
 
bool IsFixedWidth ()
 
bool IsSerif ()
 
bool IsSymbolic ()
 
bool IsItalic ()
 
bool IsAllCap ()
 
bool IsForceBold ()
 
bool IsHorizontalMode ()
 
double GetWidth (UInt32 char_code) const
 
double GetMaxWidth ()
 
double GetMissingWidth ()
 
Common::Iterator< UInt32GetCharCodeIterator ()
 
PathData GetGlyphPath (UInt32 char_code, bool conics2cubics, Common::Matrix2D *transform=0)
 
ShapedText GetShapedText (const UString &text_to_shape)
 
UString MapToUnicode (UInt32 char_code)
 
bool MapToUnicode (UInt32 char_code, Unicode *out_uni_arr, const int in_uni_sz, int &out_chars)
 
const char ** GetEncoding ()
 
bool IsEmbedded ()
 
const char * GetEmbeddedFontName ()
 
SDF::Obj GetEmbeddedFont ()
 
int GetEmbeddedFontBufSize ()
 
UInt16 GetUnitsPerEm ()
 
Rect GetBBox ()
 
double GetAscent ()
 
double GetDescent ()
 
int GetStandardType1FontType ()
 
bool IsCFF ()
 
Common::Matrix2D GetType3FontMatrix ()
 
SDF::Obj GetType3GlyphStream (UInt32 char_code)
 
double GetVerticalAdvance (UInt32 char_code, double &out_pos_vect_x, double &out_pos_vect_y)
 
std::vector< double > GetVerticalAdvance (UInt32 char_code)
 
Font GetDescendant ()
 
UInt32 MapToCID (UInt32 char_code) const
 
int MapToCID (const UChar *char_data, int char_data_avail, UInt32 &out_charcode, UInt32 &out_cid) const
 
void Destroy ()
 

Static Public Member Functions

static Font Create (SDF::SDFDoc &doc, StandardType1Font type, bool embed=false)
 
static Font CreateTrueTypeFont (SDF::SDFDoc &doc, const UString &font_path, bool embed=true, bool subset=true)
 
static Font CreateCIDTrueTypeFont (SDF::SDFDoc &doc, const UString &font_path, bool embed=true, bool subset=true, Encoding encoding=e_IdentityH, UInt32 ttc_font_index=0)
 
static Font Create (SDF::SDFDoc &doc, Font &from, const UString &char_set)
 
static Font Create (SDF::SDFDoc &doc, const char *name, const UString &char_set)
 
static Font CreateType1Font (SDF::SDFDoc &doc, const UString &font_path, bool embed=true)
 
static Type GetType (SDF::Obj font_dict)
 

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

Definition at line 55 of file Font.h.

Member Enumeration Documentation

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

Parameters
docDocument in which the external font should be embedded.
logfontA pointer to a Windows LOGFONTA structure that defines the characteristics of the logical font.
embedA boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to 'true'.
subsetA boolean indicating whether the embedded font should be subsetted.
Note
This method is available only on Windows platforms.
Enumerator
e_IdentityH 
e_Indices 

Definition at line 127 of file Font.h.

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 

Definition at line 59 of file Font.h.

Enumerator
e_Type1 
e_TrueType 
e_MMType1 
e_Type3 
e_Type0 
e_CIDType0 
e_CIDType2 

Definition at line 218 of file Font.h.

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.

Parameters
font_dictThe Cos/SDF object to create the Font object with.
pdftron::PDF::Font::Font ( const Font c)

Member Function Documentation

static Font pdftron::PDF::Font::Create ( SDF::SDFDoc doc,
StandardType1Font  type,
bool  embed = false 
)
static

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

static Font pdftron::PDF::Font::Create ( SDF::SDFDoc doc,
Font from,
const UString char_set 
)
static

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

Parameters
doc- document in which the external font should be embedded.
logfontaA pointer to a Windows LOGFONTA 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
encoding- the encoding type either e_IdentityH (default) or e_Indices (to write glyph indices rather than unicode)
Note
This method is available only on Windows platforms. Create a CID TrueType PDF font with the characteristics specified in the LOGFONTA structure.
Parameters
doc- document in which the external font should be embedded.
logfontwA pointer to a Windows LOGFONTW 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
encoding- the encoding type either e_IdentityH (default) or e_Indices (to write glyph indices rather than unicode)
Note
This method is available only on Windows platforms. Create a new Unicode font based on the description of an existing PDF font.
static Font pdftron::PDF::Font::Create ( SDF::SDFDoc doc,
const char *  name,
const UString char_set 
)
static
static Font pdftron::PDF::Font::CreateCIDTrueTypeFont ( SDF::SDFDoc doc,
const UString font_path,
bool  embed = true,
bool  subset = true,
Encoding  encoding = e_IdentityH,
UInt32  ttc_font_index = 0 
)
static

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
encoding- the encoding type either e_IdentityH (default) or e_Indices (to write glyph indices rather than unicode)
ttc_font_index- if a TrueTypeCollection (TTC) font is loaded this parameter controls which font is actually picked
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
docDocument in which the external font should be embedded.
font_pathPath to the external font file.
embedA boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to 'true'.
subsetA 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

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'.
void pdftron::PDF::Font::Destroy ( )

Frees the native memory of the object.

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.
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.
Common::Iterator<UInt32> 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.

Font pdftron::PDF::Font::GetDescendant ( )
Returns
descendant CIDFont.
Note
Relevant only for a Type0 font.
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.
SDF::Obj pdftron::PDF::Font::GetDescriptor ( )
Returns
a SDF/Cos object representing FontDescriptor or NULL is FontDescriptor is not present.
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.
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 .
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 un-encoded 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.
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.
PathData pdftron::PDF::Font::GetGlyphPath ( UInt32  char_code,
bool  conics2cubics,
Common::Matrix2D transform = 0 
)

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

Parameters
char_codecharacter to query
conics2cubicsif set to true converts all quadratic Bezier curves to cubic Beziers, otherwise no conversion is performed.
Anoptional matrix used to transform glyph data coordinates. If null/unspecified, glyph data points will not be transformed.
Returns
A PathData object containing the path information.
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.
Check PathData::IsDefined to see if the char_code was mapped to 'undefined character code'.
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.
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.
SDF::Obj pdftron::PDF::Font::GetSDFObj ( )
Returns
a SDF/Cos object of this Font.
ShapedText pdftron::PDF::Font::GetShapedText ( const UString text_to_shape)

Creates a set of positioned glyphs corresponding to the visual representation of the provided text string.

The shaped text will take into account any advanced positioning and substitution features provided by an underylying embedded font file. For example, these features could include kerning, ligatures, and diacritic positioning. Typically the resulting shaped text would be fed into ElementBuilder.CreateShapedTextRun()

Parameters
text_to_shapethe string to be shaped.
Returns
A ShapedText object representing the result of the shaping operation.
Note
Shaping requires a Type0 font with an embedded font file which covers all the unicode codepoints in the source text. For best results, this font should use the e_Indices encoding scheme, as shaping features that combine multiple codepoints into one glyph (ligatures, for example) will not work well in non-index encoded fonts.
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.
Type pdftron::PDF::Font::GetType ( )
Returns
Font Type
static Type pdftron::PDF::Font::GetType ( SDF::Obj  font_dict)
static
Returns
The type of a given SDF/Cos font dictionary
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 ( UInt32  char_code)
Returns
a SDF/Cos glyph stream for the given char_code. If specified char_code is not found in the CharProcs dictionary the function returns NULL.
Note
Relevant only for a Type3 font.
UInt16 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.
double pdftron::PDF::Font::GetVerticalAdvance ( UInt32  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_codecharacter 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.
std::vector<double> pdftron::PDF::Font::GetVerticalAdvance ( UInt32  char_code)
double pdftron::PDF::Font::GetWidth ( UInt32  char_code) const
Returns
advance width, measured in glyph space units for the glyph matching given character code.
Note
1000 glyph units = 1 text space unit
The width returned has NOT been scaled by the font size, text matrix, nor the CTM.

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.

bool pdftron::PDF::Font::IsAllCap ( )
Returns
true if font contains no lowercase letters
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
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.
bool pdftron::PDF::Font::IsFixedWidth ( )
Returns
true if all glyphs have the same width
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.
bool pdftron::PDF::Font::IsItalic ( )
Returns
true if glyphs have dominant vertical strokes that are slanted.
bool pdftron::PDF::Font::IsSerif ( )
Returns
true if glyphs have serifs
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.

bool pdftron::PDF::Font::IsSymbolic ( )
Returns
true if font contains characters outside the Adobe standard Latin character set.
UInt32 pdftron::PDF::Font::MapToCID ( UInt32  char_code) const
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,
UInt32 out_charcode,
UInt32 out_cid 
) const

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_datathe input data buffer containing one or more bytes of input charcode
char_data_availthe number of bytes in the char_data buffer
out_charcodethe first charcode in char_data buffer.
out_cidCID 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.
UString pdftron::PDF::Font::MapToUnicode ( UInt32  char_code)

Maps the encoding specific 'charcode' to Unicode. Conversion of 'charcode' to Unicode can result in up to four Unicode characters.

Parameters
char_codeencoding specific 'charcode' that needs to be converted to Unicode.
out_uni_arrA pointer to an array of Unicode characters where the conversion result will be stored.
in_uni_szThe 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_numThe 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.
bool pdftron::PDF::Font::MapToUnicode ( UInt32  char_code,
Unicode out_uni_arr,
const int  in_uni_sz,
int &  out_chars 
)
Font& pdftron::PDF::Font::operator= ( const Font c)

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