Next Page > Hide TOC

NSFontManager

Overview

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

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.

As of Mac OS X version 10.3, font collections are managed by NSFontManager.

Tasks

Constructors

• NSFontManager

Getting the Shared Font Manager

• sharedFontManager

Getting Available Fonts

• availableFonts
• availableFontFamilies
• availableFontNamesWithTraits

Setting and Examining the Selected Font

• setSelectedFont
• selectedFont
• isMultiple
• sendAction
• localizedNameForFamily

Action Methods

• addFontTrait
• removeFontTrait
• modifyFont
• modifyFontViaPanel
• orderFrontStylesPanel
• orderFrontFontPanel

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

Setting the Delegate

• setDelegate
• delegate

Setting the Action Method

• setAction
• action

Setting Attributes

• setSelectedAttributes
• convertAttributes

Working with Font Descriptors

• collectionNames
• fontDescriptorsInCollection
• addCollection
• removeCollection
• addFontDescriptors
• removeFontDescriptor

Implemented by responders

• fontManagerWillIncludeFont  delegate method

Static Methods

sharedFontManager

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

public static NSFontManager sharedFontManager()

Instance Methods

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.

public NSSelector action()

See Also

• setAction

addCollection

Adds a font collection named collectionName to the font manager with a set of options described in “Constants.”

public boolean addCollection(String collectionName, int collectionOptions)

Availability

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

See Also

• removeCollection

addFontDescriptors

Adds an array of font descriptors to the font collection specified by collectionName.

public void addFontDescriptors(NSArray descriptors, String collectionName)

Availability

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

See Also

• removeFontDescriptor

addFontTrait

This action method causes the receiver to send its action message up the responder chain.

public void addFontTrait(Object sender)

Discussion

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

Returns the names of the font families available in the system.

public NSArray availableFontFamilies()

Discussion

These fonts are in various system font directories.

See Also

• availableFontNamesWithTraits
• availableFonts

availableFontNamesWithTraits

Returns the names of the fonts available in the system whose traits are described exactly by fontTraitMask (not the NSFont objects themselves).

public NSArray availableFontNamesWithTraits(int fontTraitMask)

Discussion

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 0, this method returns all fonts that are neither italic nor bold. This result is the same one you’d get if fontTraitMask were UnitalicMask | UnboldMask.

See Also

• availableFontFamilies
• availableFonts

availableFonts

Returns the names of the fonts available in the system (not the NSFont objects themselves).

public NSArray availableFonts()

Discussion

These fonts are in various system font directories.

See Also

• availableFontFamilies
• availableFontNamesWithTraits

collectionNames

Returns the names of the currently loaded font collections.

public NSArray collectionNames()

Availability

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

See Also

• fontDescriptorsInCollection

convertAttributes

public NSDictionary convertAttributes(NSDictionary attributes)

Discussion

Converts attributes in response to an object initiating an attribute change, typically the Font panel or Font menu. Returns the converted attributes dictionary, or attributes itself if the conversion isn’t possible. Attributes unused by the sender should not be changed or removed.

This method is usually invoked on the sender of changeAttributes. See NSTextView for more information.

Availability

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

See Also

• setSelectedAttributes

convertFont

Converts aFont according to the object that initiated a font change, typically the Font panel or Font menu.

public NSFont convertFont(NSFont aFont)

Discussion

Returns the converted font, or aFont itself if the conversion isn’t possible.

This method is invoked in response to 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 “Converting Fonts Manually” for more information.

See Also

• convertFontToFace
• convertFontToFamily
• convertFontToHaveTrait
• convertFontToNotHaveTrait
• convertFontToSize
• convertWeight

convertFontToFace

Returns an NSFont whose traits are as similar as possible to those of aFont except for the typeface, which is changed to typeface.

public NSFont convertFontToFace(NSFont aFont, String typeface)

Discussion

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 to 15.

See Also

• convertFontToFamily
• convertFontToHaveTrait
• convertFontToNotHaveTrait
• convertFontToSize
• convertWeight
• convertFont

convertFontToFamily

Returns an NSFont whose traits are as similar as possible to those of aFont except for the font family, which is changed to family.

public NSFont convertFontToFamily(NSFont aFont, String family)

Discussion

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 to 15.

See Also

• convertFontToFace
• convertFontToHaveTrait
• convertFontToNotHaveTrait
• convertFontToSize
• convertWeight
• convertFont

convertFontToHaveTrait

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.

public NSFont convertFontToHaveTrait(NSFont aFont, int fontTrait)

Discussion

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

Returns an NSFont with the same traits as aFont except for the traits in fontTraitMask, which are removed.

public NSFont convertFontToNotHaveTrait(NSFont aFont, int fontTraitMask)

Discussion

fontTraitMask is a mask created using the C bitwise OR operator to combine the traits described in “Constants.”

Using BoldMask or ItalicMask removes the bold or italic trait, respectively.

Returns aFont if it can’t be converted.

See Also

• convertFontToHaveTrait
• convertFontToFace
• convertFontToFamily
• convertFontToSize
• convertWeight
• convertFont

convertFontToSize

Returns an NSFont whose traits are the same as those of aFont except for the size, which is changed to size.

public NSFont convertFontToSize(NSFont aFont, float size)

Discussion

Returns aFont if it can’t be converted.

See Also

• convertFontToFace
• convertFontToFamily
• convertFontToHaveTrait
• convertFontToNotHaveTrait
• convertWeight
• convertFont

convertWeight

Returns an NSFont whose weight is greater or lesser than that of aFont, if possible.

public NSFont convertWeight(boolean increaseFlag, NSFont aFont)

Discussion

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 on the same line are treated as identical:

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

Returns the receiver’s delegate.

public Object delegate()

See Also

• setDelegate

fontDescriptorsInCollection

Returns an array of the font descriptors in the collection specified by collectionNames.

public NSArray fontDescriptorsInCollection(String collectionNames)

Availability

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

See Also

• collectionNames

fontMenu

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

public NSMenu fontMenu(boolean createFlag)

See Also

• setFontMenu

fontPanel

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

public NSFontPanel fontPanel(boolean createFlag)

See Also

• sharedFontPanel (NSFontPanel)
• sharedFontPanelExists (NSFontPanel)

fontWithFamily

Attempts to load a font with the specified characteristics, returning the font if successful and null if not.

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

Discussion

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

fontWithNameHasTraits

Returns true if the font named typeface has all the traits specified in fontTraitMask, false if it doesn’t.

public boolean fontWithNameHasTraits(String typeface, int fontTraitMask)

Discussion

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.

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.

public boolean isEnabled()

See Also

• isEnabled (NSFontPanel)
• isEnabled (NSMenuItem)
• setEnabled

isMultiple

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

public boolean isMultiple()

See Also

• setSelectedFont
• selectedFont

localizedNameForFamily

Returns a localized string with the name of the specified font family and face (for example, "Times" and "Roman"), if one exists.

public String localizedNameForFamily(String family, String face)

Discussion

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

This action method causes the receiver to send its action message up the responder chain.

public void modifyFont(Object sender)

Discussion

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:

See Also

• addFontTrait
• removeFontTrait
• modifyFontViaPanel

modifyFontViaPanel

This action method causes the receiver to send its action message up the responder chain.

public void modifyFontViaPanel(Object sender)

Discussion

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

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

public void orderFrontFontPanel(Object sender)

See Also

• fontPanel

orderFrontStylesPanel

This action method opens the Font styles panel.

public void orderFrontStylesPanel(Object sender)

Availability

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

removeCollection

Removes the collection specified by collectionName.

public boolean removeCollection(String collectionName)

Availability

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

See Also

• addCollection

removeFontDescriptor

Removes the font collection named collectionName from the collection specified by collection.

public void removeFontDescriptor(NSFontDescriptor descriptor, String collection)

Availability

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

See Also

• addFontDescriptors

removeFontTrait

This action method causes the receiver to send its action message up the responder chain.

public void removeFontTrait(Object sender)

Discussion

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

Returns the last font recorded with a setSelectedFont message.

public NSFont selectedFont()

Discussion

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

Sends the receiver’s action message up the responder chain, initiating a font change for whatever conversion and trait to change were last requested.

public boolean sendAction()

Discussion

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

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.

public void setAction(NSSelector aSelector)

Discussion

You should rarely need to change this setting.

See Also

• action

setDelegate

Sets the receiver’s delegate to anObject.

public void setDelegate(Object anObject)

See Also

• delegate

setEnabled

Controls whether the font conversion system’s user interface items (the Font panel and Font menu items) are enabled.

public void setEnabled(boolean flag)

Discussion

If flag is true they’re enabled; if flag is false they’re disabled.

See Also

• setEnabled (NSFontPanel)
• isEnabled

setFontMenu

Records aMenu as the application’s Font menu.

public void setFontMenu(NSMenu aMenu)

See Also

• fontMenu

setSelectedAttributes

Informs the paragraph and character formatting panels when text in a selection has changed attributes.

public void setSelectedAttributes(NSDictionary attributes, boolean flag)

Discussion

flag is used to inform the panel that multiple fonts or attributes are enclosed within the selection. Used primarily by NSTextView.

Availability

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

See Also

• convertAttributes

setSelectedFont

Records aFont as the currently selected font and updates the Font panel to reflect this.

public void setSelectedFont(NSFont aFont, boolean flag)

Discussion

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

Returns the traits of aFont.

public int traitsOfFont(NSFont aFont)

Discussion

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

Font trait mask values are listed in “Constants.”

weightOfFont

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

public int weightOfFont(NSFont aFont)

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:

• BoldMask

• CompressedMask

• CondensedMask

• ExpandedMask

• FixedPitchMask

• ItalicMask

• NarrowMask

• NonstandardCharacterSetMask

• PosterMask

• SmallCapsMask

• UnboldMask

• UnitalicMask

These pairs of traits are mutually exclusive:

• CondensedMask and ExpandedMask

• BoldMask and UnboldMask

• ItalicMask and UnitalicMask

This constant specifies options accepted by addCollection:

• FontCollectionApplicationOnlyMask

Delegate Methods

fontManagerWillIncludeFont

Requests permission from the delegate to display fontName in the Font panel.

public abstract boolean fontManagerWillIncludeFont(Object theFontManager, String fontName)

Discussion

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 in theFontManager; 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.

Next Page > Hide TOC