iOS Developer Library

Developer

Core Text Reference Collection 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.

    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.

    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.

    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.

    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.

    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:

    1. tag = (uint32_t)(uintptr_t)CFArrayGetValue(table, k);

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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: Int, _ 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.

    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.

    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.

    Availability

    Available in iOS 2.0 and later.

  • Returns the number of glyphs in a font.

    Declaration

    Swift

    func CGFontGetNumberOfGlyphs(_ font: CGFont?) -> Int

    Objective-C

    size_t CGFontGetNumberOfGlyphs ( CGFontRef font );

    Parameters

    font

    A CGFont object.

    Return Value

    The number of glyphs in the provided font.

    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: Int, _ 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.

    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.

    Availability

    Available in iOS 2.0 and later.

Data Types

  • An opaque type that encapsulates font information.

    Declaration

    Swift

    class CGFont { }

    Objective-C

    typedef struct CGFont *CGFontRef;

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    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

    Objective-C

    @import CoreGraphics;

    Swift

    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

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Constants

  • Possible formats for a PostScript font subset.

    Declaration

    Swift

    enum CGFontPostScriptFormat : Int32 { case Type1 case Type3 case Type42 }

    Objective-C

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

    Constants

    • Type1

      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.

    • Type3

      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.

    • Type42

      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

    Objective-C

    @import CoreGraphics;

    Swift

    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 through iOS 8.4.

    • kCGFontIndexInvalid

      kCGFontIndexInvalid

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

      Available in iOS 2.0 through iOS 8.4.

    • kCGGlyphMax

      kCGGlyphMax

      The same as kCGFontIndexMax.

      Available in iOS 2.0 through iOS 8.4.

    Discussion

    See CGFontIndex.

  • Deprecated values for an index into a font table.

    Use kCGGlyphMax instead.

    Declaration

    Swift

    enum CGGlyphDeprecatedEnum : Int32 { case Min case Max }

    Objective-C

    enum { CGGlyphMin = 0, CGGlyphMax = kCGGlyphMax };

    Constants

    • Min

      CGGlyphMin

      Minimum font index value.

      Available in iOS 2.0 and later.

      Deprecated in iOS 7.0.

    • Max

      CGGlyphMax

      Maximum font index value.

      Available in iOS 2.0 and later.

      Deprecated in iOS 7.0.

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