iOS Developer Library

Developer

ApplicationServices Framework Reference CGFont Reference

Options
Deployment Target:

On This Page
Language:

CGFont Reference

The CGFontRef opaque type encapsulates font information. A font is a set of shapes or glyphs associated with a character set. A glyph can represent a single character (such as ‘b’), more than one character (such as the “fi” ligature), or a special character such as a space. Quartz retrieves the glyphs for the font from ATS (Apple Type Services) and paints the glyphs based on the relevant parameters of the current graphics state.

Quartz provides a limited, low-level interface for drawing text. For information on text-drawing functions, see CGContext Reference. For full Unicode and text-layout support, use the services provided by Core Text or ATSUI).

Functions

  • Decrements the retain count of a Quartz font.

    Declaration

    Objective-C

    void CGFontRelease ( CGFontRef font );

    Parameters

    font

    The Quartz font to release.

    Discussion

    This function is equivalent to CFRelease, except that it does not cause an error if the font parameter is NULL.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • Increments the retain count of a Quartz font.

    Declaration

    Objective-C

    CGFontRef CGFontRetain ( CGFontRef font );

    Parameters

    font

    The Quartz font to retain.

    Return Value

    The same font you specified in the font parameter.

    Discussion

    This function is equivalent to CFRetain, except that it does not cause an error if the font parameter is NULL.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • Creates a font object from data supplied from a data provider.

    Declaration

    Swift

    func CGFontCreateWithDataProvider(_ provider: CGDataProvider!) -> CGFont!

    Objective-C

    CGFontRef CGFontCreateWithDataProvider ( CGDataProviderRef provider );

    Parameters

    provider

    A data provider.

    Return Value

    The font object or NULL if the font can't be created. You are responsible for releasing this object using CGFontRelease.

    Discussion

    Before drawing text in a Quartz context, you must set the font in the current graphics state by calling the function CGContextSetFontSize.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Creates a font object corresponding to the font specified by a PostScript or full name.

    Declaration

    Swift

    func CGFontCreateWithFontName(_ name: CFString!) -> CGFont!

    Objective-C

    CGFontRef CGFontCreateWithFontName ( CFStringRef name );

    Parameters

    name

    The PostScript or full name of a font.

    Return Value

    The font object or NULL if the font can't be created. You are responsible for releasing this object using CGFontRelease.

    Discussion

    Before drawing text in a Quartz context, you must set the font in the current graphics state by calling the function CGContextSetFont.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Creates a copy of a font using a variation specification dictionary.

    Declaration

    Swift

    func CGFontCreateCopyWithVariations(_ font: CGFont!, _ variations: CFDictionary!) -> CGFont!

    Objective-C

    CGFontRef CGFontCreateCopyWithVariations ( CGFontRef font, CFDictionaryRef variations );

    Parameters

    font

    The Quartz font to copy.

    variations

    A variation specification dictionary that contains keys corresponding to the variation axis names of the font. Each key in the dictionary is a variation axis name. The value for each key is the value specified for that particular variation axis represented as a CFNumber object. If a variation axis name is not specified in variations, then the current value from font is used.

    Return Value

    The font object.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Obtains the PostScript name of a font.

    Declaration

    Swift

    func CGFontCopyPostScriptName(_ font: CGFont!) -> CFString!

    Objective-C

    CFStringRef CGFontCopyPostScriptName ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The PostScript name of the font.

    Discussion

    For more information on PostScript format, see Adobe Type 1 Font Format, which is available from http://partners.adobe.com/.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Determines whether Quartz can create a subset of the font in PostScript format.

    Declaration

    Swift

    func CGFontCanCreatePostScriptSubset(_ font: CGFont!, _ format: CGFontPostScriptFormat) -> Bool

    Objective-C

    bool CGFontCanCreatePostScriptSubset ( CGFontRef font, CGFontPostScriptFormat format );

    Parameters

    font

    A font object.

    Return Value

    Returns true if a subset in the PostScript format can be created for the font; false otherwise.

    Discussion

    For more information on PostScript format, see Adobe Type 1 Font Format, which is available from http://partners.adobe.com/.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Creates a subset of the font in the specified PostScript format.

    Declaration

    Swift

    func CGFontCreatePostScriptSubset(_ font: CGFont!, _ subsetName: CFString!, _ format: CGFontPostScriptFormat, _ glyphs: UnsafePointer<CGGlyph>, _ count: UInt, _ encoding: UnsafePointer<CGGlyph>) -> CFData!

    Objective-C

    CFDataRef CGFontCreatePostScriptSubset ( CGFontRef font, CFStringRef subsetName, CGFontPostScriptFormat format, const CGGlyph glyphs[], size_t count, const CGGlyph encoding[256] );

    Parameters

    font

    A font object.

    subsetName

    The name of the subset.

    format

    The PostScript format of the font.

    glyphs

    An array that contains the glyphs in the subset.

    count

    The number of glyphs specified by the glyphs array.

    encoding

    The default encoding for the subset. You can pass NULL if you do not want to specify an encoding.

    Return Value

    A subset of the font created from the supplied parameters.

    Discussion

    For more information on PostScript format, see Adobe Type 1 Font Format, which is available from http://partners.adobe.com/.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Creates a PostScript encoding of a font.

    Declaration

    Swift

    func CGFontCreatePostScriptEncoding(_ font: CGFont!, _ encoding: UnsafePointer<CGGlyph>) -> CFData!

    Objective-C

    CFDataRef CGFontCreatePostScriptEncoding ( CGFontRef font, const CGGlyph encoding[256] );

    Parameters

    font

    A CGFont object.

    encoding

    The encoding to use.

    Return Value

    A PostScript encoding of the font that contains glyphs in the specified encoding.

    Discussion

    For more information on PostScript format, see Adobe Type 1 Font Format, which is available from http://partners.adobe.com/.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns an array of tags that correspond to the font tables for a font.

    Declaration

    Swift

    func CGFontCopyTableTags(_ font: CGFont!) -> CFArray!

    Objective-C

    CFArrayRef CGFontCopyTableTags ( CGFontRef font );

    Parameters

    font

    A CGFont object.

    Return Value

    An array of font table tags.

    Discussion

    Each entry in the returned array is a four-byte value that represents a single TrueType or OpenType font table tag. To obtain a tag at index k in a manner that is appropriate for 32-bit and 64-bit architectures, you need to use code similar to the following:

    • tag = (uint32_t)(uintptr_t)CFArrayGetValue(table, k);

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the font table that corresponds to the provided tag.

    Declaration

    Swift

    func CGFontCopyTableForTag(_ font: CGFont!, _ tag: UInt32) -> CFData!

    Objective-C

    CFDataRef CGFontCopyTableForTag ( CGFontRef font, uint32_t tag );

    Parameters

    font

    A font object.

    tag

    The tag for the table you want to obtain.

    Return Value

    The font table that corresponds to the tag, or NULL if no such table exists.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the Core Foundation type identifier for Quartz fonts.

    Declaration

    Swift

    func CGFontGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGFontGetTypeID ( void );

    Return Value

    The Core Foundation identifier for the opaque type CGFontRef.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns an array of the variation axis dictionaries for a font.

    Declaration

    Swift

    func CGFontCopyVariationAxes(_ font: CGFont!) -> CFArray!

    Objective-C

    CFArrayRef CGFontCopyVariationAxes ( CGFontRef font );

    Parameters

    font

    A CGFont object.

    Return Value

    An array of the variation axis dictionaries. Returns NULL if the font doesn't support variations.

    Discussion

    A variation axis is a range included in a font by the font designer that allows a font to produce different type styles. Each variation axis dictionary contains key-value pairs that specify the variation axis name and the minimum, maximum, and default values for that variation axis.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the variation specification dictionary for a font.

    Declaration

    Swift

    func CGFontCopyVariations(_ font: CGFont!) -> CFDictionary!

    Objective-C

    CFDictionaryRef CGFontCopyVariations ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The variation specification dictionary for the font. Returns NULL if the font doesn't support variations.

    Discussion

    The variation specification dictionary contains keys that correspond to the variation axis names of the font. Each key is a variation axis name. The value for each key is the value specified for that particular variation axis represented as a CFNumber object.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the full name associated with a font object.

    Declaration

    Swift

    func CGFontCopyFullName(_ font: CGFont!) -> CFString!

    Objective-C

    CFStringRef CGFontCopyFullName ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The full name associated with the font.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the ascent of a font.

    Declaration

    Swift

    func CGFontGetAscent(_ font: CGFont!) -> Int32

    Objective-C

    int CGFontGetAscent ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The ascent of the font.

    Discussion

    The ascent is the maximum distance above the baseline of glyphs in a font. The value is specified in glyph space units.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the descent of a font.

    Declaration

    Swift

    func CGFontGetDescent(_ font: CGFont!) -> Int32

    Objective-C

    int CGFontGetDescent ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The descent of the font .

    Discussion

    The descent is the maximum distance below the baseline of glyphs in a font. The value is specified in glyph space units.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the leading of a font.

    Declaration

    Swift

    func CGFontGetLeading(_ font: CGFont!) -> Int32

    Objective-C

    int CGFontGetLeading ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The leading of the font.

    Discussion

    The leading is the spacing between consecutive lines of text in a font. The value is specified in glyph space units.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the cap height of a font.

    Declaration

    Swift

    func CGFontGetCapHeight(_ font: CGFont!) -> Int32

    Objective-C

    int CGFontGetCapHeight ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The cap height of the font.

    Discussion

    The cap height is the distance above the baseline of the top of flat capital letters of glyphs in a font. The value is specified in glyph space units.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the x-height of a font.

    Declaration

    Swift

    func CGFontGetXHeight(_ font: CGFont!) -> Int32

    Objective-C

    int CGFontGetXHeight ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The x-height of the font.

    Discussion

    The x-height is the distance above the baseline of the top of flat, non-ascending lowercase letters (such as x) of glyphs in a font. The value is specified in glyph space units.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the bounding box of a font.

    Declaration

    Swift

    func CGFontGetFontBBox(_ font: CGFont!) -> CGRect

    Objective-C

    CGRect CGFontGetFontBBox ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The bounding box of the font.

    Discussion

    The font bounding box is the union of all of the bounding boxes for all the glyphs in a font. The value is specified in glyph space units.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the italic angle of a font.

    Declaration

    Swift

    func CGFontGetItalicAngle(_ font: CGFont!) -> CGFloat

    Objective-C

    CGFloat CGFontGetItalicAngle ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The italic angle of the font, measured in degrees counter-clockwise from the vertical.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the thickness of the dominant vertical stems of glyphs in a font.

    Declaration

    Swift

    func CGFontGetStemV(_ font: CGFont!) -> CGFloat

    Objective-C

    CGFloat CGFontGetStemV ( CGFontRef font );

    Parameters

    font

    A font object.

    Return Value

    The thickness of the dominant vertical stems of glyphs in a font.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Get the bounding box of each glyph in an array.

    Declaration

    Swift

    func CGFontGetGlyphBBoxes(_ font: CGFont!, _ glyphs: UnsafePointer<CGGlyph>, _ count: UInt, _ bboxes: UnsafeMutablePointer<CGRect>) -> Bool

    Objective-C

    bool CGFontGetGlyphBBoxes ( CGFontRef font, const CGGlyph glyphs[], size_t count, CGRect bboxes[] );

    Parameters

    font

    A font object.

    glyphs

    A array of glyphs.

    count

    The number of items in the glyphs array.

    bboxes

    On return, the bounding boxes for each glyph.

    Return Value

    false if bounding boxes can't be retrieved for any reason; true otherwise.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the glyph for the glyph name associated with the specified font object.

    Declaration

    Swift

    func CGFontGetGlyphWithGlyphName(_ font: CGFont!, _ name: CFString!) -> CGGlyph

    Objective-C

    CGGlyph CGFontGetGlyphWithGlyphName ( CGFontRef font, CFStringRef name );

    Parameters

    font

    A font object.

    name

    The name of the desired glyph.

    Return Value

    The named glyph, or 0 if the named glyph isn’t associated with the font.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the glyph name of the specified glyph in the specified font.

    Declaration

    Swift

    func CGFontCopyGlyphNameForGlyph(_ font: CGFont!, _ glyph: CGGlyph) -> CFString!

    Objective-C

    CFStringRef CGFontCopyGlyphNameForGlyph ( CGFontRef font, CGGlyph glyph );

    Parameters

    font

    A font object.

    glyph

    The glyph whose name is desired.

    Return Value

    The name of the specified glyph, or NULL if the glyph isn’t associated with the font object.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the number of glyphs in a font.

    Declaration

    Swift

    func CGFontGetNumberOfGlyphs(_ font: CGFont!) -> UInt

    Objective-C

    size_t CGFontGetNumberOfGlyphs ( CGFontRef font );

    Parameters

    font

    A CGFont object.

    Return Value

    The number of glyphs in the provided font.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Gets the advance width of each glyph in the provided array.

    Declaration

    Swift

    func CGFontGetGlyphAdvances(_ font: CGFont!, _ glyphs: UnsafePointer<CGGlyph>, _ count: UInt, _ advances: UnsafeMutablePointer<Int32>) -> Bool

    Objective-C

    bool CGFontGetGlyphAdvances ( CGFontRef font, const CGGlyph glyphs[], size_t count, int advances[] );

    Parameters

    font

    The font object associated with the provided glyphs.

    glyphs

    An array of glyphs.

    count

    The number of glyphs in the array.

    advances

    On output, an array of of advance widths for the provided glyphs.

    Return Value

    TRUE unless the advance widths can’t be provided for some reason.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the number of glyph space units per em for the provided font.

    Declaration

    Swift

    func CGFontGetUnitsPerEm(_ font: CGFont!) -> Int32

    Objective-C

    int CGFontGetUnitsPerEm ( CGFontRef font );

    Parameters

    font

    A CGFont object.

    Return Value

    The number of glyph space units per em for the provided font.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Data Types

  • An opaque type that encapsulates font information.

    Declaration

    Swift

    typealias CGFontRef = CGFont

    Objective-C

    typedef struct CGFont *CGFontRef;

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • An index into a font table.

    Declaration

    Swift

    typealias CGFontIndex = UInt16

    Objective-C

    typedef unsigned short CGFontIndex;

    Discussion

    This integer type provides an additional way to specify a glyph identifier. CGFontIndex is equivalent to CGGlyph, and you can use constants of either type interchangeably.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • An index into the internal glyph table of a font.

    Declaration

    Swift

    typealias CGGlyph = CGFontIndex

    Objective-C

    typedef unsigned short CGGlyph;

    Discussion

    When drawing text, you typically specify a sequence of characters. However, Quartz also allows you to use CGGlyph values to specify glyphs. In either case, Quartz renders the text using font data provided by the Apple Type Services (ATS) framework.

    You provide CGGlyph values to the functions CGContextShowGlyphs and CGContextShowGlyphsAtPoint. These functions display an array of glyphs at the current text position or at a position you specify, respectively.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Constants

  • Possible formats for a PostScript font subset.

    Declaration

    Swift

    struct CGFontPostScriptFormat { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    enum CGFontPostScriptFormat { kCGFontPostScriptFormatType1 = 1, kCGFontPostScriptFormatType3 = 3, kCGFontPostScriptFormatType42 = 42 }; typedef enum CGFontPostScriptFormat CGFontPostScriptFormat;

    Constants

    • kCGFontPostScriptFormatType1

      kCGFontPostScriptFormatType1

      This is documented in Adobe Type 1 Font Format, which is available from http://partners.adobe.com/.

      Available in iOS 2.0 and later.

    • kCGFontPostScriptFormatType3

      kCGFontPostScriptFormatType3

      This is documented in PostScript Language Reference, 3rd edition, which is available from http://partners.adobe.com/.

      Available in iOS 2.0 and later.

    • kCGFontPostScriptFormatType42

      kCGFontPostScriptFormatType42

      This is documented in Adobe Technical Note 5012, The Type 42 Font Format Specification, which is available from http://partners.adobe.com/.

      Available in iOS 2.0 and later.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Possible values for an index into a font table.

    Declaration

    Swift

    var kCGFontIndexMax: Int { get } var kCGFontIndexInvalid: Int { get } var kCGGlyphMax: Int { get }

    Objective-C

    enum { kCGFontIndexMax = ((1 << 16) - 2), kCGFontIndexInvalid = ((1 << 16) - 1), kCGGlyphMax = kCGFontIndexMax };

    Constants

    • kCGFontIndexMax

      kCGFontIndexMax

      The maximum allowed value for CGFontIndex.

      Available in iOS 2.0 and later.

    • kCGFontIndexInvalid

      kCGFontIndexInvalid

      An invalid font index (a value which never represents a valid glyph).

      Available in iOS 2.0 and later.

    • kCGGlyphMax

      kCGGlyphMax

      The same as kCGFontIndexMax.

      Available in iOS 2.0 and later.

    Discussion

    See CGFontIndex.

    Import Statement

  • Deprecated values for an index into a font table.

    Use kCGGlyphMax instead.

    Declaration

    Objective-C

    enum { CGGlyphMin = 0, CGGlyphMax = kCGGlyphMax };

    Constants

    • CGGlyphMin

      CGGlyphMin

      Minimum font index value.

      Available in iOS 2.0 and later.

      Deprecated in iOS 7.0.

    • CGGlyphMax

      CGGlyphMax

      Maximum font index value.

      Available in iOS 2.0 and later.

      Deprecated in iOS 7.0.

    Import Statement

  • Keys used for a font variation axis dictionary.

    Declaration

    Swift

    let kCGFontVariationAxisName: CFString! let kCGFontVariationAxisMinValue: CFString! let kCGFontVariationAxisMaxValue: CFString! let kCGFontVariationAxisDefaultValue: CFString!

    Objective-C

    const CFStringRef kCGFontVariationAxisName const CFStringRef kCGFontVariationAxisMinValue const CFStringRef kCGFontVariationAxisMaxValue const CFStringRef kCGFontVariationAxisDefaultValue

    Constants

    • kCGFontVariationAxisName

      kCGFontVariationAxisName

      The key used to obtain the variation axis name from a variation axis dictionary. The value obtained with this key is a CFStringRef that specifies the name of the variation axis.

      Available in iOS 2.0 and later.

    • kCGFontVariationAxisMinValue

      kCGFontVariationAxisMinValue

      The key used to obtain the minimum variation axis value from a variation axis dictionary. The value obtained with this key is a CFNumberRef that specifies the minimum value of the variation axis.

      Available in iOS 2.0 and later.

    • kCGFontVariationAxisMaxValue

      kCGFontVariationAxisMaxValue

      The key used to obtain the maximum variation axis value from a variation axis dictionary. The value obtained with this key is a CFNumberRef that specifies the maximum value of the variation axis.

      Available in iOS 2.0 and later.

    • kCGFontVariationAxisDefaultValue

      kCGFontVariationAxisDefaultValue

      The key used to obtain the default variation axis value from a variation axis dictionary. The value obtained with this key is a CFNumberRef that specifies the default value of the variation axis.

      Available in iOS 2.0 and later.

    Import Statement