PTFont

@interface PTFont : NSObject

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

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

    Declaration

    Objective-C

    - (instancetype)initWithFont_dict:(PTObj *)font_dict;

    Swift

    init!(font_dict: PTObj!)

    Parameters

    font_dict

    The Cos/SDF object to create the Font object with.

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

    Declaration

    Objective-C

    + (PTFont *)Create:(PTSDFDoc *)doc
              type:(PTStandardType1Font)type
             embed:(BOOL)embed;

    Swift

    class func create(_ doc: PTSDFDoc!, type: PTStandardType1Font, embed: Bool) -> PTFont!

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

    Declaration

    Objective-C

    + (PTFont *)CreateTrueTypeFont:(PTSDFDoc *)doc
                     font_path:(NSString *)font_path
                         embed:(BOOL)embed
                        subset:(BOOL)subset;

    Swift

    class func createTrueTypeFont(_ doc: PTSDFDoc!, font_path: String!, embed: Bool, subset: Bool) -> PTFont!

    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.

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

    Declaration

    Objective-C

    + (PTFont *)CreateCIDTrueTypeFont:(PTSDFDoc *)doc
                        font_path:(NSString *)font_path
                            embed:(BOOL)embed
                           subset:(BOOL)subset
                         encoding:(PTEncoding)encoding
                   ttc_font_index:(unsigned int)ttc_font_index;

    Swift

    class func createCIDTrueTypeFont(_ doc: PTSDFDoc!, font_path: String!, embed: Bool, subset: Bool, encoding: PTEncoding, ttc_font_index: UInt32) -> PTFont!

    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

  • Create a new Unicode font based on the description of an existing PDF font.

    Declaration

    Objective-C

    + (PTFont *)CreateFromFont:(PTSDFDoc *)doc
                      from:(PTFont *)from
                  char_set:(NSString *)char_set;

    Swift

    class func create(fromFont doc: PTSDFDoc!, from: PTFont!, char_set: String!) -> PTFont!

    Parameters

    doc

    document in which the external font should be embedded.
    from

    A Font object that provides the name for choosing a font. If the font with that name can be located and it covers a sufficient character set characters from that font will be used. Otherwise the font object created will be from a another font that covers the character set.
    char_set

    An initial character set. This provides an approach to specify any characters that are required to be included in the final font as part of a string. Note that additional characters will be added to the character set as needed, so it is not required to specify them here. (empty string is a perfectly valid and common value for this argument)

  • Create a new Unicode font based on the description of an existing PDF font.

    Declaration

    Objective-C

    + (PTFont *)CreateFromName:(PTSDFDoc *)doc
                      name:(NSString *)name
                  char_set:(NSString *)char_set;

    Swift

    class func create(fromName doc: PTSDFDoc!, name: String!, char_set: String!) -> PTFont!

    Parameters

    doc

    document in which the external font should be embedded.
    name

    A font name that provides a hint when choosing a font. If the font with that name can be located and it covers a sufficient character set characters from that font will be used. Otherwise the font object created will be from a another font that covers the character set.
    char_set

    An initial character set. This provides an approach to specify any characters that are required to be included in the final font as part of a string. Note that additional characters will be added to the character set as needed, so it is not required to specify them here. (empty string is a perfectly valid and common value for this argument)

  • Embed an external Type1 font in the document.

    Declaration

    Objective-C

    + (PTFont *)CreateType1Font:(PTSDFDoc *)doc
                  font_path:(NSString *)font_path
                      embed:(BOOL)embed;

    Swift

    class func createType1Font(_ doc: PTSDFDoc!, font_path: String!, embed: Bool) -> PTFont!

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

  • Declaration

    Objective-C

    - (PTFontType)GetType;

    Swift

    func getType() -> PTFontType

    Return Value

    Font Type

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

    Declaration

    Objective-C

    - (BOOL)IsSimple;

    Swift

    func isSimple() -> Bool

    Return Value

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

  • Declaration

    Objective-C

    - (PTObj *)GetSDFObj;

    Swift

    func getSDFObj() -> PTObj!

    Return Value

    a SDF/Cos object of this Font.

  • Declaration

    Objective-C

    - (PTObj *)GetDescriptor;

    Swift

    func getDescriptor() -> PTObj!

    Return Value

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

  • Declaration

    Objective-C

    - (NSString *)GetName;

    Swift

    func getName() -> String!

    Return Value

    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.

  • Declaration

    Objective-C

    - (NSString *)GetFamilyName;

    Swift

    func getFamilyName() -> String!

    Return Value

    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.

  • Declaration

    Objective-C

    - (BOOL)IsFixedWidth;

    Swift

    func isFixedWidth() -> Bool

    Return Value

    true if all glyphs have the same width

  • Declaration

    Objective-C

    - (BOOL)IsSerif;

    Swift

    func isSerif() -> Bool

    Return Value

    true if glyphs have serifs

  • Declaration

    Objective-C

    - (BOOL)IsSymbolic;

    Swift

    func isSymbolic() -> Bool

    Return Value

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

  • Declaration

    Objective-C

    - (BOOL)IsItalic;

    Swift

    func isItalic() -> Bool

    Return Value

    true if glyphs have dominant vertical strokes that are slanted.

  • Declaration

    Objective-C

    - (BOOL)IsAllCap;

    Swift

    func isAllCap() -> Bool

    Return Value

    true if font contains no lowercase letters

  • Declaration

    Objective-C

    - (BOOL)IsForceBold;

    Swift

    func isForceBold() -> Bool

    Return Value

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

  • Declaration

    Objective-C

    - (BOOL)IsHorizontalMode;

    Swift

    func isHorizontalMode() -> Bool

    Return Value

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

  • Note

    1000 glyph units = 1 text space unit

    Note

    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.

    Declaration

    Objective-C

    - (double)GetWidth:(unsigned int)char_code;

    Swift

    func getWidth(_ char_code: UInt32) -> Double

    Return Value

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

  • Declaration

    Objective-C

    - (double)GetMaxWidth;

    Swift

    func getMaxWidth() -> Double

    Return Value

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

  • Declaration

    Objective-C

    - (double)GetMissingWidth;

    Swift

    func getMissingWidth() -> Double

    Return Value

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

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

    Declaration

    Objective-C

    - (PTUInt32Iterator *)GetCharCodeIterator;

    Swift

    func getCharCodeIterator() -> PTUInt32Iterator!

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

    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.

    Note

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

    Note

    Check PathData::IsDefined to see if the char_code was mapped to ‘undefined character code’.

    Declaration

    Objective-C

    - (PTPathData *)GetGlyphPath:(unsigned int)char_code
               conics2cubics:(BOOL)conics2cubics
                   transform:(PTMatrix2D *)transform;

    Swift

    func getGlyphPath(_ char_code: UInt32, conics2cubics: Bool, transform: PTMatrix2D!) -> PTPathData!

    Parameters

    char_code

    character to query
    conics2cubics

    if set to true converts all quadratic Bezier curves to cubic Beziers, otherwise no conversion is performed.
    transform

    An optional matrix used to transform glyph data coordinates. If null/unspecified, glyph data points will not be transformed.

    Return Value

    A PathData object containing the path information.

  • 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()

    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.

    Declaration

    Objective-C

    - (PTShapedText *)GetShapedText:(NSString *)text_to_shape;

    Swift

    func getShapedText(_ text_to_shape: String!) -> PTShapedText!

    Parameters

    text_to_shape

    the string to be shaped.

    Return Value

    A ShapedText object representing the result of the shaping operation.

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

    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.

    Declaration

    Objective-C

    - (NSString *)MapToUnicode:(unsigned int)char_code;

    Swift

    func map(toUnicode char_code: UInt32) -> String!

    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.

    Return Value

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

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

    Declaration

    Objective-C

    - (BOOL)IsEmbedded;

    Swift

    func isEmbedded() -> Bool

    Return Value

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

  • Declaration

    Objective-C

    - (NSString *)GetEmbeddedFontName;

    Swift

    func getEmbeddedFontName() -> String!

    Return Value

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

  • Note

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

    Declaration

    Objective-C

    - (PTObj *)GetEmbeddedFont;

    Swift

    func getEmbeddedFont() -> PTObj!

    Return Value

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

  • Note

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

    Note

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

    Declaration

    Objective-C

    - (int)GetEmbeddedFontBufSize;

    Swift

    func getEmbeddedFontBufSize() -> Int32

    Return Value

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

  • Note

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

    Note

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

    Declaration

    Objective-C

    - (unsigned short)GetUnitsPerEm;

    Swift

    func getUnitsPerEm() -> UInt16

    Return Value

    the number of font units per EM square for this face. This is typically 2048 for TrueType fonts, 1000 for Type1 fonts

  • Declaration

    Objective-C

    - (PTPDFRect *)GetBBox;

    Swift

    func getBBox() -> PTPDFRect!

    Return Value

    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.

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

    Declaration

    Objective-C

    - (double)GetAscent;

    Swift

    func getAscent() -> Double

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

    Declaration

    Objective-C

    - (double)GetDescent;

    Swift

    func getDescent() -> Double

  • Declaration

    Objective-C

    - (int)GetStandardType1FontType;

    Swift

    func getStandardType1FontType() -> Int32

    Return Value

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

  • Note

    Only Type1 and Type1C fonts can be represented in CFF format

    Declaration

    Objective-C

    - (BOOL)IsCFF;

    Swift

    func isCFF() -> Bool

    Return Value

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

  • Note

    Relevant only for a Type3 font.

    Declaration

    Objective-C

    - (PTMatrix2D *)GetType3FontMatrix;

    Swift

    func getType3FontMatrix() -> PTMatrix2D!

    Return Value

    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.

    Declaration

    Objective-C

    - (PTObj *)GetType3GlyphStream:(unsigned int)char_code;

    Swift

    func getType3GlyphStream(_ char_code: UInt32) -> PTObj!

    Return Value

    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

    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.

    Note

    Relevant only for a Type0 font.

    Declaration

    Objective-C

    - (NSMutableArray *)GetVerticalAdvance:(unsigned int)char_code;

    Swift

    func getVerticalAdvance(_ char_code: UInt32) -> NSMutableArray!

    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.

    Return Value

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

  • Note

    Relevant only for a Type0 font.

    Declaration

    Objective-C

    - (PTFont *)GetDescendant;

    Swift

    func getDescendant() -> PTFont!

    Return Value

    descendant CIDFont.

  • Note

    Relevant only for a Type0 font.

    Declaration

    Objective-C

    - (unsigned int)MapToCID:(unsigned int)char_code;

    Swift

    func map(toCID char_code: UInt32) -> UInt32

    Return Value

    a CID matching specified charcode.