Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSFontManager


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


NSFontManager is the center of activity for the font conversion system. It records the currently selected font, updates the Font Panel and Font menu to reflect the selected font, initiates font changes, and converts fonts in response to requests from text-bearing objects. In a more prosaic role, NSFontManager can be queried for the fonts available to the application, and for the particular attributes of a font, such as whether it's condensed or extended.

You normally set up a font manager and the Font Menu using Interface Builder. However, you can also do so programmatically by getting the shared font manager instance and having it create the standard Font menu at run time.

You can then add the Font menu to your 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.


Recording the Selected Font


Any object that records fonts that the user can change should tell the font manager what the font of its selection is whenever it becomes the first responder and whenever its selection changes while it's the first responder. The object does so by sending the shared font manager a setSelectedFont message. It should pass in the first font of the selection, along with a flag indicating whether there's more than one font.

The font manager uses this information to update the Font Panel and Font menu to reflect the selected font. For example, suppose the selected font is set as Helvetica Oblique 12.0 point. In this case the Font Panel selects that font and displays its name; the Font menu changes its Italic command to Unitalic; if there's no Bold variant of Helvetica available, the Bold menu item is disabled; and so on.


Initiating Font Changes


The user normally changes the font of the selection by manipulating the Font Panel and Font menu. These objects initiate the intended change by sending an action message to the font manager. There are four font-changing action methods:

The first three cause the font manager to query the sender of the message in order to determine which trait to add or remove, or how to modify the font. The last causes the font manager to use the settings in the Font Panel to modify the font. The font manager records this information and uses it in later requests to convert fonts, as described under "Responding to Font Changes" .

When the font manager receives an addFontTrait or removeFontTrait message, it queries the sender with a tag message, interpreting the return value as a trait mask for use with convertFontToHaveTrait or convertFontToNotHaveTrait, as described below under "Converting Fonts Manually" . The Italic and Bold Font menu commands, for example, have tags of ItalicMask and BoldMask, respectively. See convertFontToHaveTrait for a list of trait mask values.

When the font manager receives a modifyFont message, it queries the sender with a tag message and interprets the return value as a particular kind of conversion to perform, via the various conversion methods described under "Converting Fonts Manually" . For example, a button whose tag value is SizeUpFontAction causes the font manager's convertFont method to increase the size of the NSFont passed as the argument. See modifyFont for a list of conversion tag values.

For modifyFontViaPanel, the font manager sends the application's Font Panel a panelConvertFont message. The Font Panel in turn uses the font manager to convert the font provided according to the user's choices. For example, if the user selects only the font family in the Font Panel (perhaps to Helvetica), then whatever fonts are provided to panelConvertFont, only the family is changed: Courier Medium 10.0 point becomes Helvetica Medium 10.0 point, while Times Italic 12.0 point becomes Helvetica Oblique 12.0 point.


Responding to Font Changes


The font manager responds to a font-changing action method by sending a changeFont: action message up the responder chain. A text-bearing object that receives this message should have the font manager convert the fonts in its selection by invoking convertFont for each font and using the NSFont object returned. convertFont uses the information recorded by the font-changing action method, such as addFontTrait, modifying the font provided appropriately. (There's no way to explicitly set the font-changing action or trait; instead, you use the methods described under "Converting Fonts Manually".)

Most text-bearing objects will have to scan the selection for ranges with different fonts, and invoke convertFont for each one.


Converting Fonts Manually


NSFontManager defines a number of methods for explicitly converting particular traits and characteristics of a font. These methods are:

Each returns a transformed version of the font provided, or the original font if it can't be converted. convertFontToFace and convertFontToFamily both alter the basic design of the font provided. The first method requires a fully-specified typeface name, such as "Times-Roman" or "Helvetica-BoldOblique", while the second expects only a family name, such as "Times" or "Helvetica".

convertFontToHaveTrait and convertFontToNotHaveTrait use trait masks to add or remove a single trait such as Italic, Bold, Condensed, or Extended.

convertFontToSize returns a font of the requested size, with all other characteristics the same as those of the original font.

convertWeight either increases or decreases the weight of the font provided, according to a boolean flag. Font weights are typically indicated by a series of names, which can vary from font to font. Some go from Light to Medium to Bold, while others have Book, SemiBold, Bold, and Black. This method offers a uniform way of incrementing and decrementing any font's weight.

The default implementation of font conversion is very conservative, making a change only if no other trait or aspect is affected. For example, if you try to convert Helvetica Oblique 12.0 point by adding the Bold trait, and only Helvetica Bold is available, the font isn't converted. You can create a subclass of NSFontManager and override the conversion methods to perform less conservative conversion, perhaps using Helvetica Bold in this case and losing the Oblique trait.

In addition to the font-conversion methods, NSFontManager defines fontWithFamily to construct a font with a given set of characteristics. If you don't care to make a subclass of NSFontManager, you can use this method to perform approximate font conversions yourself.


Examining Fonts


In addition to converting fonts, NSFontManager provides information on which fonts are available to the application, and on the characteristics of any given font. availableFonts returns an array of the names of all fonts available. availableFontNamesWithTraits filters the available fonts based on a font trait mask.

There are three methods for examining individual fonts. fontWithNameHasTraits returns true if the font matches the trait mask provided. traitsOfFont returns a trait mask for a given font. weightOfFont returns an approximate ranking of a font's weight on a scale of 0-15, where 0 is the lightest possible weight, 5 is Normal or Book weight, 9 is the equivalent of Bold, and 15 is the heaviest possible (often called Black or Ultra Black).


Customizing the Font Conversion System


To add some custom controls to the Font Panel, invoke NSFontPanel's setAccessoryView method to add an NSView below its font browser.

If you provide your own Font menu, you should register it with the font manager using the setFontMenu method. The font manager is responsible for validating Font menu items and changing their titles and tags according to the selected font. For example, when the selected font is Italic the font manager changes the Italic Font menu item to Unitalic, and changes its tag to UnitalicMask. Your Font menu's items should use the appropriate action methods and tags. Here are some examples:


Font Menu Item Action Tag
Italic addFontTrait ItalicMask
Bold addFontTrait BoldMask
Heavier modifyFont HeavierFontAction
Larger modifyFont SizeUpFontAction




Constants


NSFontManager categorizes fonts according to a small set of traits. You can convert fonts by adding and removing individual traits, and you can get a font with a specific combination of traits. The traits defined and available for your use are:

These pairs of traits are mutually exclusive:

The constants specify what action modifyFont will take:



Method Types


Constructors
NSFontManager
Getting the shared font manager
sharedFontManager
Getting available fonts
availableFonts
availableFontFamilies
availableFontNamesWithTraits
Setting and examining the selected font
setSelectedFont
selectedFont
isMultiple
sendAction
Action methods
addFontTrait
removeFontTrait
modifyFont
modifyFontViaPanel
Converting fonts automatically
convertFont
Converting fonts manually
convertFontToFace
convertFontToFamily
convertFontToHaveTrait
convertFontToNotHaveTrait
convertFontToSize
convertWeight
Getting a particular font
fontWithFamily
Examining fonts
traitsOfFont
fontWithNameHasTraits
weightOfFont
Enabling the Font Panel and Font menu
setEnabled
isEnabled
Setting the Font menu
setFontMenu
fontMenu
Getting the Font Panel
fontPanel
orderFrontFontPanel
Setting the delegate
setDelegate
delegate
Setting the action method
setAction
action


Constructors



NSFontManager

public NSFontManager()

Description forthcoming.


Static Methods



sharedFontManager

public static NSFontManager sharedFontManager()

Returns the shared instance of the font manager for the application, creating it if necessary.

See Also: setFontManagerFactory:




Instance Methods



action

public NSSelector action()

Returns the action sent to the first responder when the user selects a new font from the Font panel or chooses a command from the Font menu.

See Also: setAction



addFontTrait

public void addFontTrait(Object sender)

This action method causes the receiver to send its action message up the responder chain. When a responder replies by providing a font to convert in a convertFont message, the receiver converts the font by adding the trait specified by sender. This trait is determined by sending a tag message to sender and interpreting it as a font trait mask for a convertFontToHaveTrait message.

See Also: removeFontTrait, modifyFont, modifyFontViaPanel



availableFontFamilies

public NSArray availableFontFamilies()

Returns the names of the font families available in the system. These fonts are in various system font directories.

See Also: availableFontNamesWithTraits, availableFonts



availableFontNamesWithTraits

public NSArray availableFontNamesWithTraits(int fontTraitMask)

Returns the names of the fonts available in the system whose traits are described exactly by fontTraitMask (not the NSFont objects themselves). These fonts are in various system font directories. You specify the desired traits by combining the font trait mask values described in "Constants" using the C bitwise OR operator.

If fontTraitMask is zero, this method returns all fonts that are neither italic nor bold. This is the same result you'd get if fontTraitMask were UnitalicMask | UnboldMask.

See Also: availableFontFamilies, availableFonts



availableFonts

public NSArray availableFonts()

Returns the names of the fonts available in the system (not the NSFont objects themselves). These fonts are in various system font directories.

See Also: availableFontFamilies, availableFontNamesWithTraits



convertFont

public NSFont convertFont(NSFont aFont)

Converts aFont according to the object that initiated a font change, typically the Font Panel or Font menu. Returns the converted font, or aFont itself if the conversion isn't possible.

This method is invoked in response to a changeFont: message, which is itself initiated by an action message such as addFontTrait or modifyFontViaPanel. These initiating methods cause the font manager to query the sender for the action to take and the traits to change. See the class description for more information.

See Also: convertFontToFace, convertFontToFamily, convertFontToHaveTrait, convertFontToNotHaveTrait, convertFontToSize, convertWeight



convertFontToFace

public NSFont convertFontToFace( NSFont aFont, String typeface)

Returns an NSFont whose traits are as similar as possible to those of aFont except for the typeface, which is changed to typeface. Returns aFont if it can't be converted. A typeface is a fully specified family-face name, such as Helvetica-BoldOblique or Times-Roman.

This method attempts to match the weight and posture of aFont as closely as possible. Italic is mapped to Oblique, for example. Weights are mapped based on an approximate numeric scale of 0-15.

See Also: convertFontToFamily, convertFontToHaveTrait, convertFontToNotHaveTrait, convertFontToSize, convertWeight, convertFont



convertFontToFamily

public NSFont convertFontToFamily( NSFont aFont, String family)

Returns an NSFont whose traits are as similar as possible to those of aFont except for the font family, which is changed to family. Returns aFont if it can't be converted. A family is a generic font name, such as Helvetica or Times.

This method attempts to match the weight and posture of aFont as closely as possible. Italic is mapped to Oblique, for example. Weights are mapped based on an approximate numeric scale of 0-15.

See Also: convertFontToFace, convertFontToHaveTrait, convertFontToNotHaveTrait, convertFontToSize, convertWeight, convertFont



convertFontToHaveTrait

public NSFont convertFontToHaveTrait( NSFont aFont, int fontTrait)

Returns an NSFont whose traits are the same as those of aFont except for the traits, which are changed to include the single trait fontTrait. fontTrait may be any one of the traits described in "Constants" .

Using UnboldMask or UnitalicMask removes the bold or italic trait, respectively.

Returns aFont if it can't be converted.

See Also: convertFontToNotHaveTrait, convertFontToFace, convertFontToFamily, convertFontToSize, convertWeight, convertFont



convertFontToNotHaveTrait

public NSFont convertFontToNotHaveTrait( NSFont aFont, int fontTraitMask)

Returns an NSFont with the same traits as aFont except for the traits in fontTraitMask, which are removed. fontTraitMask is a mask created using the C bitwise OR operator to combine the traits described in "Constants" .

Using UnboldMask or UnitalicMask removes the bold or italic trait, respectively.

Returns aFont if it can't be converted.

See Also: convertFontToHaveTrait, convertFontToFace, convertFontToFamily, convertFontToSize, convertWeight, convertFont



convertFontToSize

public NSFont convertFontToSize( NSFont aFont, float size)

Returns an NSFont whose traits are the same as those of aFont except for the size, which is changed to size. Returns aFont if it can't be converted.

See Also: convertFontToFace, convertFontToFamily, convertFontToHaveTrait, convertFontToNotHaveTrait, convertWeight, convertFont



convertWeight

public NSFont convertWeight( boolean increaseFlag, NSFont aFont)

Returns an NSFont whose weight is greater or lesser than that of aFont, if possible. If increaseFlag is true, a heavier font is returned; if it's false, a lighter font is returned. Returns aFont unchanged if it can't be converted.

Weights are graded along the following scale. The list on the left gives Apple's terminology and the list on the right gives the ISO equivalents. Names in the same line are treated as identical:


1) ultralight
2) thin W1) ultralight
3) light, extralight W2) extralight
4) book W3) light
5) regular, plain, display, roman W4) semilight
6) medium W5) medium
7) demi, demibold
8) semi, semibold W6) semibold
9) bold W7) bold
10) extra, extrabold W8) extrabold
11) heavy, heavyface
12) black, super W9) ultrabold
13) ultra, ultrablack, fat
14) extrablack, obese, nord

NSFontManager's implementation of this method refuses to convert a font's weight if it can't maintain all other traits, such as Italic and Condensed. You might wish to override this method to allow a looser interpretation of weight conversion.

See Also: convertFontToFace, convertFontToFamily, convertFontToHaveTrait, convertFontToNotHaveTrait, convertFontToSize, convertFont



delegate

public Object delegate()

Returns the receiver's delegate.

See Also: setDelegate



fontMenu

public NSMenu fontMenu(boolean createFlag)

Returns the menu that's hooked up to the font conversion system, creating it if necessary if createFlag is true.

See Also: setFontMenu



fontWithNameHasTraits

public boolean fontWithNameHasTraits( String typeface, int fontTraitMask)

Returns true if the font named typeface has all the traits specified in fontTraitMask, false if it doesn't. You specify the desired traits by combining the font trait mask values described in "Constants" using the C bitwise OR operator.

Using UnboldMask returns true if the font is not bold, false otherwise. Using UnitalicMask returns true if the font is not italic, false otherwise.



fontPanel

public NSFontPanel fontPanel(boolean createFlag)

Returns the application's shared Font Panel object, creating it if necessary if createFlag is true.

See Also: sharedFontPanel (NSFontPanel), sharedFontPanelExists (NSFontPanel)



fontWithFamily

public NSFont fontWithFamily( String family, int fontTraitMask, int weight, float size)

Attempts to load a font with the specified characteristics, returning the font if successful and null if not. family is the generic name of the font desired, such as Times or Helvetica. weight is a hint for the weight desired, on a scale of 0-15: a value of 5 indicates a normal or book weight and 9 or more a bold or heavier weight. The weight is ignored if fontTraitMask includes BoldMask.

You specify fontTraitMask by combining the font trait mask values described in "Constants" using the C bitwise OR operator.

Using UnboldMask or UnitalicMask loads a font that doesn't have either the bold or italic trait, respectively.



isEnabled

public boolean isEnabled()

Returns true if the font-conversion system's user interface items (the Font Panel and Font menu items) are enabled, false if they're not.

See Also: isEnabled (NSFontPanel), isEnabled (NSMenuItem), setEnabled



isMultiple

public boolean isMultiple()

Returns true if the last font selection recorded has multiple fonts, false if it's a single font.

See Also: setSelectedFont, selectedFont



localizedNameForFamily

public String localizedNameForFamily( String family, String face)

Returns a localized string with the name of the specified font family and face (for example, "Times" and "Roman"), if one exists. The user's location is determined from the user's Languages default setting. The method also loads the localized strings for the font, if they aren't already loaded.

If face is null, this method returns the font family only.



modifyFont

public void modifyFont(Object sender)

This action method causes the receiver to send its action message up the responder chain. When a responder replies by providing a font to convert in a convertFont message, the receiver converts the font in the manner specified by sender. The conversion is determined by sending a tag message to sender and invoking a corresponding method:
Sender's Tag Method Used
NoFontChangeAction None, the font is returned unchanged
ViaPanelFontAction The Font Panel's panelConvertFont
AddTraitFontAction convertFontToHaveTrait
RemoveTraitFontAction convertFontToNotHaveTrait
SizeUpFontAction convertFontToSize
SizeDownFontAction convertFontToSize
HeavierFontAction convertWeight
LighterFontAction convertWeight

See Also: addFontTrait, removeFontTrait, modifyFontViaPanel



modifyFontViaPanel

public void modifyFontViaPanel(Object sender)

This action method causes the receiver to send its action message up the responder chain. When a responder replies by providing a font to convert in a convertFont message, the receiver converts the font by sending a panelConvertFont message to the Font Panel. The panel in turn may send convertFontToFamily, convertFontToHaveTrait, and other specific conversion methods to make its change.

See Also: addFontTrait, removeFontTrait, modifyFont



orderFrontFontPanel

public void orderFrontFontPanel(Object sender)

This action method opens the Font Panel by sending it an orderFront: message, creating the Font Panel if necessary.

See Also: fontPanel, setFontPanelFactory:



removeFontTrait

public void removeFontTrait(Object sender)

This action method causes the receiver to send its action message up the responder chain. When a responder replies by providing a font to convert in a convertFont message, the receiver converts the font by removing the trait specified by sender. This trait is determined by sending a tag message to sender and interpreting it as a font trait mask for a convertFontToNotHaveTrait message.

See Also: addFontTrait, modifyFont, modifyFontViaPanel



selectedFont

public NSFont selectedFont()

Returns the last font recorded with a setSelectedFont message. While fonts are being converted in response to a convertFont message, you can determine the font selected in the Font Panel like this:
NSFontManager fontManager = NSFontManager.sharedFontManager();
panelFont = fontManager.convertFont(fontManager.selectedFont());

See Also: isMultiple



sendAction

public boolean sendAction()

Sends the receiver's action message up the responder chain, initiating a font change for whatever conversion and trait to change were last requested. Returns true if some object handled the message, false if the message went unheard.

This method is used internally by the font conversion system. You should never need to invoke it directly. Instead, use the action methods such as addFontTrait or modifyFontViaPanel.

See Also: setAction



setAction

public void setAction(NSSelector aSelector)

Sets the action that's sent to the first responder when the user selects a new font from the Font panel or chooses a command from the Font menu to aSelector. You should rarely need to change this.

See Also: action



setDelegate

public void setDelegate(Object anObject)

Sets the receiver's delegate to anObject.

See Also: delegate



setEnabled

public void setEnabled(boolean flag)

Controls whether the font-conversion system's user interface items (the Font Panel and Font menu items) are enabled. If flag is true they're enabled; if flag is false they're disabled.

See Also: setEnabled (NSFontPanel), isEnabled



setFontMenu

public void setFontMenu(NSMenu aMenu)

Records aMenu as the application's Font menu.

See Also: fontMenu



setSelectedFont

public void setSelectedFont( NSFont aFont, boolean flag)

Records aFont as the currently selected font, and updates the Font Panel to reflect this. If flag is true, the Font Panel indicates that more than one font is contained in the selection.

An object that manipulates fonts should invoke this method whenever it becomes first responder and whenever its selection changes. After all fonts have been converted, the font manager itself records the new selected font.

See Also: selectedFont, isMultiple



traitsOfFont

public int traitsOfFont(NSFont aFont)

Returns the traits of aFont. The traits are returned as a mask created by combining these options with the C bitwise OR operator:

You specify fontTraitMask by combining the font trait mask values described in "Constants" using the C bitwise OR operator.



weightOfFont

public int weightOfFont(NSFont aFont)

Returns a rough numeric measure of aFont's weight, where 0 indicates the lightest possible weight, 5 indicates a normal or book weight, and 9 or more indicates a bold or heavier weight.


Methods Implemented By the Delegate


fontManagerWillIncludeFont

public abstract boolean fontManagerWillIncludeFont( Object theFontManager, String fontName)

Requests permission from the delegate to display fontName in the Font Panel. fontName is the full PostScript name of the font, such as "Helvetica-BoldOblique" or "Helvetica-Narrow-Bold". If the delegate returns true, fontName is listed; if the delegate returns false, it isn't.

This method is invoked repeatedly as necessary whenever the Font Panel needs updating, such as when the Font Panel is first loaded, and when the user selects a family name to see which typefaces in that family are available. Your implementation should execute fairly quickly to ensure the responsiveness of the Font Panel.




Table of Contents