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

NSFontManager

Inherits From:	NSObject

Conforms To:	NSObject (NSObject)

Declared In:	AppKit/NSFontManager.h

Class Description

NSFontManager declares the programmatic interface to objects that manage font conversion in an application. NSFontManager is the center of activity for font conversion. NSFontManager accepts messages from font conversion user-interface objects such as the Font menu or the Font panel (see NSFontPanel for more details) and appropriately converts the current font in the selection by sending a changeFont: message up the responder chain.

When an object receives a changeFont: message, it should message NSFontManager (by sending it a convertFont: message), asking it to convert the font in whatever way the user has specified. Thus, any object containing a font that can be changed should respond to the changeFont: message by sending a convertFont: message back to the NSFontManager for each font in the selection.

To use NSFontManager, you simply insert a Font menu into your application's menu using the appropriate interface construction tools (such as Interface Builder). You can also obtain a Font menu by sending a getFontMenu: message to NSFontManager and then inserting the menu it returns into the application's main menu. Once the Font menu is installed, your application automatically gains the functionality of both the Font menu and the Font panel.

NSFontManager's delegate can restrict which font names will appear in the Font Panel. See ªMethods Implemented by the Delegateº at the end of this class specification for more information.

NSFontManager can be used to convert a font or find out the attributes of a font. It can also be overridden to convert fonts in some application-specific manner. The default implementation of font conversion is very conservative: The font isn't converted unless all traits of the font can be maintained across the conversion.

Generally, you obtain an instance of NSFontManager by sending a sharedFontManager message to the NSFontManager class object. NSFontManager will return a font manager object that is shared within your application. NSFontManager normally returns a pre-defined font manager object, but the actual object which is returned can be changed by previously invoking the setFontManagerFactory factory to some other kind of object.

Font Traits

Fonts work mainly in terms of traits, or characteristics, such as bold, italic, condensed, and so on. Traits are described by a collection of constants such as NSItalicFontMask, NSBoldFontMask, and so on. The full complement of traits are defined in AppKit/NSFontManager.h. The values of traits are defined in bitwise form so they can be or'ed together, although some traits, such as NSBoldFontMask and NSUnboldFontMask naturally conflict and have the effect of turning each other off. You use one of the convertFont¼ methods to obtain a font of the desired characteristics from an existing font.

The convertFont:toHaveTrait: and the convertFont:toNotHaveTrait: methods deal with only one trait at a time. To convert a font to have (or not have) multiple traits, you must invoke these methods for each separate trait you wish to add to or remove from the font. Alternatively, use the fontWithFamily:traits:weight:size: method to specify multiple traits in one invocation.	

The size of a font in the method definitions below is defined in ªpointsº, which, in the current milieu, 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.

The weight of a font as used in these methods is simply a value representing a point in a continuum of font weights from lightest to heaviest. There's no simple one-to-one mapping of some integer value to, say, a bold weight. If you query the font for its weight value, increment the value, and use it as a new weight, you'll not necessarily obtain a different face (such as a transition from medium to bold) in a new instance of the font. 

Managing the FontManager

+ (void)setFontManagerFactory:(Class)classId	Sets the class used to create the NSFontManager.

+ (void)setFontPanelFactory:(Class)classId	Sets the class used to create the FontPanel.

+ (NSFontManager *)sharedFontManager	Returns a shared FontManager.

Converting Fonts

- (NSFont *)convertFont:(NSFont *)fontObject	Converts fontObject according to the user's selections from the Font panel or the Font menu.

- (NSFont *)convertFont:(NSFont *)fontObject	Returns a Font object whose traits are the same as those of
toFamily:(NSString *)family		 fontObject except as specified by family. 	

- (NSFont *)convertFont:(NSFont *)fontObject	Returns a Font object whose traits are the same as those of
toFace:(NSString *)typeface		 fontObject except as specified by typeface. 	

- (NSFont *)convertFont:(NSFont *)fontObject	Returns a Font object whose traits are the same as those of
toHaveTrait:(NSFontTraitMask)trait		 fontObject except as altered by the addition of the traits specified by trait.

- (NSFont *)convertFont:(NSFont *)fontObject	Returns a Font object whose traits are the same as those of
toNotHaveTrait:(NSFontTraitMask)trait		 fontObject except as altered by the removal of the traits specified by trait.

- (NSFont *)convertFont:(NSFont *)fontObject	Returns a Font object whose traits are the same as those of
toSize:(float)size		 fontObject except as specified by size. 	

- (NSFont *)convertWeight:(BOOL)upFlag	Attempts to increase (if upFlag is YES) or decrease (if
ofFont:(NSFont *)fontObject		 upFlag is NO) the weight of the font specified by fontObject. 

- (NSFont *)fontWithFamily:(NSString *)family	Tries to find a font that matches the specified
traits:(NSFontTraitMask)traits	 	characteristics.
weight:(int)weight	 
size:(float)size	

Setting and Getting Parameters

- (SEL)action	Gets the action sent by the FontManager.

- (NSArray *)availableFonts	Provides an array listing all available fonts.

- (NSMenu *)fontMenu:(BOOL)create	Returns the Font menu, creating one if it doesn't exist and create is YES.

- (NSFontPanel *)fontPanel:(BOOL)create	Returns the Font panel, creating one if it doesn't exist and create is YES.

- (BOOL)isEnabled	Returns whether the Font panel and menu are enabled.

- (BOOL)isMultiple	Returns whether the selection contains multiple fonts.

- (NSFont *)selectedFont	Returns the first font in the current selection 

- (void)setAction:(SEL)aSelector	Sets the action to that specified by aSelector to be sent by the FontManager when the user selects a new font.

- (void)setEnabled:(BOOL)flag	Enables or disables the Font panel and menu depending on flag.

- (void)setFontMenu:(NSMenu *)newMenu	Sets the font menu to newMenu.

- (void)setSelectedFont:(NSFont *)fontObject	Notifies FontManager of the selection's current font from
isMultiple:(BOOL)flag		fontObject with flag indicating whether the selection has multiple fonts.

- (NSFontTraitMask)traitsOfFont:(NSFont *)fontObject
	Returns the font traits of fontObject.

- (int)weightOfFont:(NSFont *)fontObject	Returns the font weight of fontObject.

Target and Action Methods

- (BOOL)sendAction	Dispatches the action message up the responder chain.

Assigning a Delegate

- (id)delegate	Returns the FontManager's delegate.

- (void)setDelegate:(id)anObject	Sets the FontManager's delegate to anObject.

Methods Implemented by the Delegate

- (BOOL)fontManager:(id)sender willIncludeFont:(NSString *)fontName
	Responds to a message informing the FontManager's delegate that the FontPanel is about to include fontName in the list displayed to the user; if this method returns NO, the font isn't added; otherwise, it is.