LayerPD_Layer
ObjectPDFont

A PDFont is a font that is used to draw text on a page. It corresponds to a font resource in a PDF file (see Chapter 5, Text, in the PDF Reference).

Plug-ins can get a list of PDFont objects used on a PDPage or a range of PDPage objects. More than one PDPage may reference the same PDFont object.

A PDFont has a number of attributes whose values can be read or set, including an array of widths, the character encoding, and the font's resource name.

In general, a PDFont refers to a base font and an encoding. The base font is specified by the font name and the subtype (typically Type 0, Type 1, MMType1, Type3, or TrueType). This combination of base font and encoding is commonly referred to as a font instance.

In single-byte character systems, an encoding specifies a mapping from an 8-bit index, often called a codepoint, to a glyph.

Type 0 fonts support single-byte or multibyte encodings and can refer to one or more descendent fonts. These fonts are analogous to the Type 0 or composite fonts supported by Level 2 PostScript interpreters. However, PDF Type 0 fonts only support character encodings defined by a character map (CMap). The CMap defines the encoding for a Type 0 font. It specifies the mappings between character codes and the glyphs in the descendant fonts. For more information on Type 0 fonts, see Section 5.6.5, Type 0 Font Dictionaries, in the PDF Reference. See Section 5.6.4, CMaps, for information on CMaps.

Type 0 fonts may have a CIDFont as a descendent. A CIDFont is designed to contain a large number of glyph procedures and is used for languages such as Chinese, Japanese, or Korean. Instead of being accessed by a name, each glyph procedure is accessed by an integer known as a character identifier or CID. Instead of a font encoding, CIDFonts use a CMap to define the mapping from character codes to a font number and a character selector. For more information on CIDFonts, see the following sections in the PDF Reference:

To access documents on CIDFonts, see the Adobe Solutions Network Web site (http://partners.adobe.com/asn).

For general information on CID Fonts, refer to these technical notes:

For information on specific CID fonts, see these technical notes:

Each base font contains a fixed set of glyphs. There are some common sets of glyph names, and these sets are typically called charsets. Acrobat takes advantage of the most common charset to enable font substitution. This charset is called the Adobe Standard Roman Character Set (see the PostScript Language Reference). If Acrobat encounters a font with this charset, it knows that it can represent all of the glyphs in the font using font substitution. Other common charsets are the Adobe Expert and Expert Subset charsets, and the Symbol charset. Most decorative fonts, such as Carta and Wingdings, have custom charsets.

Given a base font and its charset, multiple encodings are possible. For example, one encoding for a font could specify that the glyph for the letter 'A' appears at codepoint 65. A different encoding could specify that 'A' appears at both codepoint 65 and at codepoint 97. If text were rendered using the second encoding using the text string "a is always A", it would appear as "A is always A" using a font such as Times. Encodings allow glyphs to be reordered to the most convenient order for an application or operating system.

Every font has a default encoding, commonly called its built-in encoding. In PDF, shortcuts are taken when specifying an encoding in order to minimize document size. If a font instance uses the built-in encoding, no encoding information is written into the PDF document. If a font has a different encoding, only those codepoints for which the encoding differs from the built-in encoding are recorded in the PDF file. This information is called a difference encoding; it describes the difference between the built-in encoding and the current encoding.

For non-Roman systems, the font encoding may be a variety of encodings, which are defined by a CMap. See Section 5.6.4, CMaps, in the PDF Reference for a list of predefined CMaps, such as SHIFT-JIS for Japanese.

A host encoding is a platform-dependent encoding for the host machine's base font. For non-UNIX Roman systems, it is WinAnsiEncoding on Windows and MacRomanEncoding on Mac OS. For UNIX (except HP-UX) Roman systems, it is ISO8859-1 (ISO Latin-1). For HP-UX, it is HP-ROMAN8. See Appendix D, Character Sets and Encoding, in the PDF Reference for descriptions of WinAnsiEncoding and MacRomanEncoding. These encodings specify a mapping from codepoint to glyph name for fonts that use the Adobe Standard Roman Character Set on Mac OS and Windows.

Across PDF documents, or even within a single PDF document, the same base font can be used with more than one encoding. This allows documents from different platforms to be combined without losing information. Therefore, it is not uncommon to see a document that contains two instances of Helvetica, one using MacRoman encoding and another using WinAnsi encoding. See Appendix D, Character Sets and Encoding, in the PDF Reference for descriptions of WinAnsiEncoding and MacRomanEncoding. For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap.

Type 3 fonts do not have the ability to provide a base font with more than one encoding. For each Type 3 font, there is only one encoding. This encoding is completely specified in the PDF file; there are no shortcuts as there are for other fonts.

See Section 5.7, Font Descriptors, in the PDF Reference for a discussion of font descriptors. Methods are provided to create and destroy fonts, as well as to access the information in the font's descriptor.


Define Summary
 Define
 PDFontGetDescendant
Typedef Summary
 Typedef
 PDFont
A font that is used to draw text on a page. It corresponds to a Font Resource in a PDF file. Applications can get a list of PDFont objects used on a PDPage or a range of PDPage objects. More than one PDPage may reference the same PDFont object. A PDFont has a number of attributes whose values can be read or set, including an array of widths, the character encoding, and the font's resource name.
 PDFontAngle
An italic angle value in degrees, for use in PDFontMetrics.
 PDFontDownloadContext
A resource tree for a PDPage or other PDModel object. Maintains information about the current print job and what fonts have been downloaded.
 PDFontFlags
 PDFontMetric
An unsigned measurement of a font characteristic (for example, width).
 PDFontMetrics
 PDFontMetricsP
 PDFontOffset
A font offset value, for use in PDFontMetrics.
 PDFontStyles
 PDiFontMetric
A font metric value (which is never negative), for use in PDFontMetrics.
Enumeration Summary
 Enumeration
  PDFontEncoding
An enumerated data type that specifies a font's encoding.
  PDFontStyle
Specifies a synthetic font style.
Structure Summary
 Structure
 _t_PDFontFlags
A data structure containing additional information about a font.
 _t_PDFontMetrics
A data structure containing information about a font's metrics. See Section 5.5.1 in the PDF Reference for more information about font metrics.You also can find information about Adobe Font Metrics (AFM) at http://partners.adobe.com/asn.
 _t_PDFontStyles
A data structure containing PANOSE and sFamily class values for a font. It is used in the PDFontMetrics structure. See Section 5.7.2 in the PDF Reference for more information. For additional details on the PANOSE number, see the Japanese TrueType Font Property Selection Guidelines by the TrueType Conference Technical Committee.
Callback Summary
 Callback
 PDFontEnumProc
A callback used by PDDocEnumFonts() and PDDocEnumLoadedFonts(). It is called once for each font.
Method Summary
 Method
 
ASUns8** PDFontAcquireEncodingArray(PDFont font)
Acquires a font's encoding array (the mapping of character codes to glyphs). When you are done with this array, call PDFontEncodingArrayRelease() to release it.
 
ASInt16* PDFontAcquireXlateTable(PDFont font)
Increments the specified font's XlateTable reference count and also returns the XlateTable, which is a 256-entry table that maps characters from their encoding in the PDF file to host encoding. If a character cannot be mapped to host encoding, then the table entry will (for that character) contain -1. When you are done using the XlateTable, call PDFontXlateTableRelease() to release it.
 
void PDFontEncodingArrayRelease(ASUns8** array)
Releases a font's encoding array (the mapping of character codes to glyphs). Call this method after you are done using an encoding array acquired using PDFontAcquireEncodingArray().
 
void PDFontEnumCharProcs(PDFont font, PDCharProcEnumProc proc, void* clientData)
Enumerates a Type 3 font's character drawing procedures. The elements of a single character procedure can be enumerated using PDCharProcEnum().
 
PDFont PDFontFromCosObj(CosObj fontObj)
Converts a dictionary Cos object to a font. This method does not copy the object, but is instead the logical equivalent of a type cast.
 
void PDFontGetASTextName(PDFont font, ASBool removePrefix, ASText nameToFill)
Fills in an ASText object with the font name, to be used in displaying lists or menus.
 
void PDFontGetBBox(PDFont font, ASFixedRect* bboxP)
Gets a Type 3 font's bounding box, which is the smallest rectangle that would enclose every character in the font if they were overlaid and painted.
 
PDCharSet PDFontGetCharSet(PDFont font)
Gets the font's character set. This is derived from the 'Uses Adobe standard encoding' bit in the font descriptor (if the font has a font descriptor) or from the font's name (if the font is one of the base 14 fonts and does not have a font descriptor).
 
ASAtom PDFontGetCIDSystemInfo(PDFont font)
Gets an ASAtom representing Registry and Ordering for a CIDFont. This information resides in the CIDSystemInfo entry of the CIDFont dictionary, which describes a CIDFont.
 
ASInt32 PDFontGetCIDSystemSupplement(PDFont font)
Gets the SystemSupplement number of a CIDFont. This field resides in the CIDSystemInfo entry of the CIDFont dictionary, which describes a CIDFont.
 
CosObj PDFontGetCosObj(PDFont font)
Gets the Cos object for a font. This method does not copy the object, but is instead the logical equivalent of a type cast.
 
PDFont PDFontGetDescendant(PDFont font)
Gets a Type 0 font's descendant, which may be a CIDType0 or CIDType2 font.
 
ASInt32 PDFontGetEncodingIndex(PDFont font)
Gets a font's encoding index.
 
const ASUns8* PDFontGetEncodingName(PDFont font)
Gets a string representing a font's encoding.
 
void PDFontGetFontMatrix(PDFont fontP, ASFixedMatrix* matrixP)
Gets a font's matrix, which specifies the transformation from character space to text space. See Section 5.5.4 in the PDF Reference. This is only valid for Type 3 fonts.
 
void PDFontGetMetrics(PDFont font, PDFontMetricsP metricsP, os_size_t sizeMetrics)
Gets a font's metrics, which provide the information needed to create a substitute Multiple Master font when the original font is unavailable. See Section 5.7 in the PDF Reference for a discussion of font descriptors.
 
ASInt32 PDFontGetName(PDFont font, char* buffer, ASInt32 bufSize)
Gets 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. See Section 5.5.4 in the PDF Reference. For other types it gets the value of the BaseFont key in a PDF font resource.
 
ASAtom PDFontGetSubtype(PDFont font)
Gets a font's subtype.
 
void PDFontGetWidths(PDFont font, ASInt16* widths)
Gets the advance width of every glyph in a font. 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 (for example, a glyph representing an accent mark might have an advance width of zero so that characters can be drawn under it). For this reason, the advance width cannot be used to determine the glyphs' bounding boxes.
 
ASBool PDFontIsEmbedded(PDFont font)
Tests whether the specified font is embedded in the PDF file, meaning that the font is stored as a font file, which is a stream embedded in the PDF file. Only Type 1 and TrueType fonts can be embedded.
 
void PDFontSetMetrics(PDFont font, PDFontMetricsP metricsP, os_size_t sizeMetrics)
Sets a font's metrics, which provide the information needed to create a substitute Multiple Master font when the original font is unavailable. See Section 5.7 in the PDF Reference for a discussion of font descriptors. This method can only be used on Type 1, Multiple Master Type 1, and TrueType fonts; it cannot be used on Type 3 fonts.
 
ASBool PDFontXlateString(PDFont font, ASUns8* inP, ASUns8* outP, ASInt32 len)
Translates a string from the PDFont's encoding into host encoding. If any characters cannot be represented in host encoding, they are replaced with space characters. If no XlateTable exists in the font, the function returns false and outP is not written.
 
void PDFontXlateTableRelease(ASInt16* table)
Decrements the specified font's XlateTable reference count. The XlateTable is a 256-entry table that maps characters from their encoding in the PDF file to host encoding. If a character cannot be mapped to host encoding, then the table entry will (for that character) contain -1.
 
ASInt32 PDFontXlateToHost(PDFont fontP, ASUns8* inP, ASInt32 inLen, ASUns8* outP, ASInt32 outLen)
Translates a string from the PDFont's encoding to host encoding. This is useful for converting the text from a PDWord into host encoding. In the same way that PDXlateToHostEx() converts text from bookmark titles to host encoding, PDFontXlateToHost() converts text from a page contents stream to host encoding. Use PDFontXlateToUCS() to translate from the PDFont's encoding to Unicode.
 
ASInt32 PDFontXlateToUCS(PDFont fontP, ASUns8* inP, ASInt32 inLen, ASUns8* outP, ASInt32 outLen)
Translates a string from whatever encoding the PDFont uses to Unicode encoding. This is useful for converting the text from a PDWord into Unicode. Use PDFontXlateToHost() to translate from the PDFont's encoding to host encoding.
 
void PDFontXlateWidths(PDFont font, ASInt16* inP, ASInt16* outP)
Translates an array of 256 glyph advance widths (obtained from PDFontGetWidths()) from their order in the PDF file into host encoding order. If the widths are already in host encoding order, the widths are merely copied. All un-encoded code points are given a width of zero.
Defines Detail
PDFontGetDescendant 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDFontGetDescendant PDFontGetDescendantInt
File: PDCalls.h
Line: 164

Typedefs Detail
PDFont 
Product availability: All
Platform availability: All

Syntax

typedef struct _t_PDFont* PDFont;

A font that is used to draw text on a page. It corresponds to a Font Resource in a PDF file. Applications can get a list of PDFont objects used on a PDPage or a range of PDPage objects. More than one PDPage may reference the same PDFont object. A PDFont has a number of attributes whose values can be read or set, including an array of widths, the character encoding, and the font's resource name.

See Also

PDDocEnumFonts
PDDocEnumLoadedFonts
PDFontGetDescendant
PDStyleGetFont
PDDocEnumFonts
PDFontEnumCharProcs

File: PDBasicExpT.h
Line: 96
PDFontAngle 
Product availability: All
Platform availability: All

Syntax

typedef ASInt16 PDFontAngle;

An italic angle value in degrees, for use in PDFontMetrics.


File: PDExpT.h
Line: 67
PDFontDownloadContext 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_PDFontDownloadContext* PDFontDownloadContext;

A resource tree for a PDPage or other PDModel object. Maintains information about the current print job and what fonts have been downloaded.

See Also

PDFontDownloadContextCreate
PDFontDownloadContextDestroy

File: PDFLExpT.h
Line: 1632
PDFontFlags 
Product availability: All
Platform availability: All

Syntax

typedef _t_PDFontFlags PDFontFlags;

File: PDExpT.h
Line: 2161
PDFontMetric 
Product availability: All
Platform availability: All

Syntax

typedef ASUns16 PDFontMetric;

An unsigned measurement of a font characteristic (for example, width).


File: PDExpT.h
Line: 62
PDFontMetrics 
Product availability: All
Platform availability: All

Syntax

typedef _t_PDFontMetrics PDFontMetrics;

File: PDExpT.h
Line: 2373
PDFontMetricsP 
Product availability: All
Platform availability: All

Syntax

typedef _t_PDFontMetrics PDFontMetricsP;

File: PDExpT.h
Line: 2373
PDFontOffset 
Product availability: All
Platform availability: All

Syntax

typedef ASInt16 PDFontOffset;

A font offset value, for use in PDFontMetrics.


File: PDExpT.h
Line: 72
PDFontStyles 
Product availability: All
Platform availability: All

Syntax

typedef _t_PDFontStyles PDFontStyles;

File: PDExpT.h
Line: 2311
PDiFontMetric 
Product availability: All
Platform availability: All

Syntax

typedef ASInt16 PDiFontMetric;

A font metric value (which is never negative), for use in PDFontMetrics.


File: PDExpT.h
Line: 77

Enumeration Detail
PDFontEncoding
Product availability: All
Platform availability: All

Syntax

enum PDFontEncoding {
 PDBuiltInEncoding = -1,
 
 PDMacRomanEncoding = 0,
 
 PDMacExpertEncoding = 1,
 
 PDWinAnsiEncoding = 2,
 
 PDStdEncoding = 3,
 
 PDFDocEncoding = 4,
 
 PDLastKnownEncoding
}

File: PDExpT.h
Line: 2197

Elements
PDBuiltInEncoding  

The encoding specified internally in the font. In the case of a Type 1 or MMType 1 font, this is specified by the Encoding value in the font's fontdict. In the case of TrueType fonts, this is the encoding specified by the default one-byte CMap for the platform.

 
PDMacRomanEncoding  

MacRomanEncoding, as defined in Appendix D in the PDF Reference.

 
PDMacExpertEncoding  

MacExpertEncoding, as defined in Appendix D in the PDF Reference.

 
PDWinAnsiEncoding  

WinAnsiEncoding, as defined in Appendix D in the PDF Reference.

 
PDStdEncoding  

StandardEncoding, as defined in Appendix D in the PDF Reference.

 
PDFDocEncoding  

PDFDocEncoding, as defined in Appendix D in the PDF Reference. This will never be returned for a font; it is used internally.

 
PDFontStyle 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

enum PDFontStyle {
 PDRoman = 0,
 
 PDItalic,
 
 PDBold,
 
 PDBoldItalic
}

See Also

PDPrintFontRec

File: PDFLExpT.h
Line: 208


Structure Detail
_t_PDFontFlags
Product availability: All
Platform availability: All

Syntax

struct _t_PDFontFlags {
 ASInt32 notUsed; 
 
 ASUns32 flags; 
}

A data structure containing additional information about a font.

See Also

PDDocEnumFonts
PDFontEnumProc

File: PDExpT.h
Line: 2154

Elements
notUsed  

Not used. For backward compatibility.

 
flags  

It must be an OR of the PDFONTFLAGS_ values. All unused flags must be off.

_t_PDFontMetrics 
Product availability: All
Platform availability: All

Syntax

struct _t_PDFontMetrics {
 ASFlagBits flags; 
 
 ASFixedRect fontBBox; 
 
 PDiFontMetric missingWidth; 
 
 PDiFontMetric stemV; 
 
 PDiFontMetric stemH; 
 
 PDiFontMetric capHeight; 
 
 PDiFontMetric xHeight; 
 
 PDiFontMetric ascent; 
 
 PDiFontMetric descent; 
 
 PDiFontMetric leading; 
 
 PDiFontMetric maxWidth; 
 
 PDiFontMetric avgWidth; 
 
 PDFontAngle italicAngle; 
 
 PDFontStyles style; 
 
 PDFontOffset baseLineAdj; 
}

A data structure containing information about a font's metrics. See Section 5.5.1 in the PDF Reference for more information about font metrics.You also can find information about Adobe Font Metrics (AFM) at

See Also

PDFontGetMetrics
PDFontSetMetrics

File: PDExpT.h
Line: 2321

Elements
flags  

It must be an OR of the Font Flags values. All unused flags must be off.

 
fontBBox  

A font bounding box in 1000 EM units. An EM is a typographic unit of measurement equal to the size of a font. In a 12-point font, an EM is 12 points.

 
missingWidth  

The width of the missing character (.notdef)

 
stemV  

The vertical stem width.

 
stemH  

The horizontal stem width.

 
capHeight  

The capital height.

 
xHeight  

The X height.

 
ascent  

The maximum ascender height.

 
descent  

The maximum descender depth.

 
leading  

The additional leading between lines.

 
maxWidth  

The maximum character width.

 
avgWidth  

The average character width.

 
italicAngle  

The italic angle in degrees, if any.

 
style  

The PANOSE and sFamily class values.

 
baseLineAdj  

The baseline adjustment, which is a vertical adjustment for font baseline difference and writing mode 1 (vertical). This should only be used for CIDFontType 2 fonts with font substitution.

_t_PDFontStyles 
Product availability: All
Platform availability: All

Syntax

struct _t_PDFontStyles {
 ASUns8 sFamilyClassID; 
 
 ASUns8 sFamilySubclassID; 
 
 ASUns8 bFamilyType; 
 
 ASUns8 bSerifStyle; 
 
 ASUns8 bWeight; 
 
 ASUns8 bProportion; 
}

A data structure containing PANOSE and sFamily class values for a font. It is used in the PDFontMetrics structure. See Section 5.7.2 in the PDF Reference for more information. For additional details on the PANOSE number, see the Japanese TrueType Font Property Selection Guidelines by the TrueType Conference Technical Committee.

See Also

PDFontGetMetrics
PDFontSetMetrics

File: PDExpT.h
Line: 2279

Elements
sFamilyClassID  

A number that identifies the font family and determines the meaning of the remaining PANOSE digits. The possible families are Latin, Kanji, Hebrew, and so forth.

 
sFamilySubclassID  

A number to identify the kind of family: text, decorative, handwritten, symbols, and so on.

 
bFamilyType  

A number to identify the family type: text, decorative, handwritten, symbols, and so on.

 
bSerifStyle  

A number that specifies the font's serif style, such as cove, obtuse cove, square, bone, and so forth.

 
bWeight  

A number that specifies the font's weight, such as very light, heavy, black, and so on.

 
bProportion  

A number that specifies the font's proportions, such as modern, expanded, condensed, mono-spaced, and so on.

Callbacks Detail
PDFontEnumProc 
Product availability: All
Platform availability: All

Syntax

ASBool (*PDFontEnumProc)(PDFont font, PDFontFlags *fontFlags, void *clientData)

A callback used by PDDocEnumFonts() and PDDocEnumLoadedFonts(). It is called once for each font.

See Also

PDDocEnumFonts
PDDocEnumLoadedFonts

File: PDExpT.h
Line: 2175

Method Detail
PDFontAcquireEncodingArray()
Product availability: All
Platform availability: All

Syntax

ASUns8 PDFontAcquireEncodingArray(PDFont font)

Acquires a font's encoding array (the mapping of character codes to glyphs). When you are done with this array, call PDFontEncodingArrayRelease() to release it.

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.

For non-Roman character set viewers, it is not appropriate to call this method.

Parameters

font — 

The font whose encoding array is obtained.

Returns

The font's encoding array. It returns NULL if there is no encoding array associated with the font.

See Also

PDFontEncodingArrayRelease
PDFontGetEncodingIndex

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2749
PDFontAcquireXlateTable() 
Product availability: All
Platform availability: All

Syntax

ASInt16 PDFontAcquireXlateTable(PDFont font)

Increments the specified font's XlateTable reference count and also returns the XlateTable, which is a 256-entry table that maps characters from their encoding in the PDF file to host encoding. If a character cannot be mapped to host encoding, then the table entry will (for that character) contain -1. When you are done using the XlateTable, call PDFontXlateTableRelease() to release it.

For non-Roman character set viewers, it is not appropriate to call this method.

Parameters

font — 

IN/OUT The font whose XlateTable is obtained.

Returns

A pointer to the font's XlateTable, if any. Otherwise it returns NULL.

See Also

PDFontXlateTableRelease
PDFontXlateString

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2934
PDFontEncodingArrayRelease() 
Product availability: All
Platform availability: All

Syntax

void PDFontEncodingArrayRelease(ASUns8** array)

Releases a font's encoding array (the mapping of character codes to glyphs). Call this method after you are done using an encoding array acquired using PDFontAcquireEncodingArray().

Parameters

array — 

IN/OUT The encoding array to release.

See Also

PDFontAcquireEncodingArray

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2760
PDFontEnumCharProcs() 
Product availability: All
Platform availability: All

Syntax

void PDFontEnumCharProcs(PDFont font, PDCharProcEnumProc proc, void* clientData)

Enumerates a Type 3 font's character drawing procedures. The elements of a single character procedure can be enumerated using PDCharProcEnum().

Parameters

font — 

IN/OUT The Type 3 font's character drawing procedures are being enumerated.

 
proc — 

IN/OUT A user-supplied callback to call for each character in the font. Enumeration ends if proc returns false. If the font contains no characters, proc will not be called.
 
clientData — 

IN/OUT A pointer to user-supplied data passed to proc each time it is called.

See Also

PDCharProcEnum
PDDocEnumFonts
PDDocEnumLoadedFonts

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 3931
PDFontFromCosObj() 
Product availability: All
Platform availability: All

Syntax

PDFont PDFontFromCosObj(CosObj fontObj)

Converts a dictionary Cos object to a font. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

fontObj — 

IN/OUT The dictionary Cos object for the font.

Returns

The PDFont for fontObj. It returns NULL if there is no CosDoc or PDDoc containing fontObj.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7660
PDFontGetASTextName() 
Product availability: All
Platform availability: All

Syntax

void PDFontGetASTextName(PDFont font, ASBool removePrefix, ASText nameToFill)

Fills in an ASText object with the font name, to be used in displaying lists or menus.

In PDF 1.5, the font name can be represented with a UTF8 byte sequence. In previous versions of Acrobat the name could also be represented by host encodings such as Shift- JIS, Big5, KSC, and so on. This routine tries to return a text object that uses the correct script, but cannot always do so.

The ASText object is owned by the caller.

Parameters

font — 

The font whose name is obtained.

 
removePrefix — 

Whether to remove the subset prefix, if present. For example, when true, the name "ABCDEF+Myriad" is returned as "Myriad".

 
nameToFill — 

(Filled by the method) The ASText object for the font's name.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10988
PDFontGetBBox() 
Product availability: All
Platform availability: All

Syntax

void PDFontGetBBox(PDFont font, ASFixedRect* bboxP)

Gets a Type 3 font's bounding box, which is the smallest rectangle that would enclose every character in the font if they were overlaid and painted.

Parameters

font — 

IN/OUT The font whose bounding box is obtained.

 
bboxP — 

IN/OUT (Filled by the method) A pointer to a rectangle specifying the font's bounding box.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2790
PDFontGetCharSet() 
Product availability: All
Platform availability: All

Syntax

PDCharSet PDFontGetCharSet(PDFont font)

Gets the font's character set. This is derived from the 'Uses Adobe standard encoding' bit in the font descriptor (if the font has a font descriptor) or from the font's name (if the font is one of the base 14 fonts and does not have a font descriptor).

For non-Roman character set viewers, call PDFontGetEncodingName() instead.

Parameters

font — 

IN/OUT The font whose character set is obtained.

Returns

The font's character set. For non-Roman character set viewers, it returns PDUnknownCharSet.

See Also

PDFontGetEncodingName

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2707
PDFontGetCIDSystemInfo() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDFontGetCIDSystemInfo(PDFont font)

Gets an ASAtom representing Registry and Ordering for a CIDFont. This information resides in the CIDSystemInfo entry of the CIDFont dictionary, which describes a CIDFont.

PDFontGetCIDSystemInfo() takes either a Type 0 font or a descendant font (CIDType0 or CIDType2) as an argument. This information is always present for any Type 0 font; the actual registry ordering information is a part of the descendant font.

This method provides one way to identify a font's language.

The CIDSystemInfo entry uses three components to identify a character collection uniquely:

The PDFontGetCIDSystemInfo() method obtains the first two of these components.

A CIDFont is designed to contain a large number of glyph procedures. Instead of being accessed by a name, each glyph procedure is accessed by an integer known as a character identifier or CID. Instead of a font encoding, CIDFonts use a CMap with a Type 0 composite font to define the mapping from character codes to a font number and a character selector.

For more information on Type 0 fonts, CIDFonts, and CMaps, see Section 5.6 in the PDF Reference. For detailed information on CIDFonts, see Technical Note # 5092, CID-Keyed Font Technology Overview, and Technical Note # 5014, Adobe CMap and CIDFont Files Specification.

Parameters

font — 

IN/OUT The font whose Registry and Ordering information is obtained.

Returns

The ASAtom representing the CIDFont's Registry and Ordering information (for example, "Adobe-Japan1").

See Also

PDFontGetCIDSystemSupplement
PDFontGetDescendant

Since

PI_PDMODEL_VERSION >= 0x00020003

File: PDProcs.h
Line: 6221
PDFontGetCIDSystemSupplement() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDFontGetCIDSystemSupplement(PDFont font)

Gets the SystemSupplement number of a CIDFont. This field resides in the CIDSystemInfo entry of the CIDFont dictionary, which describes a CIDFont.

The CIDSystemInfo entry uses three components to identify a character collection uniquely:

PDFontGetCIDSystemInfo() provides character collection information, and PDFontGetCIDSystemSupplement() specifies the version of the ordering.

A CIDFont is designed to contain a large number of glyph procedures. Instead of being accessed by a name, each glyph procedure is accessed by an integer known as a character identifier or CID. Instead of a font encoding, CIDFonts use a CMap with a Type 0 composite font to define the mapping from character codes to a font number and a character selector.

For more information on Type 0 fonts, CIDFonts, and CMaps, see Section 5.6 in the PDF Reference. For detailed information on CIDFonts, see Technical Note # 5092, CID-Keyed Font Technology Overview, and Technical Note # 5014, Adobe CMap and CIDFont Files Specification.

Parameters

font — 

IN/OUT The font whose SystemSupplement field is obtained.

Returns

The SystemSupplement field from the CIDFont.

See Also

PDFontGetDescendant
PDFontGetCIDSystemInfo

Since

PI_PDMODEL_VERSION >= 0x00020003

File: PDProcs.h
Line: 6263
PDFontGetCosObj() 
Product availability: All
Platform availability: All

Syntax

CosObj PDFontGetCosObj(PDFont font)

Gets the Cos object for a font. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

font — 

IN/OUT The font whose Cos object is obtained.

Returns

The dictionary Cos object for the font. The dictionary's contents may be enumerated with CosObjEnum().

See Also

PDDocEnumFonts

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2993
PDFontGetDescendant() 
Product availability: All
Platform availability: All

Syntax

PDFont PDFontGetDescendant(PDFont font)

Gets a Type 0 font's descendant, which may be a CIDType0 or CIDType2 font.

Type 0 fonts support single-byte or multi-byte encodings and can refer to one or more descendant fonts. These fonts are analogous to the Type 0 or composite fonts supported by Level 2 PostScript interpreters. However, PDF Type 0 fonts only support character encodings defined by a CMap. The CMap specifies the mappings between character codes and the glyphs in the descendant fonts.

For information on Type 0 fonts, see Section 5.6 in the PDF Reference. See Section 5.6.4 for more details on CMaps.

Parameters

font — 

IN/OUT The font whose descendant is obtained.

Returns

The font's descendant font.

See Also

PDFontGetCIDSystemInfo
PDFontGetCIDSystemSupplement

Since

PI_PDMODEL_VERSION >= 0x00020003

File: PDProcs.h
Line: 6143
PDFontGetEncodingIndex() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDFontGetEncodingIndex(PDFont font)

Gets a font's encoding index.

For non-Roman character set viewers, call PDFontGetEncodingName() instead.

Parameters

font — 

IN/OUT The font whose encoding index is obtained.

Returns

A font encoding index. If the index is greater than PDLastKnownEncoding, it is a custom encoding, and is unique within the document. If the index is less than PDLastKnownEncoding, it must be one of the PDFontEncoding values.

See Also

PDFontAcquireEncodingArray

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2723
PDFontGetEncodingName() 
Product availability: All
Platform availability: All

Syntax

ASUns8 PDFontGetEncodingName(PDFont font)

Gets a string representing a font's encoding.

Use PDFontGetEncodingIndex() to get encoding information for Roman viewers.

Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is WinAnsiEncoding on Windows and MacRomanEncoding on Mac OS. On UNIX (except HP-UX) Roman systems, it is ISO8859-1 (ISO Latin-1); for HP-UX, it is HP-ROMAN8. See Appendix D in the PDF Reference for descriptions of WinAnsiEncoding, MacRomanEncoding, and PDFDocEncoding.

For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). See Section 5.6.4 in the PDF Reference for a list of predefined CMaps. In this case, the encoding string contains values such as "90ms-RKSJ-H", "90msp-RKSJ-H", "Identity-V", or "90pv-RKSJ-H"; it does not return a string like "Shift-JIS".

Parameters

font — 

The font whose encoding name is obtained.

Returns

The string representing the font's encoding.

See Also

PDFontGetEncodingIndex
PDGetHostEncoding

Since

PI_PDMODEL_VERSION >= 0x00020003

File: PDProcs.h
Line: 6171
PDFontGetFontMatrix() 
Product availability: All
Platform availability: All

Syntax

void PDFontGetFontMatrix(PDFont fontP, ASFixedMatrix* matrixP)

Gets a font's matrix, which specifies the transformation from character space to text space. See Section 5.5.4 in the PDF Reference. This is only valid for Type 3 fonts.

Parameters

fontP — 

IN/OUT The font whose matrix is obtained.

 
matrixP — 

IN/OUT (Filled by the method) A pointer to the font's matrix.

See Also

PDDocEnumFonts

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2963
PDFontGetMetrics() 
Product availability: All
Platform availability: All

Syntax

void PDFontGetMetrics(PDFont font, PDFontMetricsP metricsP, os_size_t sizeMetrics)

Gets a font's metrics, which provide the information needed to create a substitute Multiple Master font when the original font is unavailable. See Section 5.7 in the PDF Reference for a discussion of font descriptors.

Parameters

font — 

IN/OUT The font whose metrics are being obtained.
 
metricsP — 

IN/OUT (Filled by the method) A pointer to a PDFontMetrics structure containing the font's metrics. The font metric values may be patched before being returned. If the actual values in the PDF file are required, use Cos instead to get trustworthy metrics.

 
sizeMetrics — 

IN/OUT It must be sizeof(PDFontMetrics).

See Also

PDFontGetWidths
PDFontSetMetrics

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2779
PDFontGetName() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDFontGetName(PDFont font, char* buffer, ASInt32 bufSize)

Gets 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. See Section 5.5.4 in the PDF Reference. For other types it gets the value of the BaseFont key in a PDF font resource.

Parameters

font — 

IN/OUT The font whose name is obtained.

 
buffer — 

IN/OUT (Filled by the method) The buffer into which the font's name is stored. The client may pass in NULL to obtain the buffer size, excluding the terminating NULL, and then call the method with a buffer of the appropriate size. You must pass at least the bufSize + 1 as the buffer size

 
bufSize — 

IN/OUT The length of buffer in bytes. The maximum font name length that the Acrobat viewer will return is PSNAMESIZE (see PDExpT. h).

Returns

The number of characters in the font name. If the font name is too long to fit into buffer, bufSize - 1 bytes are copied into buffer, and buffer is NULL-terminated.

See Also

PDDocEnumFonts
PDFontGetEncodingName

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2679
PDFontGetSubtype() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDFontGetSubtype(PDFont font)

Gets a font's subtype.

Parameters

font — 

IN/OUT The font whose subtype is obtained.

Returns

The font's subtype. The ASAtom returned can be converted to a string using ASAtomGetString(). It must be one of the Font Subtypes.

See Also

PDDocEnumFonts

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2690
PDFontGetWidths() 
Product availability: All
Platform availability: All

Syntax

void PDFontGetWidths(PDFont font, ASInt16* widths)

Gets the advance width of every glyph in a font. 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 (for example, a glyph representing an accent mark might have an advance width of zero so that characters can be drawn under it). For this reason, the advance width cannot be used to determine the glyphs' bounding boxes.

For non-Roman character set viewers, this method gets the width for a single byte range (0 through 255).

Parameters

font — 

IN/OUT The font whose glyph advance widths are obtained.
 
widths — 

IN/OUT (Filled by the method) An array of glyph advance widths, measured in character space units. Un-encoded code points will have a width of zero. For non-Roman character set viewers, an array for a single byte range (0 through 255).

See Also

PDFontGetMetrics
PDFontSetMetrics
PDFontXlateWidths

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2816
PDFontIsEmbedded() 
Product availability: All
Platform availability: All

Syntax

ASBool PDFontIsEmbedded(PDFont font)

Tests whether the specified font is embedded in the PDF file, meaning that the font is stored as a font file, which is a stream embedded in the PDF file. Only Type 1 and TrueType fonts can be embedded.

Parameters

font — 

The font to test.

Returns

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

See Also

PDDocEnumFonts

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2861
PDFontSetMetrics() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDFontSetMetrics(PDFont font, PDFontMetricsP metricsP, os_size_t sizeMetrics)

Sets a font's metrics, which provide the information needed to create a substitute Multiple Master font when the original font is unavailable. See Section 5.7 in the PDF Reference for a discussion of font descriptors. This method can only be used on Type 1, Multiple Master Type 1, and TrueType fonts; it cannot be used on Type 3 fonts.

Parameters

font — 

IN/OUT The font whose metrics are being set.

 
metricsP — 

IN/OUT A pointer to a PDFontMetrics structure containing the font's metrics.

 
sizeMetrics — 

IN/OUT It must be sizeof(PDFontMetrics).

See Also

PDFontGetMetrics

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2980
PDFontXlateString() 
Product availability: All
Platform availability: All

Syntax

ASBool PDFontXlateString(PDFont font, ASUns8* inP, ASUns8* outP, ASInt32 len)

Translates a string from the PDFont's encoding into host encoding. If any characters cannot be represented in host encoding, they are replaced with space characters. If no XlateTable exists in the font, the function returns false and outP is not written.

For non-Roman character set viewers, it is not appropriate to call this method. Instead call one of the following: PDFontXlateToHost(), PDFontXlateToUCS(), PDXlateToHostEx(), or PDXlateToPDFDocEncEx().

Parameters

font — 

The font (and hence, the encoding) that inP uses.
 
inP — 

The string to translate.

 
outP — 

(Filled by the method) The translated string. outP may point to the same buffer as inP, to allow in-place translation.

 
len — 

The length of inP and outP.

Returns

true if an XlateTable exists in the font, false otherwise. If no XlateTable exists in the font, outP is not written.

See Also

PDFontXlateToHost
PDFontAcquireXlateTable
PDFontXlateToUCS
PDXlateToHostEx
PDXlateToPDFDocEncEx

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2913
PDFontXlateTableRelease() 
Product availability: All
Platform availability: All

Syntax

void PDFontXlateTableRelease(ASInt16* table)

Decrements the specified font's XlateTable reference count. The XlateTable is a 256-entry table that maps characters from their encoding in the PDF file to host encoding. If a character cannot be mapped to host encoding, then the table entry will (for that character) contain -1.

Parameters

table — 

IN/OUT The XlateTable to release.

See Also

PDFontAcquireXlateTable
PDFontXlateString

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2948
PDFontXlateToHost() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDFontXlateToHost(PDFont fontP, ASUns8* inP, ASInt32 inLen, ASUns8* outP, ASInt32 outLen)

Translates a string from the PDFont's encoding to host encoding. This is useful for converting the text from a PDWord into host encoding. In the same way that PDXlateToHostEx() converts text from bookmark titles to host encoding, PDFontXlateToHost() converts text from a page contents stream to host encoding. Use PDFontXlateToUCS() to translate from the PDFont's encoding to Unicode.

Non-Roman fonts, such as PostScript composite fonts, can be encoded in different ways, such as SHIFT-JIS, RKSJ, and so on. To use PDFontXlateToHost(), the caller does not need to know which encoding he is converting from, since that information is contained in the PDFont.

Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is WinAnsiEncoding on Windows and MacRomanEncoding on Mac OS. On UNIX (except HP-UX) Roman systems, it is ISO8859-1 (ISO Latin-1); for HP-UX, it is HP-ROMAN8. See Appendix D in the PDF Reference for descriptions of MacRomanEncoding, WinAnsiEncoding, and PDFDocEncoding.

For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). See Section 5.6.4 in the PDF Reference for a list of predefined CMaps.

Use PDGetHostEncoding() to determine if a system's host encoding is Roman.

Parameters

fontP — 

The font used in the input string inP.

 
inP — 

A pointer to the string to translate.

 
inLen — 

The length of the inP buffer in bytes.

 
outP — 

(Filled by the method) A pointer to the translated string.

 
outLen — 

The length of the outP buffer in bytes.

Returns

The number of bytes in the translated string outP.

See Also

PDFontXlateString
PDFontXlateToUCS
PDGetHostEncoding
PDXlateToHostEx
PDXlateToPDFDocEncEx

Since

PI_PDMODEL_VERSION >= 0x00020003

File: PDProcs.h
Line: 6516
PDFontXlateToUCS() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDFontXlateToUCS(PDFont fontP, ASUns8* inP, ASInt32 inLen, ASUns8* outP, ASInt32 outLen)

Translates a string from whatever encoding the PDFont uses to Unicode encoding. This is useful for converting the text from a PDWord into Unicode. Use PDFontXlateToHost() to translate from the PDFont's encoding to host encoding.

Non-Roman fonts, like PostScript composite fonts, can be encoded in different ways, such as SHIFT-JIS, RKSJ, and so on. The caller does not need to know which encoding they're converting from, since that information is contained in the PDFont.

Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is WinAnsiEncoding on Windows and MacRomanEncoding on Mac OS. On UNIX (except HP-UX) Roman systems, it is ISO8859-1 (ISO Latin-1); for HP-UX, it is HP-ROMAN8. See Appendix D in the PDF Reference for descriptions of WinAnsiEncoding, MacRomanEncoding, and PDFDocEncoding.

For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). See Section 5.6.4 in the PDF Reference for a list of predefined CMaps.

Use PDGetHostEncoding() to determine if a system's host encoding is Roman.

Parameters

fontP — 

The font of the input string inP.

 
inP — 

A pointer to the string to translate.

 
inLen — 

The length of the inP buffer in bytes.

 
outP — 

(Filled by the method) A pointer to the translated string. If it is NULL, the method returns the size of the translated string.

 
outLen — 

The length of the outP buffer in bytes. If it is 0, the method returns the size of the translated string.

Returns

The number of bytes in the translated string in outP.

See Also

PDFontXlateToHost
PDGetHostEncoding
PDXlateToHostEx
PDXlateToPDFDocEncEx

Since

PI_PDMODEL_VERSION >= 0x00020003

File: PDProcs.h
Line: 6561
PDFontXlateWidths() 
Product availability: All
Platform availability: All

Syntax

void PDFontXlateWidths(PDFont font, ASInt16* inP, ASInt16* outP)

Translates an array of 256 glyph advance widths (obtained from PDFontGetWidths()) from their order in the PDF file into host encoding order. If the widths are already in host encoding order, the widths are merely copied. All un-encoded code points are given a width of zero.

For non-Roman character set viewers, it is not appropriate to call this method.

Parameters

font — 

IN/OUT The font whose glyph widths are translated.
 
inP — 

IN/OUT The array of glyph advance widths to rearrange.
 
outP — 

IN/OUT (Filled by the method) The rearranged array of glyph advance widths.

See Also

PDFontGetWidths

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 2883



© 2004-2013 Adobe Systems Incorporated. All rights reserved.
Thu Jan 21 2016, 11:19 AM IST