Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSFont 

Inherits From:	NSObject

Conforms To:	NSCoding, NSCopying
NSObject (NSObject)

Declared In:	AppKit/NSFont.h

Class Description

The NSFont class declares the programmatic interface to objects that correspond to fonts. NSFont is in principle an abstract class that represents fonts in general, not just PostScript fonts. In practice, at this time, NSFont objects represent PostScript fonts. Each NSFont object records a font's name, size, style, and matrix. When an NSFont object receives a set message, it establishes its font as the current font in the PostScript Server's current graphics state.

For a given application, only one NSFont object is created for a particular PostScript font/size or font/matrix combination. That isÐif you ask for 24-point Optima, a new font object is created for 24-point Optima if such an object doesn't exist already. When the NSFont class object receives a message to create a new object for a particular font, it first checks whether an object has already been created for that font. If so, the the NSFont class object returns the existing font object; otherwise, the the NSFont class object creates a new font object and returns it. 

This sharing of NSFont objects minimizes the number of distinct font objects created. It also implies that no one object in your application can know whether it has the only reference to a particular NSFont object. Thus, NSFont objects shouldn't be deallocated, but should be treated like auto-released Foundation class objects.

Where matrix is used, it refers to a PostScript-style six-element array of numbers that indicate transformations to be applied to a font. An NSFontIdentityMatrix identifies a font matrix used for fonts created by specifying a size.

The size of a font in the method definitions is defined in ªpointsº, which in currently accepted practice, are actually PostScript unitsÐa PostScript unit being defined as 1/72 of an inch, or 0.0139 of an inch. In metric equivalents, a PostScript unit is 0.3528 millimetres. PostScript ªpointsº are minimally different from ªprinter's pointsº, so for all intents and purposes you can think of PostScript units and points as interchangeable.

In general, you instantiate an NSFont object by sending one of the methods listed in ªCreating a Font Objectº to the NSFont class object. The methods with system and user in their names obtain special pre-determined fonts defined at the system level and the application level, respectively. In general, you would use the fontWithName:size: and fontWithName:matrix: methods to obtain a named font.

A variety of methods are available for querying a font object. In particular, AFM (Adobe Font Metrics) data can be obtained by invoking afmDictionary or afmFileContents	.

Methods whose descriptions state ªReturns¼and matrix NSFontIdentityMatrixº actually return an NSFontIdentityMatrix whose first and fourth elements are multiplied by the current size of the font.

Exceptions

Methods listed in ªCreating a Font Objectº can all raise a NSFontUnavailableException if the requested font can't be constructed.

Creating a Font Object

+ (NSFont *)boldSystemFontOfSize:(float)fontSize	Returns the font object representing the bold system font
		of size fontSize and matrix NSFontIdentityMatrix.

+ (NSFont *)fontWithName:(NSString *)fontName matrix:(const float *)fontMatrix
	Returns a font object for font fontName and matrix fontMatrix.

+ (NSFont *)fontWithName:(NSString *)fontName size:(float)fontSize
	Returns a font object for font fontName of size fontSize. 

+ (NSFont *)systemFontOfSize:(float)fontSize	Returns the font object representing the system font of size fontSize and matrix NSFontIdentityMatrix.

+ (NSFont *)userFixedPitchFontOfSize:(float)fontSize
	Returns the font object representing the application's fixed-pitch font of size fontSize and matrix NSFontIdentityMatrix.

+ (NSFont *)userFontOfSize:(float)fontSize	Returns the font object representing the application's standard font of size fontSize and matrix NSFontIdentityMatrix.

Setting the Font

+ (void)setUserFixedPitchFont:(NSFont *)aFont	Sets the fixed-pitch font used by default in the application to aFont.

+ (void)setUserFont:(NSFont *)aFont	Sets the standard font used by default in the application to aFont.

+ (void)useFont:(NSString *)fontName	Registers that fontName is used in the document. This information is used by the printing machinery

- (void)set	Makes this font the graphic state's current font.

Querying the Font

- (NSDictionary *)afmDictionary	Returns the font's AFM dictionary if the font has an AFM file. The return value can possibly be nil, so you must check to determine if a non-nil value was actually returned.

- (NSString *)afmFileContents	Returns the raw contents of the entire AFM file, in terms of strings, if the font has an AFM file. If the font does not have an AFM file, this method returns nil.

- (NSRect)boundingRectForFont	Returns the bounding rectangle for the font. This is the font's FontBBox field scaled to the current size of the font.

- (NSString *)displayName	Returns the full name of the font as displayed in the font panel. This is the localized version of the font's name. It is not necessarily the FullName field of the font.

- (NSString *)familyName	Returns the name of the font's family.

- (NSString *)fontName	Returns the name of the font.

- (BOOL)isBaseFont	Indicates whether the font is a base font, as opposed to a composite font.

- (const float *)matrix	Returns a pointer to an array of six floats representing the font's matrix. You should not alter the data pointed to by matrix. If you wish to change values for any reason you must make a copy of the matrix 

- (float)pointSize	Returns the size of the font in points. 

- (NSFont *)printerFont	Returns the printer font for the font, if the receiving font object is a screen font. Else, this method returns self.

- (NSFont *)screenFont	Returns the screen font for the font, if there is one. Else this method returns self.

- (float)widthOfString:(NSString *)string	Returns the width of string in the font. Use this method with caution: it assumes that the characters in stringcan all actually be rendered in the font. It uses lossy encoding methods in NSString to get the character data.

- (float *)widths	Returns a pointer to an array representing the widths of the glyphs in the font.

Manipulating Glyphs

- (NSSize)advancementForGlyph:(NSGlyph)aGlyph
	Returns the horizontal and vertical advancement for aGlyph. That is, this method returns the amount by which the current point would be displaced in both x and y if the specified glyph were rendered in the current font and size. In general, the y component of the displacement for ªWesternº fonts will be zero.

- (NSRect)boundingRectForGlyph:(NSGlyph)aGlyph
	Returns a bounding rectangle for aGlyph, scaled to the font's actual size and matrix.

- (BOOL)glyphIsEncoded:(NSGlyph)aGlyph	Indicates whether aGlyph is encoded. That is, aGlyph is present in the encoding for the font.

- (NSPoint)positionOfGlyph:(NSGlyph)curGlyph	Returns curGlyph's position when it follows prevGlyph.
precededByGlyph:(NSGlyph)prevGlyph		 nominal is a pointer to a BOOL. If not nil, this method
isNominal:(BOOL *)nominal		 fills in nominal with YES, to indicate that the position has been modified by kerning information, and NO to indicate that no kerning information was present.