- Inherits from:
- NSObject
- Package:
- com.apple.yellow.application
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.
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.
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.
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.
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.
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).
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 |
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
The constants specify what action modifyFont will take:
NoFontChangeAction
ViaPanelFontAction
AddTraitFontAction
RemoveTraitFontAction
SizeUpFontAction
SizeDownFontAction
HeavierFontAction
LighterFontAction
- 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
public NSFontManager()
public static NSFontManager sharedFontManager()
See Also: setFontManagerFactory:
public NSSelector action()
See Also: setAction
public void addFontTrait(Object sender)
See Also: removeFontTrait, modifyFont, modifyFontViaPanel
public NSArray availableFontFamilies()
See Also: availableFontNamesWithTraits, availableFonts
public NSArray availableFontNamesWithTraits(int fontTraitMask)
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
public NSArray availableFonts()
See Also: availableFontFamilies, availableFontNamesWithTraits
public 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: convertFontToFace, convertFontToFamily, convertFontToHaveTrait, convertFontToNotHaveTrait, convertFontToSize, convertWeight
public NSFont convertFontToFace(
NSFont aFont,
String 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: convertFontToFamily, convertFontToHaveTrait, convertFontToNotHaveTrait, convertFontToSize, convertWeight, convertFont
public NSFont convertFontToFamily(
NSFont aFont,
String 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: convertFontToFace, convertFontToHaveTrait, convertFontToNotHaveTrait, convertFontToSize, convertWeight, convertFont
public NSFont convertFontToHaveTrait(
NSFont aFont,
int fontTrait)
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
public NSFont convertFontToNotHaveTrait(
NSFont aFont,
int fontTraitMask)
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
public NSFont convertFontToSize(
NSFont aFont,
float size)
See Also: convertFontToFace, convertFontToFamily, convertFontToHaveTrait, convertFontToNotHaveTrait, convertWeight, convertFont
public NSFont convertWeight(
boolean increaseFlag,
NSFont aFont)
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
public Object delegate()
See Also: setDelegate
public NSMenu fontMenu(boolean createFlag)
true
.See Also: setFontMenu
public boolean fontWithNameHasTraits(
String typeface,
int fontTraitMask)
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.
public NSFontPanel fontPanel(boolean createFlag)
See Also: sharedFontPanel (NSFontPanel), sharedFontPanelExists (NSFontPanel)
public NSFont fontWithFamily(
String family,
int fontTraitMask,
int weight,
float size)
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.
public boolean isEnabled()
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
public boolean isMultiple()
true
if
the last font selection recorded has multiple fonts, false
if
it's a single font.See Also: setSelectedFont, selectedFont
public String localizedNameForFamily(
String family,
String face)
"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.
public void modifyFont(Object sender)
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
public void modifyFontViaPanel(Object sender)
See Also: addFontTrait, removeFontTrait, modifyFont
public void orderFrontFontPanel(Object sender)
See Also: fontPanel, setFontPanelFactory:
public void removeFontTrait(Object sender)
See Also: addFontTrait, modifyFont, modifyFontViaPanel
public NSFont selectedFont()
NSFontManager fontManager = NSFontManager.sharedFontManager(); panelFont = fontManager.convertFont(fontManager.selectedFont());
See Also: isMultiple
public boolean sendAction()
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
public void setAction(NSSelector aSelector)
See Also: action
public void setDelegate(Object anObject)
See Also: delegate
public void setEnabled(boolean flag)
true
they're
enabled; if flag is false
they're
disabled.See Also: setEnabled (NSFontPanel), isEnabled
public void setFontMenu(NSMenu aMenu)
See Also: fontMenu
public void setSelectedFont(
NSFont aFont,
boolean flag)
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
public int traitsOfFont(NSFont aFont)
You specify fontTraitMask by combining the font trait mask values described in "Constants" using the C bitwise OR operator.
public int weightOfFont(NSFont aFont)
public abstract boolean fontManagerWillIncludeFont(
Object theFontManager,
String fontName)
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.