Next Page >

Hide TOC

CGFont Reference

Derived from	CFType
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 “ﬁ” 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 Mac 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 Mac OS X version 10.5 and later.

Declared In

CGFont.h

CGFontCopyGlyphNameForGlyph

Returns the glyph name associated with a font object.

CFStringRef CGFontCopyGlyphNameForGlyph (
   CGFontRef font
);

Parameters

font: A font object.

Return Value

A glyph name, or NULL if there isn’t a glyph associated with the font object.

Availability

Available in Mac OS X version 10.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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X version 10.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 Mac OS X version 10.5 and later.

Declared In

CGFont.h

CGFontCreateWithPlatformFont

Creates a font object from an Apple Type Services (ATS) font.

CGFontRef CGFontCreateWithPlatformFont (
   void *platformFontReference
);

Parameters

platformFontReference: A generic pointer to a font object. The font should be of a type appropriate to the platform on which your program is running. For Mac OS X, you should pass a pointer to an ATS font.

Return Value

The font object, or NULL if the platform font could not be located. 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. For ATS Fonts, call this function to create a Quartz font, and pass it to CGContextSetFont.

Availability

Available in Mac OS X version 10.0 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 Mac OS X version 10.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 Mac OS X version 10.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 Mac OS X version 10.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 Mac OS X version 10.5 and later.

Declared In

CGFont.h

CGFontGetGlyphAdvances

Gets the bound box 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 advances for the provided glyphs.

Return Value

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

Availability

Available in Mac 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 Mac OS X version 10.5 and later.

Declared In

CGFont.h

CGFontGetGlyphWithGlyphName

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

CGGlyph CGFontGetGlyphWithGlyphName (
   CGFontRef font
);

Parameters

font: A font object.

Return Value

A glyph, or 0 if there isn’t a name associated with the font object.

Availability

Available in Mac OS X version 10.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 Mac OS X version 10.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 Mac OS X version 10.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 Mac 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 Mac OS X version 10.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 Mac OS X version 10.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 Mac 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 Mac OS X version 10.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 Mac OS X version 10.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 Mac OS X version 10.0 and later.

Declared In

CGFont.h

Data Types

CGFontRef

An opaque type that encapsulates font information.

typedef struct CGFont *CGFontRef;

Availability

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

Declared in CGFont.h.

Availability

Available in Mac 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 Mac 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 Mac OS X v10.1 and later.

Declared in CGFont.h.

kCGGlyphMax

The same as kCGFontIndexMax.

Available in Mac OS X v10.1 and later.

Declared in CGFont.h.

Discussion

See CGFontIndex.

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

Declared in CGFont.h.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGFont.h

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.