---

NSFont

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 a constructor. Instead, you use fontWithNameAndSize 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.

Tasks

Constructors

• NSFont

Creating Arbitrary Fonts

• fontWithNameAndSize
• fontWithNameAndMatrix

Creating User Fonts

• userFontOfSize
• userFixedPitchFontOfSize

Creating System Fonts

• boldSystemFontOfSize
• controlContentFontOfSize
• labelFontOfSize
• menuFontOfSize
• menuBarFontOfSize
• messageFontOfSize
• paletteFontOfSize
• systemFontOfSize
• titleBarFontOfSize
• toolTipsFontOfSize

Getting Preferred Fonts

• setPreferredFontNames
• preferredFontNames

Using a Font to Draw

• set

Getting General Font Information

• coveredCharacterSet
• encodingScheme
• fontDescriptor
• isBaseFont
• isFixedPitch
• mostCompatibleStringEncoding

Getting Information About Glyphs

• glyphIsEncoded
• glyphPacking
• glyphWithName

Getting Metrics Information

• labelFontSize
• smallSystemFontSize
• systemFontSize
• systemFontSizeForControlSize
• advancementForGlyph
• afmDictionary
• afmFileContents
• ascender
• boundingRectForFont
• boundingRectForGlyph
• capHeight
• descender
• italicAngle
• maximumAdvancement
• numberOfGlyphs
• pointSize
• underlinePosition
• underlineThickness
• widthOfString
• xHeight

Getting Font Names

• displayName
• familyName
• fontName

Laying out Overstruck Glyphs

• positionOfGlyphForCharacterStruckOverRect

Setting User Fonts

• setUserFont
• setUserFixedPitchFont

Getting Corresponding Device Fonts

• printerFont
• screenFont

Deprecated Methods

• useFont

Static Methods

boldSystemFontOfSize

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

public static NSFont boldSystemFontOfSize(float fontSize)

Discussion

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

See Also

• fontWithNameAndSize

controlContentFontOfSize

Returns the font used for the content of controls, in fontSize.

public static NSFont controlContentFontOfSize(float fontSize)

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.

See Also

• fontWithNameAndSize

fontWithNameAndMatrix

Returns a font object for typeface and fontMatrix.

public static Object fontWithNameAndMatrix(String typeface, NSArray fontMatrix)

Discussion

typeface is a fully specified family-face name, such as Helvetica-BoldOblique or Times-Roman (not a name as shown in the Font Panel). 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 fontWithNameAndSize to create standard scaled fonts.

See Also

• isFlipped (NSView)

fontWithNameAndSize

Returns a font object for fontName and fontSize.

public static NSFont fontWithNameAndSize(String fontName, float fontSize)

Discussion

fontName is a fully specified family-face name, such as Helvetica-BoldOblique or Times-Roman. fontSize is used to scale the font. 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.

labelFontOfSize

Returns the Aqua font used for standard interface labels in fontSize.

public static NSFont labelFontOfSize(float fontSize)

Discussion

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

labelFontSize

Returns the size of the standard label font.

public static float labelFontSize()

Availability

• Available in Mac OS X v10.3 and later.

menuBarFontOfSize

Returns the font used for menu bar items in fontSize.

public static NSFont menuBarFontOfSize(float fontSize)

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• fontWithNameAndSize

menuFontOfSize

Returns the font used for menu items in fontSize.

public static NSFont menuFontOfSize(float fontSize)

Discussion

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

See Also

• fontWithNameAndSize

messageFontOfSize

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

public static NSFont messageFontOfSize(float fontSize)

Discussion

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

See Also

• fontWithNameAndSize

paletteFontOfSize

Returns the font used for palette window title bars.

public static NSFont paletteFontOfSize(float fontSize)

Discussion

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

See Also

• fontWithNameAndSize
• titleBarFontOfSize

preferredFontNames

This method is deprecated. NSFontCascadeListAttribute offers more powerful font substitution management.

public static NSArray preferredFontNames()

Discussion

Returns the names of fonts that the Application Kit tries first when a character has no font specified or when the font specified doesn’t have a glyph for that character. If none of these fonts provides a glyph, the remaining fonts on the system are searched for a glyph.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.

See Also

• setPreferredFontNames

setPreferredFontNames

This method is deprecated.

public static void setPreferredFontNames(NSArray fontNames)

Discussion

Sets the list of preferred font names to fontNames and records them in the user defaults database for all applications. The Application Kit tries these fonts first when a character has no font specified or when the font specified doesn’t have a glyph for that character. If none of these fonts provides a glyph, the remaining fonts on the system are searched for a glyph.

This method is useful for optimizing glyph rendering for uncommon scripts, by guaranteeing that appropriate fonts are searched first. For example, suppose you have three hundred Latin alphabet fonts and one Cyrillic alphabet font. When you read a document in Russian, you want it to find the Cyrillic font quickly. Ordinarily, the Application Kit will search for the Cyrillic font among all 301 fonts. But if it is in the list of preferred fonts, the Cyrillic font will be one of the first searched.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.

See Also

• preferredFontNames

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

public static void setUserFixedPitchFont(NSFont aFont)

Discussion

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

See Also

• setUserFont
• userFixedPitchFontOfSize

setUserFont

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

public static void setUserFont(NSFont aFont)

Discussion

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

See Also

• setUserFixedPitchFont
• userFontOfSize

smallSystemFontSize

Returns the size of the standard small system font.

public static float smallSystemFontSize()

Availability

• Available in Mac OS X v10.3 and later.

systemFontOfSize

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

public static NSFont systemFontOfSize(float fontSize)

Discussion

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

See Also

• boldSystemFontOfSize
• userFontOfSize
• userFixedPitchFontOfSize
• fontWithNameAndSize

systemFontSize

Returns the size of the standard system font.

public static float systemFontSize()

Availability

• Available in Mac OS X v10.3 and later.

systemFontSizeForControlSize

Returns the font size used for controlSize. If

public static float systemFontSizeForControlSize(int controlSize)

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

titleBarFontOfSize

Returns the font used for window title bars, in fontSize.

public static NSFont titleBarFontOfSize(float fontSize)

Discussion

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

See Also

• paletteFontOfSize

toolTipsFontOfSize

Returns the font used for tool tips labels, in fontSize.

public static NSFont toolTipsFontOfSize(float fontSize)

Discussion

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

See Also

• fontWithNameAndSize

useFont

This method is deprecated. This is now automatically handled by Quartz.

public static void useFont(String fontName)

Discussion

Records fontName as one used in the current print operation.

The NSFont class object keeps track of the fonts used in an NSView by recording each one that receives a set message. When the view is called upon to generate conforming PostScript language output (such as during printing), the NSFont class provides the list of fonts required for the %%DocumentFonts comment, as required by Adobe’s document structuring conventions.

The useFont argument augments this system by providing a way to register fonts that are included in the document but not set using NSFont’s set method. For example, you might set a font by executing the setfont operator within a function created by the pswrap utility. In such a case, be sure to pair the use of the font with a useFont message to register the font for listing in the document comments.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.

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.

public static NSFont userFixedPitchFontOfSize(float fontSize)

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.

See Also

• userFontOfSize
• fontWithNameAndSize
• setUserFixedPitchFont

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

public static NSFont userFontOfSize(float fontSize)

Discussion

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

See Also

• userFixedPitchFontOfSize
• fontWithNameAndSize
• setUserFont

Instance Methods

advancementForGlyph

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

public NSSize advancementForGlyph(int aGlyph)

Discussion

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

See Also

• boundingRectForGlyph
• maximumAdvancement

afmDictionary

This method is deprecated.

public NSDictionary afmDictionary()

Discussion

It simply returns null.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.3.

See Also

• afmFileContents

afmFileContents

This method is deprecated.

public String afmFileContents()

Discussion

It simply returns null.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.3.

ascender

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

public float ascender()

See Also

• descender
• capHeight
• xHeight

boundingRectForFont

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

public NSRect boundingRectForFont()

Discussion

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

See Also

• boundingRectForGlyph

boundingRectForGlyph

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

public NSRect boundingRectForGlyph(int 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.

See Also

• boundingRectForFont,

capHeight

Returns the receiver’s cap height.

public float capHeight()

See Also

• ascender
• descender
• xHeight

coveredCharacterSet

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

public NSCharacterSet coveredCharacterSet()

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

• Available in Mac OS X v10.2 and later.

descender

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

public float descender()

Discussion

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

displayName

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

public String displayName()

encodingScheme

This method is deprecated.

public String encodingScheme()

Discussion

Returns the name of the receiver’s encoding scheme, such as “AdobeStandardEncoding,” “ISOLatin1Encoding,” “FontSpecific,” and so on.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.

familyName

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

public String 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.

See Also

• fontName

fontDescriptor

Returns the receiver’s font descriptor.

public NSFontDescriptor fontDescriptor()

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

fontName

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

public String fontName()

Discussion

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

See Also

• familyName

glyphIsEncoded

This method is deprecated. The value can be deduced by aGlyph < [NSFont numberOfGlyphs] since only NSNativeShortGlyphPacking is supported.

public boolean glyphIsEncoded(int aGlyph)

Discussion

Returns true if the receiver encodes aGlyph, false if it doesn’t contain it.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.

glyphPacking

This method is deprecated.

public int glyphPacking()

Discussion

Returns the best way to encode the receiver’s glyphs into an array of bytes. The return value is one of values described in “Constants.”

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.

glyphWithName

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

public int glyphWithName(String glyphName)

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.

isBaseFont

This method is deprecated.

public boolean isBaseFont()

Discussion

Returns true if the receiver is a PostScript base font, false if it’s a PostScript composite font composed of other base fonts.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.3.

isFixedPitch

Returns true if all glyphs in the receiver have the same advancement, false if any advancements differ.

public boolean isFixedPitch()

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.

See Also

• advancementForGlyph

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.

public float italicAngle()

maximumAdvancement

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

public NSSize maximumAdvancement()

Discussion

This advancement is always either strictly horizontal or strictly vertical.

See Also

• advancementForGlyph

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.

public int mostCompatibleStringEncoding()

Discussion

You can use NSStringReferences’s dataUsingEncoding method to convert the string to this encoding.

If this method returns NSStringReference.ASCIIStringEncoding, 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.

See Also

• widthOfString

numberOfGlyphs

Returns the number of glyphs in the receiver.

public int numberOfGlyphs()

Discussion

Glyphs are numbered starting at 0.

pointSize

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

public float pointSize()

positionOfGlyphForCharacterStruckOverRect

This method is deprecated. Context-sensitive inter-glyph spacing is now performed at the typesetting stage.

public NSPoint positionOfGlyphForCharacterStruckOverRect(int aGlyph, char aChar, NSRect aRect)

Discussion

Calculates and returns a suitable location for aGlyph to be drawn as a diacritic or nonspacing mark relative to aRect, assuming that aGlyph represents aChar. Returns NSPoint.ZeroPoint if the location can’t be calculated. The nature of aChar as one appearing above or below its base character determines the location returned. For example, in the first figure below, the gray tilde and box represent aGlyph and aRect, and the black dot is the point returned (defined relative to the origin of the aRect).

To place multiple glyphs with respect to a rectangle, work from the innermost glyphs to the outermost. As you calculate the position of each glyph, enlarge the rectangle to include the bounding rectangle of the glyph in preparation for the next glyph. The second figure shows a tilde, acute accent, and cedilla all placed in their appropriate positions with respect to a rectangle, with the acute accent placed relative to the expanded bounding box of the base rectangle and the tilde.

Availability

• Deprecated.
• Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.

printerFont

public NSFont printerFont()

Discussion

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

See Also

• screenFont

screenFont

public 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 null if such a font can’t be found. When sent to a font object representing a bitmapped screen font, returns null.

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.

See Also

• printerFont

set

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

public void set()

Discussion

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

See Also

• useFont

underlinePosition

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

public float underlinePosition()

Discussion

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

See Also

• underlineThickness

underlineThickness

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

public float underlineThickness()

See Also

• underlinePosition

widthOfString

Returns the x axis offset of the current point when aString is drawn with a PostScript show operator in the receiving font.

public float widthOfString(String aString)

Discussion

This method performs lossy conversion of aString to the most compatible encoding for the receiving font.

Use this method only when you’re sure all of aString can be rendered with the receiving font.

This method is for backward compatibility only.

See Also

• mostCompatibleStringEncoding

xHeight

Returns the x height of the receiver.

public float xHeight()

See Also

• ascender
• descender

Constants

Cocoa stores all text data as Unicode. The text system converts Unicode into glyph IDs and places them in 1-, 2-, or 4-byte storage depending on the context. To render text, you must convert the storage into a format the text engine understands. The following constants describe the glyph packing schemes the text rendering engine can use. They are used to extract glyphs from a font for making a multibyte (or single-byte) array of glyphs for passing to an interpreter, such as the window server, which expects a big-endian multibyte stream (that is, “packed glyphs”) instead of a pure NSGlyph stream. They’re used by glyphPacking. With Quartz, the engine always expects the format to be in 2 -byte short array, so NativeShortGlyphPacking is the only format currently in use.

---