Inherits from: NSObject
Conforms to: NSObject
(NSObject)
Declared in: AppKit/NSFontManager.h
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:
NSFontManager *fontManager = [NSFontManager sharedFontManager]; NSMenu *fontMenu = [fontManager fontMenu:YES];
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.
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:isMultiple: 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.
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 convertFont:toHaveTrait: or convertFont:toNotHaveTrait:,
as described below under "Converting Fonts Manually". The Italic
and Bold Font menu commands, for example, have tags of NSItalicFontMask
and NSBoldFontMask
,
respectively. See convertFont:toHaveTrait: 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 NSSizeUpFontAction
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.
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".)
This simple example assumes there's only one font in the selection:
- (void)changeFont:(id)sender { NSFont *oldFont = [self selectionFont]; NSFont *newFont = [sender convertFont:oldFont]; [self setSelectionFont:newFont]; return; }
Most text-bearing objects will have to scan the selection for ranges with different fonts, and invoke convertFont: for each one.
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. - convertFont:toFace: and - convertFont:toFamily: 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".
- convertFont:toHaveTrait: and - convertFont:toNotHaveTrait: use trait masks to add or remove a single trait such as Italic, Bold, Condensed, or Extended.
- convertFont:toSize: returns a font of the requested size, with all other characteristics the same as those of the original font.
- convertWeight:ofFont: 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:traits:weight:size: 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.
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. fontNamed:hasTraits: returns YES
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).
If you need to customize the font conversion system by creating subclasses of NSFontManager or NSFontPanel, you must inform the NSFontManager class of this change with a setFontManagerFactory: or setFontPanelFactory: message, before either the shared font manager or shared font panel is created. These methods record your class as the one to instantiate the first time the font manager or Font Panel is requested.
You may be able to avoid using subclasses if all you need is to add some custom controls to the Font Panel. In this case, you can 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 NSUnitalicFontMask
.
Your Font menu's items should use the appropriate action methods
and tags. Here are some examples:
Font Menu Item | Action | Tag |
Italic | addFontTrait: | NSItalicFontMask |
Bold | addFontTrait: | NSBoldFontMask |
Heavier | modifyFont: | NSHeavierFontAction |
Larger | modifyFont: | NSSizeUpFontAction |
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:
NSBoldFontMask
NSCompressedFontMask
NSCondensedFontMask
NSExpandedFontMask
NSFixedPitchFontMask
NSItalicFontMask
NSNarrowFontMask
NSNonstandardCharacterSetFontMask
NSPosterFontMask
NSSmallCapsFontMask
NSUnboldFontMask
NSUnitalicFontMask
These pairs of traits are mutually exclusive:
NSCondensedFontMask
and NSExpandedFontMask
NSBoldFontMask
and NSUnboldFontMask
NSItalicFontMask
and NSUnitalicFontMask
The constants specify what action modifyFont: will take:
NSNoFontChangeAction
NSViaPanelFontAction
NSAddTraitFontAction
NSRemoveTraitFontAction
NSSizeUpFontAction
NSSizeDownFontAction
NSHeavierFontAction
NSLighterFontAction
- Getting the shared font manager
- + sharedFontManager
- Changing the default font conversion classes
- + setFontManagerFactory:
- + setFontPanelFactory:
- Getting available fonts
- - availableFonts
- - availableFontFamilies
- - availableFontNamesWithTraits:
- Setting and examining the selected font
- - setSelectedFont:isMultiple:
- - selectedFont
- - isMultiple
- - sendAction
- Action methods
- - addFontTrait:
- - removeFontTrait:
- - modifyFont:
- - modifyFontViaPanel:
- Converting fonts automatically
- - convertFont:
- Converting fonts manually
- - convertFont:toFace:
- - convertFont:toFamily:
- - convertFont:toHaveTrait:
- - convertFont:toNotHaveTrait:
- - convertFont:toSize:
- - convertWeight:ofFont:
- Getting a particular font
- - fontWithFamily:traits:weight:size:
- Examining fonts
- - traitsOfFont:
- - fontNamed:hasTraits:
- - 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
+ (void)setFontManagerFactory:(Class)aClass
This method must be invoked before your application's main nib file is loaded, such as in the application delegate's applicationWillFinishLaunching: method.
See Also: + setFontPanelFactory:
+ (void)setFontPanelFactory:(Class)factoryId
See Also: + setFontManagerFactory:
+ (NSFontManager *)sharedFontManager
See Also: + setFontManagerFactory:
- (SEL)action
See Also: - setAction:
- (void)addFontTrait:(id)sender
See Also: - removeFontTrait:, - modifyFont:, - modifyFontViaPanel:
- (NSArray *)availableFontFamilies
See Also: - availableFontNamesWithTraits:, - availableFonts
- (NSArray *)availableFontNamesWithTraits:(NSFontTraitMask)fontTraitMask
NSBoldFontMask
NSCompressedFontMask
NSCondensedFontMask
NSExpandedFontMask
NSFixedPitchFontMask
NSItalicFontMask
NSNarrowFontMask
NSNonstandardCharacterSetFontMask
NSPosterFontMask
NSSmallCapsFontMask
NSUnboldFontMask
NSUnitalicFontMask
These pairs of traits are mutually exclusive:
NSCondensedFontMask
and NSExpandedFontMask
NSBoldFontMask
and NSUnboldFontMask
NSItalicFontMask
and NSUnitalicFontMask
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 NSUnitalicFontMask
|
NSUnboldFontMask
.
See Also: - availableFontFamilies, - availableFonts
- (NSArray *)availableFonts
See Also: - availableFontFamilies, - availableFontNamesWithTraits:
- (NSArray *)availableMembersOfFontFamily:(NSString
*)family
Each entry of the returned NSArray is another NSArray with 4 members, as follows:
The members of the family are arranged in the font-panel order (narrowest to widest, lightest to boldest, plain to italic).
For example, if you call availableMembersOfFontFamily:@"Times", it might return an array like this:
(("Times-Roman", "Roman", 5, 4), ("Times-Italic", "Italic", 6, 5), ("Times-Bold", "Bold", 9, 2), ("Times-BoldItalic", "Bold Italic", 9, 3) )
- (NSFont *)convertFont:(NSFont
*)aFont
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: - convertFont:toFace:, - convertFont:toFamily:, - convertFont:toHaveTrait:, - convertFont:toNotHaveTrait:, - convertFont:toSize:, - convertWeight:ofFont:
- (NSFont *)convertFont:(NSFont
*)aFont toFace:(NSString
*)typeface
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: - convertFont:toFamily:, - convertFont:toHaveTrait:, - convertFont:toNotHaveTrait:, - convertFont:toSize:, - convertWeight:ofFont:, - convertFont:
- (NSFont *)convertFont:(NSFont
*)aFont toFamily:(NSString
*)family
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: - convertFont:toFace:, - convertFont:toHaveTrait:, - convertFont:toNotHaveTrait:, - convertFont:toSize:, - convertWeight:ofFont:, - convertFont:
- (NSFont *)convertFont:(NSFont
*)aFont toHaveTrait:(NSFontTraitMask)fontTrait
NSBoldFontMask
NSCompressedFontMask
NSCondensedFontMask
NSExpandedFontMask
NSFixedPitchFontMask
NSItalicFontMask
NSNarrowFontMask
NSNonstandardCharacterSetFontMask
NSPosterFontMask
NSSmallCapsFontMask
NSUnboldFontMask
NSUnitalicFontMask
These pairs of traits are mutually exclusive:
NSCondensedFontMask
and NSExpandedFontMask
NSBoldFontMask
and NSUnboldFontMask
NSItalicFontMask
and NSUnitalicFontMask
Using NSUnboldFontMask
or NSUnitalicFontMask
removes
the bold or italic trait, respectively.
Returns aFont if it can't be converted.
See Also: - convertFont:toNotHaveTrait:, - convertFont:toFace:, - convertFont:toFamily:, - convertFont:toSize:, - convertWeight:ofFont:, - convertFont:
- (NSFont *)convertFont:(NSFont
*)aFont toNotHaveTrait:(NSFontTraitMask)fontTraitMask
NSBoldFontMask
NSCompressedFontMask
NSCondensedFontMask
NSExpandedFontMask
NSFixedPitchFontMask
NSItalicFontMask
NSNarrowFontMask
NSNonstandardCharacterSetFontMask
NSPosterFontMask
NSSmallCapsFontMask
NSUnboldFontMask
NSUnitalicFontMask
These pairs of traits are mutually exclusive:
NSCondensedFontMask
and NSExpandedFontMask
NSBoldFontMask
and NSUnboldFontMask
NSItalicFontMask
and NSUnitalicFontMask
Using NSUnboldFontMask
or NSUnitalicFontMask
removes
the bold or italic trait, respectively.
Returns aFont if it can't be converted.
See Also: - convertFont:toHaveTrait:, - convertFont:toFace:, - convertFont:toFamily:, - convertFont:toSize:, - convertWeight:ofFont:, - convertFont:
- (NSFont *)convertFont:(NSFont
*)aFont toSize:(float)size
See Also: - convertFont:toFace:, - convertFont:toFamily:, - convertFont:toHaveTrait:, - convertFont:toNotHaveTrait:, - convertWeight:ofFont:, - convertFont:
- (NSFont *)convertWeight:(BOOL)increaseFlag ofFont:(NSFont
*)aFont
YES
,
a heavier font is returned; if it's NO
,
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 right gives OpenStep'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: - convertFont:toFace:, - convertFont:toFamily:, - convertFont:toHaveTrait:, - convertFont:toNotHaveTrait:, - convertFont:toSize:, - convertFont:
- (id)delegate
See Also: - setDelegate:
- (NSMenu *)fontMenu:(BOOL)createFlag
YES
.See Also: - setFontMenu:
- (BOOL)fontNamed:(NSString
*)typeface hasTraits:(NSFontTraitMask)fontTraitMask
YES
if
the font named typeface has all the
traits specified in fontTraitMask, NO
if
it doesn't. You specify the desired traits by
combining these font trait mask values using the C bitwise OR operator:NSBoldFontMask
NSCompressedFontMask
NSCondensedFontMask
NSExpandedFontMask
NSFixedPitchFontMask
NSItalicFontMask
NSNarrowFontMask
NSNonstandardCharacterSetFontMask
NSPosterFontMask
NSSmallCapsFontMask
NSUnboldFontMask
NSUnitalicFontMask
These pairs of traits are mutually exclusive:
NSCondensedFontMask
and NSExpandedFontMask
NSBoldFontMask
and NSUnboldFontMask
NSItalicFontMask
and NSUnitalicFontMask
Using NSUnboldFontMask
returns YES
if
the font is not bold, NO
otherwise. Using NSUnitalicFontMask
returns YES
if
the font is not italic, NO
otherwise.
- (NSFontPanel *)fontPanel:(BOOL)createFlag
See Also: + sharedFontPanel (NSFontPanel) + sharedFontPanelExists (NSFontPanel), + setFontPanelFactory:
- (NSFont *)fontWithFamily:(NSString
*)family traits:(NSFontTraitMask)fontTraitMask weight:(int)weight size:(float)size
nil
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 NSBoldFontMask
.You specify fontTraitMask by combining these font trait mask values using the C bitwise OR operator:
NSBoldFontMask
NSCompressedFontMask
NSCondensedFontMask
NSExpandedFontMask
NSFixedPitchFontMask
NSItalicFontMask
NSNarrowFontMask
NSNonstandardCharacterSetFontMask
NSPosterFontMask
NSSmallCapsFontMask
NSUnboldFontMask
NSUnitalicFontMask
These pairs of traits are mutually exclusive:
NSCondensedFontMask
and NSExpandedFontMask
NSBoldFontMask
and NSUnboldFontMask
NSItalicFontMask
and NSUnitalicFontMask
Using NSUnboldFontMask
or NSUnitalicFontMask
loads
a font that doesn't have either the bold or italic trait, respectively.
- (BOOL)isEnabled
YES
if
the font-conversion system's user interface items (the Font Panel and
Font menu items) are enabled, NO
if
they're not.See Also: - isEnabled (NSFontPanel) - isEnabled (NSMenuItem), - setEnabled:
- (BOOL)isMultiple
YES
if
the last font selection recorded has multiple fonts, NO
if
it's a single font.See Also: - setSelectedFont:isMultiple:, - selectedFont
- (NSString *) localizedNameForFamily:(NSString
*)family face:(NSString
*)face
@"Times"
and @"Roman"
),
if one exists. The user's location is determined
from the user's NSLanguages default setting. The method also loads the
localized strings for the font, if they aren't already loaded. If face is nil
,
this method returns the font family only.
- (void)modifyFont:(id)sender
Sender's Tag | Method Used |
NSNoFontChangeAction |
None, the font is returned unchanged |
NSViaPanelFontAction |
The Font Panel's panelConvertFont: |
NSAddTraitFontAction |
convertFont:toHaveTrait: |
NSRemoveTraitFontAction |
convertFont:toNotHaveTrait: |
NSSizeUpFontAction |
convertFont:toSize: |
NSSizeDownFontAction |
convertFont:toSize: |
NSHeavierFontAction |
convertWeight:ofFont: |
NSLighterFontAction |
convertWeight:ofFont: |
See Also: - addFontTrait:, - removeFontTrait:, - modifyFontViaPanel:
- (void)modifyFontViaPanel:(id)sender
See Also: - addFontTrait:, - removeFontTrait:, - modifyFont:
- (void)orderFrontFontPanel:(id)sender
See Also: - fontPanel:, + setFontPanelFactory:
- (void)removeFontTrait:(id)sender
See Also: - addFontTrait:, - modifyFont:, - modifyFontViaPanel:
- (NSFont *)selectedFont
NSFontManager *fontManager = [NSFontManager sharedFontManager]; panelFont = [fontManager convertFont:[fontManager selectedFont]];
See Also: - isMultiple
- (BOOL)sendAction
YES
if
some object handled the changeFont: message, NO
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:
- (void)setAction:(SEL)aSelector
See Also: - action
- (void)setDelegate:(id)anObject
See Also: - delegate
- (void)setEnabled:(BOOL)flag
YES
they're
enabled; if flag is NO
they're
disabled.See Also: - setEnabled: (NSFontPanel), - isEnabled
- (void)setFontMenu:(NSMenu
*)aMenu
See Also: - fontMenu:
- (void)setSelectedFont:(NSFont
*)aFont isMultiple:(BOOL)flag
YES
,
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. It shouldn't invoke this method in the process of handling a changeFont: message, as this causes the font manager to lose the information necessary to effect the change. After all fonts have been converted, the font manager itself records the new selected font.
See Also: - selectedFont, - isMultiple
- (NSFontTraitMask)traitsOfFont:(NSFont
*)aFont
You specify fontTraitMask by combining these font trait mask values using the C bitwise OR operator:
NSBoldFontMask
NSCompressedFontMask
NSCondensedFontMask
NSExpandedFontMask
NSFixedPitchFontMask
NSItalicFontMask
NSNarrowFontMask
NSNonstandardCharacterSetFontMask
NSPosterFontMask
NSSmallCapsFontMask
NSCondensedFontMask
and NSExpandedFontMask
are
mutually exclusive.
- (int)weightOfFont:(NSFont
*)aFont
- (void)changeFont:(id)sender
See Also: - addFontTrait:, - convertFont:toHaveTrait:, - convertFont:toFace:, - convertFont:toFamily:, - convertFont:toNotHaveTrait:, - convertFont:toSize:, - convertWeight:ofFont:, - convertFont:, - removeFontTrait:, - modifyFontViaPanel:, - modifyFont:
- (BOOL)fontManager:(id)theFontManager willIncludeFont:(NSString
*)fontName
YES
, fontName is
listed; if the delegate returns NO
,
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.