Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

NSFont Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSFont.h

Overview

NSFont objects represent fonts to an application, providing access to characteristics of the font and assistance in laying out glyphs relative to one another. Font objects are also used to establish the current font when drawing in an NSView, using the set method.

You don’t create NSFont objects using the alloc and init methods. Instead, you use either fontWithDescriptor:size: or fontWithName:size: to look up an available font and alter its size or matrix to your needs. These methods check for an existing font object with the specified characteristics, returning it if there is one. Otherwise, they look up the font data requested and create the appropriate object. NSFont also defines a number of methods for getting standard system fonts, such as systemFontOfSize:, userFontOfSize:, and messageFontOfSize:. To request the default size for these standard fonts, pass a negative number or 0 as the font size.

Adopted Protocols

NSCoding
NSCopying

Tasks

Creating Arbitrary Fonts

Creating User Fonts

Creating System Fonts

Using a Font to Draw

Getting General Font Information

Getting Information About Glyphs

Getting Metrics Information

Getting Font Names

Setting User Fonts

Getting Corresponding Device Fonts

Deprecated Methods

Class Methods

boldSystemFontOfSize:

Returns the Aqua system font used for standard interface items that are rendered in boldface type in the specified size.

+ (NSFont *)boldSystemFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the boldface system font at the default size.

Availability
See Also
Declared In
NSFont.h

controlContentFontOfSize:

Returns the font used for the content of controls in the specified size.

+ (NSFont *)controlContentFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

For example, in a table, the user’s input uses the control content font, and the table’s header uses another font. If fontSize is 0 or negative, returns the control content font at the default size.

Availability
See Also
Declared In
NSFont.h

fontWithDescriptor:size:

Returns a font object for the specified font descriptor and font size.

+ (NSFont *)fontWithDescriptor:(NSFontDescriptor *)fontDescriptor size:(CGFloat)fontSize

Parameters
fontDescriptor

A font descriptor object.

fontSize

The size in points to which the font is scaled.

Return Value

A font object for the specified descriptor and size.

Discussion

In most cases, you can simply use fontWithName:size: to create standard scaled fonts.

Availability
See Also
Declared In
NSFont.h

fontWithDescriptor:textTransform:

Returns a font object for the specified font descriptor and text transform.

+ (NSFont *)fontWithDescriptor:(NSFontDescriptor *)fontDescriptor textTransform:(NSAffineTransform *)textTransform

Parameters
fontDescriptor

The font descriptor object describing the font to return.

textTransform

An affine transformation applied to the font.

Return Value

A font object for the specified name and transform.

Discussion

In most cases, you can simply use fontWithName:size: to create standard scaled fonts. If textTransform is non-nil, it has precedence over NSFontMatrixAttribute in fontDescriptor.

Availability
See Also
Declared In
NSFont.h

fontWithName:matrix:

Returns a font object for the specified font name and matrix.

+ (NSFont *)fontWithName:(NSString *)fontName matrix:(const CGFloat *)fontMatrix

Parameters
fontName

The fully specified family-face name of the font.

fontMatrix

A transformation matrix applied to the font.

Return Value

A font object for the specified name and transformation matrix.

Discussion

The fontName is a fully specified family-face name, such as Helvetica-BoldOblique or Times-Roman (not a name as shown in the Font Panel). The fontMatrix is a standard 6-element transformation matrix as used in the PostScript language, specifically with the makefont operator. In most cases, you can simply use fontWithName:size: to create standard scaled fonts.

You can use the defined value NSFontIdentityMatrix for [1 0 0 1 0 0]. Fonts created with a matrix other than NSFontIdentityMatrix don’t automatically flip themselves in flipped views.

Availability
See Also
Declared In
NSFont.h

fontWithName:size:

Creates a font object for the specified font name and font size.

+ (NSFont *)fontWithName:(NSString *)fontName size:(CGFloat)fontSize

Parameters
fontName

The fully specified family-face name of the font.

fontSize

The size in points to which the font is scaled.

Return Value

A font object for the specified name and size.

Discussion

The fontName is a fully specified family-face name, such as Helvetica-BoldOblique or Times-Roman. The fontSize is equivalent to using a font matrix of [fontSize 0 0 fontSize 0 0] with fontWithDescriptor:size:. If you use a fontSize of 0.0, this method uses the default User Font size.

Fonts created with this method automatically flip themselves in flipped views. This method is the preferred means for creating fonts.

Availability
Declared In
NSFont.h

labelFontOfSize:

Returns the Aqua font used for standard interface labels in the specified size.

+ (NSFont *)labelFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the label font with the default size.

Availability
Declared In
NSFont.h

labelFontSize

Returns the size of the standard label font.

+ (CGFloat)labelFontSize

Return Value

The label font size in points.

Availability
Declared In
NSFont.h

menuBarFontOfSize:

Returns the font used for menu bar items, in the specified size.

+ (NSFont *)menuBarFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the menu bar font with the default size.

Availability
See Also
Declared In
NSFont.h

menuFontOfSize:

Returns the font used for menu items, in the specified size.

+ (NSFont *)menuFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the menu items font with the default size.

Availability
See Also
Declared In
NSFont.h

messageFontOfSize:

Returns the font used for standard interface items, such as button labels, menu items, and so on, in the specified size.

+ (NSFont *)messageFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns this font at the default size. This method is equivalent to systemFontOfSize:.

Availability
See Also
Declared In
NSFont.h

paletteFontOfSize:

Returns the font used for palette window title bars, in the specified size.

+ (NSFont *)paletteFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the palette title font at the default size.

Availability
See Also
Declared In
NSFont.h

setUserFixedPitchFont:

Sets the font used by default for documents and other text under the user’s control, when that font should be fixed-pitch, to the specified font.

+ (void)setUserFixedPitchFont:(NSFont *)aFont

Discussion

Specifying aFont as nil causes the default to be removed from the application domain.

Availability
See Also
Declared In
NSFont.h

setUserFont:

Sets the font used by default for documents and other text under the user’s control to the specified font.

+ (void)setUserFont:(NSFont *)aFont

Discussion

Specifying aFont as nil causes the default to be removed from the application domain.

Availability
See Also
Declared In
NSFont.h

smallSystemFontSize

Returns the size of the standard small system font.

+ (CGFloat)smallSystemFontSize

Return Value

The small system font size in points.

Availability
Declared In
NSFont.h

systemFontOfSize:

Returns the Aqua system font used for standard interface items, such as button labels, menu items, and so on, in the specified size.

+ (NSFont *)systemFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the system font at the default size.

Availability
See Also
Declared In
NSFont.h

systemFontSize

Returns the size of the standard system font.

+ (CGFloat)systemFontSize

Return Value

The standard system font size in points.

Availability
Declared In
NSFont.h

systemFontSizeForControlSize:

Returns the font size used for the specified control size.

+ (CGFloat)systemFontSizeForControlSize:(NSControlSize)controlSize

Parameters
controlSize

The control size constant.

Return Value

The font size in points for the specified control size.

Discussion

If controlSize does not correspond to a valid NSControlSize, returns the size of the standard system font.

Availability
Declared In
NSFont.h

titleBarFontOfSize:

Returns the font used for window title bars, in the specified size.

+ (NSFont *)titleBarFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the title bar font at the default size. This method is equivalent to boldSystemFontOfSize:.

Availability
See Also
Declared In
NSFont.h

toolTipsFontOfSize:

Returns the font used for tool tips labels, in the specified size.

+ (NSFont *)toolTipsFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the tool tips font at the default size.

Availability
See Also
Declared In
NSFont.h

userFixedPitchFontOfSize:

Returns the font used by default for documents and other text under the user’s control (that is, text whose font the user can normally change), when that font should be fixed-pitch, in the specified size.

+ (NSFont *)userFixedPitchFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the fixed-pitch font at the default size.

The system does not guarantee that all the glyphs in a fixed-pitch font are the same width. For example, certain Japanese fonts are dual-pitch, and other fonts may have nonspacing marks that can affect the display of other glyphs.

Availability
See Also
Declared In
NSFont.h

userFontOfSize:

Returns the font used by default for documents and other text under the user’s control (that is, text whose font the user can normally change), in the specified size.

+ (NSFont *)userFontOfSize:(CGFloat)fontSize

Parameters
fontSize

The size in points to which the font is scaled.

Return Value

A font object of the specified size.

Discussion

If fontSize is 0 or negative, returns the user font at the default size.

Availability
See Also
Declared In
NSFont.h

Instance Methods

advancementForGlyph:

Returns the nominal spacing for the given glyph—the distance the current point moves after showing the glyph—accounting for the receiver’s size.

- (NSSize)advancementForGlyph:(NSGlyph)aGlyph

Parameters
aGlyph

The glyph whose advancement is returned.

Return Value

The advancement spacing in points.

Discussion

This spacing is given according to the glyph’s movement direction, which is either strictly horizontal or strictly vertical.

Availability
See Also
Declared In
NSFont.h

ascender

Returns the top y-coordinate, offset from the baseline, of the receiver’s longest ascender.

- (CGFloat)ascender

Return Value

The distance of the longest ascender’s top y-coordinate from the baseline in points.

Availability
See Also
Declared In
NSFont.h

boundingRectForFont

Returns the receiver’s bounding rectangle, scaled to the font’s size.

- (NSRect)boundingRectForFont

Discussion

The bounding rectangle is the union of the bounding rectangles of every glyph in the font.

Availability
See Also
Declared In
NSFont.h

boundingRectForGlyph:

Returns the bounding rectangle for the specified glyph, scaled to the receiver’s size.

- (NSRect)boundingRectForGlyph:(NSGlyph)aGlyph

Discussion

Japanese fonts encoded with the scheme “EUC12-NJE-CFEncoding” do not have individual metrics or bounding boxes available for the glyphs above 127. For those glyphs, this method returns the bounding rectangle for the font instead.

Availability
See Also
Declared In
NSFont.h

capHeight

Returns the receiver’s cap height.

- (CGFloat)capHeight

Availability
See Also
Declared In
NSFont.h

coveredCharacterSet

Returns an NSCharacterSet object containing all of the nominal characters renderable by the receiver, which is all of the entries mapped in the receiver’s ‘cmap’ table.

- (NSCharacterSet *)coveredCharacterSet

Return Value

An NSCharacterSet object containing all of the nominal characters renderable by the receiver.

Discussion

The number of glyphs supported by a given font is often larger than the number of characters contained in the character set returned by this method.

Availability
Declared In
NSFont.h

descender

Returns the bottom y coordinate, offset from the baseline, of the receiver’s longest descender.

- (CGFloat)descender

Discussion

Thus, if the longest descender extends 2 points below the baseline, descender will return –2.

Availability
Declared In
NSFont.h

displayName

Returns the name, including family and face, used to represent the font in the user interface, typically localized for the user’s language.

- (NSString *)displayName

Availability
Declared In
NSFont.h

familyName

Returns the receiver’s family name—for example, “Times” or “Helvetica.”

- (NSString *)familyName

Discussion

This name is the one that NSFontManager uses and may differ slightly from the AFM name.

The value returned by this method is intended for an application’s internal usage and not for display. Use displayName instead.

Availability
See Also
Declared In
NSFont.h

fontDescriptor

Returns the receiver’s font descriptor.

- (NSFontDescriptor *)fontDescriptor

Return Value

A font descriptor object that describes the receiver.

Discussion

The font descriptor contains a mutable dictionary of optional attributes for creating an NSFont object. See documentation on NSFontDescriptor for more information.

Availability
Declared In
NSFont.h

fontName

Returns the receiver’s full font name, as used in PostScript language code—for example, “Times-Roman” or “Helvetica-Oblique.”

- (NSString *)fontName

Discussion

The value returned by this method is intended for an application’s internal usage and not for display. Use displayName instead.

Availability
See Also
Declared In
NSFont.h

getAdvancements:forGlyphs:count:

Returns an array of the advancements for the specified glyphs rendered by the receiver.

- (void)getAdvancements:(NSSizeArray)advancements forGlyphs:(const NSGlyph *)glyphs count:(NSUInteger)glyphCount

Discussion

Returns in advancements an array of the advancements for the glyphs specified by glyphs and rendered by the receiver. The glyphCount must specify the count of glyphs passed in glyphs.

Availability
See Also
Declared In
NSFont.h

getAdvancements:forPackedGlyphs:length:

Returns an array of the advancements for the specified packed glyphs and rendered by the receiver.

- (void)getAdvancements:(NSSizeArray)advancements forPackedGlyphs:(const void *)packedGlyphs length:(NSUInteger)length- (void)getAdvancements

Discussion

Returns in advancements an array of the advancements for the packed glyphs specified by packedGlyphs and rendered by the receiver. The glyphCount must specify the count of glyphs passed in packedGlyphs.

Availability
See Also
Declared In
NSFont.h

getBoundingRects:forGlyphs:count:

Returns an array of the bounding rectangles for the specified glyphs rendered by the receiver.

- (void)getBoundingRects:(NSRectArray)bounds forGlyphs:(const NSGlyph *)glyphs count:(NSUInteger)glyphCount

Discussion

Returns in bounds an array of the bounding rectangles for the glyphs specified by glyphs and rendered by the receiver. The glyphCount must specify the count of glyphs passed in glyphs.

Availability
See Also
Declared In
NSFont.h

glyphWithName:

Returns the named encoded glyph, or –1 if the receiver contains no such glyph.

- (NSGlyph)glyphWithName:(NSString *)glyphName

Parameters
glyphName

The name of the glyph.

Return Value

The named encoded glyph.

Discussion

Returns –1 if the glyph named glyphName isn’t encoded.

Glyph names in fonts do not always accurately identify the glyph. If possible, look up the appropriate glyph on your own.

Availability
Declared In
NSFont.h

isFixedPitch

Returns a Boolean value indicating whether all glyphs in the receiver have the same advancement.

- (BOOL)isFixedPitch

Return Value

YES if all glyphs in the receiver have the same advancement; NO if any advancements differ.

Discussion

Some Japanese fonts encoded with the scheme “EUC12-NJE-CFEncoding” return that they have the same advancement, but actually encode glyphs with one of two advancements, for historical compatibility. You may need to handle such fonts specially for some applications.

Availability
See Also
Declared In
NSFont.h

italicAngle

Returns the receiver’s italic angle, the amount that the font is slanted in degrees counterclockwise from the vertical, as read from its AFM file. Because the slant is measured counterclockwise, English italic fonts typically return a negative value.

- (CGFloat)italicAngle

Availability
Declared In
NSFont.h

leading

Returns the receiver’s leading.

- (CGFloat)leading

Availability
See Also
Declared In
NSFont.h

matrix

Returns the receiver’s font matrix, a standard six-element transformation matrix as used in the PostScript language, specifically with the makefont operator.

- (const CGFloat *)matrix

Discussion

In most cases, with a font of fontSize, this matrix is [fontSize 0 0 fontSize 0 0].

Availability
See Also
Declared In
NSFont.h

maximumAdvancement

Returns the greatest advancement of any of the receiver’s glyphs.

- (NSSize)maximumAdvancement

Discussion

This advancement is always either strictly horizontal or strictly vertical.

Availability
See Also
Declared In
NSFont.h

mostCompatibleStringEncoding

Returns the string encoding that works best with the receiver, where there are the fewest possible unmatched characters in the string encoding and glyphs in the font.

- (NSStringEncoding)mostCompatibleStringEncoding

Return Value

The string encoding that works best with the receiver.

Discussion

You can use NSString‘s dataUsingEncoding: or dataUsingEncoding:allowLossyConversion: method to convert the string to this encoding.

If this method returns NSASCIIStringEncoding, it could not determine the correct encoding and assumed that the font can render only ASCII characters.

This method works heuristically using well-known font encodings, so for nonstandard encodings it may not in fact return the optimal string encoding.

Availability
Declared In
NSFont.h

numberOfGlyphs

Returns the number of glyphs in the receiver.

- (NSUInteger)numberOfGlyphs

Discussion

Glyphs are numbered starting at 0.

Availability
Declared In
NSFont.h

pointSize

Returns the receiver’s point size, or the effective vertical point size for a font with a nonstandard matrix.

- (CGFloat)pointSize

Availability
Declared In
NSFont.h

printerFont

Returns the scalable PostScript font corresponding to itself.

- (NSFont *)printerFont

Discussion

When sent to a font object representing a scalable PostScript font, returns self. When sent to a font object representing a bitmapped screen font, returns its corresponding scalable PostScript font.

Availability
See Also
Declared In
NSFont.h

renderingMode

Returns the rendering mode of the receiver.

- (NSFontRenderingMode)renderingMode

Return Value

The rendering mode of the receiver.

Discussion

For valid rendering modes, see “Constants.”

Availability
See Also
Declared In
NSFont.h

screenFont

Returns the bitmapped screen font corresponding to itself.

- (NSFont *)screenFont

Discussion

When sent to a font object representing a scalable PostScript font, returns a bitmapped screen font matching the receiver in typeface and matrix (or size), or nil if such a font can’t be found. When sent to a font object representing a bitmapped screen font, returns nil.

Screen fonts are for direct use with the window server only. Never use them with Application Kit objects, such as in setFont: methods. Internally, the Application Kit automatically uses the corresponding screen font for a font object as long as the view is not rotated or scaled.

Availability
See Also
Declared In
NSFont.h

screenFontWithRenderingMode:

Returns a bitmapped screen font, when sent to a font object representing a scalable PostScript font, with the specified rendering mode, matching the receiver in typeface and matrix (or size), or nil if such a font can’t be found.

- (NSFont *)screenFontWithRenderingMode:(NSFontRenderingMode)renderingMode

Discussion

For valid rendering modes, see NSFontRenderingMode.

Screen fonts are for direct use with the window server only. Never use them with Application Kit objects, such as in setFont: methods. Internally, the Application Kit automatically uses the corresponding screen font for a font object as long as the view is not rotated or scaled.

Availability
See Also
Declared In
NSFont.h

set

Establishes the receiver as the current font for PostScript show and other text-drawing operators.

- (void)set

Discussion

During a print operation, also records the font as used in the PostScript code emitted.

Availability
See Also
Declared In
NSFont.h

setInContext:

Establishes the receiver as the current font for the specified graphics context.

- (void)setInContext:(NSGraphicsContext *)graphicsContext

Parameters
graphicsContext

The graphics context for which the font is set.

Availability
See Also
Declared In
NSFont.h

textTransform

Returns the current transformation matrix for the receiver.

- (NSAffineTransform *)textTransform

Availability
See Also
Declared In
NSFont.h

underlinePosition

Returns the baseline offset that should be used when drawing underlines with the receiver, as determined by the font’s AFM file.

- (CGFloat)underlinePosition

Discussion

This value is usually negative, which must be considered when drawing in a flipped coordinate system.

Availability
See Also
Declared In
NSFont.h

underlineThickness

Returns the thickness that should be used when drawing underlines with the receiver, as determined by the font’s AFM file.

- (CGFloat)underlineThickness

Availability
See Also
Declared In
NSFont.h

xHeight

Returns the x-height of the