CGFont Reference

Derived from
CFType Reference
Framework
ApplicationServices/ApplicationServices.h
Companion guide
Quartz 2D Programming Guide
Declared in
CGFont.h

Overview

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 by Task

Retaining and Releasing a CGFont Object

Creating a CGFont Object

Working With PostScript Fonts

Working With Font Tables

Getting Font Information

Functions

CGFontCanCreatePostScriptSubset

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

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

Availability
  • Available in OS X v10.4 and later.
Declared In
CGFont.h

CGFontCopyFullName

Returns the full name associated with a font object.

CFStringRef CGFontCopyFullName (
   CGFontRef font
);
Parameters
font

A font object.

Return Value

The full name associated with the font.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGFont.h

CGFontCopyGlyphNameForGlyph

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

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontCopyPostScriptName

Obtains the PostScript name of a font.

CFStringRef CGFontCopyPostScriptName (
   CGFontRef font
);
Parameters
font

A font object.

Return Value

The PostScript name of the font.

Discussion

Availability
  • Available in OS X v10.4 and later.
Declared In
CGFont.h

CGFontCopyTableForTag

Returns the font table that corresponds to the provided tag.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontCopyTableTags

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

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);
Availability
  • Available in OS X v10.5 and later.
Declared In
CGFont.h

CGFontCopyVariationAxes

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

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 OS X v10.4 and later.
Declared In
CGFont.h

CGFontCopyVariations

Returns the variation specification dictionary for a font. 

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 OS X v10.4 and later.
Declared In
CGFont.h

CGFontCreateCopyWithVariations

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

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 OS X v10.4 and later.
Declared In
CGFont.h

CGFontCreatePostScriptEncoding

Creates a PostScript encoding of a font.

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

Availability
  • Available in OS X v10.4 and later.
Declared In
CGFont.h

CGFontCreatePostScriptSubset

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

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

Availability
  • Available in OS X v10.4 and later.
Declared In
CGFont.h

CGFontCreateWithDataProvider

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

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontCreateWithFontName

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

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetAscent

Returns the ascent of a font.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetCapHeight

Returns the cap height of a font.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetDescent

Returns the descent of a font.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetFontBBox

Returns the bounding box of a font.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetGlyphAdvances

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

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetGlyphBBoxes

Get the bounding box of each glyph in an array.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetGlyphWithGlyphName

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

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetItalicAngle

Returns the italic angle of a font.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetLeading

Returns the leading of a font.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetNumberOfGlyphs

Returns the number of glyphs in a font.

size_t CGFontGetNumberOfGlyphs (
   CGFontRef font
);
Parameters
font

A CGFont object.

Return Value

The number of glyphs in the provided font.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetStemV

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

CGFloat CGFontGetItalicAngle (
   CGFontRef font
);
Parameters
font

A font object.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetTypeID

Returns the Core Foundation type identifier for Quartz fonts.

CFTypeID CGFontGetTypeID (
   void
);
Return Value

The Core Foundation identifier for the opaque type CGFontRef.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGFont.h

CGFontGetUnitsPerEm

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

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontGetXHeight

Returns the x-height of a font.

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 OS X v10.5 and later.
Declared In
CGFont.h

CGFontRelease

Decrements the retain count of a Quartz font.

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 OS X v10.0 and later.
Declared In
CGFont.h

CGFontRetain

Increments the retain count of a Quartz font.

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 OS X v10.0 and later.
Declared In
CGFont.h

Data Types

CGFontRef

An opaque type that encapsulates font information.

typedef struct CGFont *CGFontRef;
Availability
  • Available in OS X v10.0 and later.
Declared In
CGFont.h

CGFontIndex

An index into a font table.

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.

Availability
  • Available in OS X version 10.2 and later.
Declared In
CGFont.h

CGGlyph

An index into the internal glyph table of a font.

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGFont.h

Constants

CGFontPostScriptFormat

Possible formats for a PostScript font subset.

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

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

Available in OS X v10.4 and later.

Declared in CGFont.h.

kCGFontPostScriptFormatType3

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

Available in OS X v10.4 and later.

Declared in CGFont.h.

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 OS X v10.4 and later.

Declared in CGFont.h.

Font Table Index Values

Possible values for an index into a font table.

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

The maximum allowed value for CGFontIndex.

Available in OS X v10.1 and later.

Declared in CGFont.h.

kCGFontIndexInvalid

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

Available in OS X v10.1 and later.

Declared in CGFont.h.

kCGGlyphMax

The same as kCGFontIndexMax.

Available in OS X v10.1 and later.

Declared in CGFont.h.

Discussion

See CGFontIndex.

Obsolete Font Table Index Values

Deprecated values for an index into a font table. (Deprecated. Use kCGGlyphMax instead.)

enum {
   CGGlyphMin = 0,
   CGGlyphMax = kCGGlyphMax
};
Constants
CGGlyphMin

Minimum font index value.

Available in OS X v10.0 and later.

Declared in CGFont.h.

CGGlyphMax

Maximum font index value.

Available in OS X v10.0 and later.

Declared in CGFont.h.

Font Variation Axis Keys

Keys used for a font variation axis dictionary.

const CFStringRef kCGFontVariationAxisName
const CFStringRef kCGFontVariationAxisMinValue
const CFStringRef kCGFontVariationAxisMaxValue
const CFStringRef kCGFontVariationAxisDefaultValue
Constants
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 OS X v10.4 and later.

Declared in CGFont.h.

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 OS X v10.4 and later.

Declared in CGFont.h.

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 OS X v10.4 and later.

Declared in CGFont.h.

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 OS X v10.4 and later.

Declared in CGFont.h.



© 2003, 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-05-13)

Did this document help you? Yes It's good, but... Not helpful...