Mac Developer Library

Developer

AppKit Framework Reference NSFontManager Class Reference

Options
Deployment Target:

On This Page
Language:

NSFontManager

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:

  1. NSFontManager *fontManager = [NSFontManager sharedFontManager];
  2. NSMenu *fontMenu = [fontManager fontMenu:YES];

You can then add the Font menu to your application’s main menu. After the Font menu is installed, your application automatically gains the functionality of both the Font menu and the Font panel.

Font collections are managed by NSFontManager.

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

    Declaration

    Swift

    class func sharedFontManager() -> NSFontManager

    Objective-C

    + (NSFontManager *)sharedFontManager

    Return Value

    The shared font manager.

    Availability

    Available in OS X v10.0 and later.

  • Sets the class object used to create the font manager to the given class.

    Declaration

    Swift

    class func setFontManagerFactory(_ factoryId: AnyClass?)

    Objective-C

    + (void)setFontManagerFactory:(Class)aClass

    Parameters

    aClass

    The new font manager factory class, which should be a subclass of NSFontManager.

    Discussion

    When the NSFontManager class object receives a sharedFontManager message, it creates an instance of aClass, if no instance already exists. Your font manager class should implement init as its designated initializer. The default font manager factory is NSFontManager.

    This method must be invoked before your application’s main nib file is loaded, such as in the application delegate’s applicationWillFinishLaunching: method.

    Availability

    Available in OS X v10.0 and later.

  • Sets the class used to create the Font panel to the given class.

    Declaration

    Swift

    class func setFontPanelFactory(_ factoryId: AnyClass?)

    Objective-C

    + (void)setFontPanelFactory:(Class)factoryId

    Parameters

    factoryId

    The new font panel factory class, which should be a subclass of NSFontPanel.

    Discussion

    Invoke this method before accessing the Font panel in any way, such as in the application delegate’s applicationWillFinishLaunching: method.

    Availability

    Available in OS X v10.0 and later.

  • The names of the fonts available in the system (not the NSFont objects themselves). (read-only)

    Declaration

    Swift

    var availableFonts: [String] { get }

    Objective-C

    @property(readonly, copy) NSArray <NSString *> *availableFonts

    Discussion

    Note that these fonts are in various system font directories.

    Availability

    Available in OS X v10.0 and later.

  • The names of the font families available in the system. (read-only)

    Declaration

    Swift

    var availableFontFamilies: [String] { get }

    Objective-C

    @property(readonly, copy) NSArray <NSString *> *availableFontFamilies

    Discussion

    Note that these fonts are in various system font directories.

    Availability

    Available in OS X v10.0 and later.

  • Returns the names of the fonts available in the system whose traits are described exactly by the given font trait mask (not the NSFont objects themselves).

    Declaration

    Swift

    func availableFontNamesWithTraits(_ someTraits: NSFontTraitMask) -> [String]?

    Objective-C

    - (NSArray<NSString *> *)availableFontNamesWithTraits:(NSFontTraitMask)fontTraitMask

    Parameters

    fontTraitMask

    The font traits for which to return font names. You specify the desired traits by combining the font trait mask values described in Constants using the C bitwise OR operator.

    Return Value

    The names of the corresponding fonts.

    Discussion

    These fonts are in various system font directories.

    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 NSUnitalicFontMask | NSUnboldFontMask.

    Availability

    Available in OS X v10.0 and later.

  • Returns an array with one entry for each available member of a font family.

    Declaration

    Swift

    func availableMembersOfFontFamily(_ fam: String) -> [[AnyObject]]?

    Objective-C

    - (NSArray<NSArray *> *)availableMembersOfFontFamily:(NSString *)family

    Parameters

    family

    The name of a font family, like one specified by the value of availableFontFamilies.

    Return Value

    The available members of family. See the following discussion for a specific description.

    Discussion

    Each entry of the returned NSArray is another NSArray with four members, as follows:

    • 0. The PostScript font name, as an NSString object.

    • 1. The part of the font name used in the font panel that’s not the font name, as an NSString object. This value is not localized—for example, "Roman", "Italic", or "Bold".

    • 2. The font’s weight, as an NSNumber.

    • 3. The font’s traits, as an NSNumber.

    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:

    1. (("Times-Roman", "Roman", 5, 4),
    2. ("Times-Italic", "Italic", 6, 5),
    3. ("Times-Bold", "Bold", 9, 2),
    4. ("Times-BoldItalic", "Bold Italic", 9, 3)
    5. )

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setSelectedFont(_ fontObj: NSFont, isMultiple flag: Bool)

    Objective-C

    - (void)setSelectedFont:(NSFont *)aFont isMultiple:(BOOL)flag

    Parameters

    aFont

    The font to set as selected.

    flag

    If YEStrue, the Font panel indicates that more than one font is contained in the selection; if NOfalse, it does not.

    Discussion

    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.

    Availability

    Available in OS X v10.0 and later.

  • The last font recorded. (read-only)

    Declaration

    Swift

    var selectedFont: NSFont? { get }

    Objective-C

    @property(readonly, strong) NSFont *selectedFont

    Discussion

    The value of this property is the last font recorded with a setSelectedFont:isMultiple: message.

    While fonts are being converted in response to a convertFont: message, you can determine the font selected in the Font panel like this:

    1. NSFontManager *fontManager = [NSFontManager sharedFontManager];
    2. panelFont = [fontManager convertFont:[fontManager.selectedFont]];

    Availability

    Available in OS X v10.0 and later.

    See Also

    multiple

  • A Boolean value that indicates if the last font selection recorded has multiple fonts. (read-only)

    Declaration

    Swift

    var multiple: Bool { get }

    Objective-C

    @property(getter=isMultiple, readonly) BOOL multiple

    Discussion

    When the value of this property is YEStrue, the last font selection recorded has multiple fonts; if the last font selection recorded is a single font, the value is NOfalse.

    Availability

    Available in OS X v10.0 and later.

  • sendAction sendAction Available in OS X v10.0 through OS X v10.10.3 Property

    A Boolean value that indicates if the font manager’s action message was handled. (read-only)

    Declaration

    Swift

    var sendAction: Bool { get }

    Objective-C

    @property(readonly) BOOL sendAction

    Discussion

    By default, the font manager’s action message is changeFont:. The value of this property is YEStrue if some object handled the changeFont: message or NOfalse if the message went unheard.

    Availability

    Available in OS X v10.0 through OS X v10.10.3.

    See Also

    action

  • Returns a localized string with the name of the specified font family and face, if one exists.

    Declaration

    Swift

    func localizedNameForFamily(_ family: String, face faceKey: String?) -> String

    Objective-C

    - (NSString *)localizedNameForFamily:(NSString *)family face:(NSString *)face

    Parameters

    family

    The font family, for example, @"Times".

    face

    The font face, for example, @"Roman".

    Return Value

    A localized string with the name of the specified font family and face, or, if face is nil, the font family only.

    Discussion

    The user’s locale 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.

    Availability

    Available in OS X v10.0 and later.

  • Attempts to load a font with the specified characteristics.

    Declaration

    Swift

    func fontWithFamily(_ family: String, traits traits: NSFontTraitMask, weight weight: Int, size size: CGFloat) -> NSFont?

    Objective-C

    - (NSFont *)fontWithFamily:(NSString *)family traits:(NSFontTraitMask)fontTraitMask weight:(NSInteger)weight size:(CGFloat)size

    Parameters

    family

    The generic name of the desired font, such as Times or Helvetica.

    fontTraitMask

    The font traits, specified by combining the font trait mask values described in Constants using the C bitwise OR operator. Using NSUnboldFontMask or NSUnitalicFontMask loads a font that doesn’t have either the bold or italic trait, respectively.

    weight

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

    size

    The point size of the desired font.

    Return Value

    A font with the specified characteristics if successful, or nil if not.

    Availability

    Available in OS X v10.0 and later.

  • Returns the traits of the given font.

    Declaration

    Swift

    func traitsOfFont(_ fontObj: NSFont) -> NSFontTraitMask

    Objective-C

    - (NSFontTraitMask)traitsOfFont:(NSFont *)aFont

    Parameters

    aFont

    The font whose traits are returned.

    Return Value

    The font traits, returned as a mask created by combining values listed in Constants with the C bitwise OR operator.

    Availability

    Available in OS X v10.0 and later.

  • Indicates whether the given font has all the specified traits.

    Declaration

    Swift

    func fontNamed(_ fName: String, hasTraits someTraits: NSFontTraitMask) -> Bool

    Objective-C

    - (BOOL)fontNamed:(NSString *)typeface hasTraits:(NSFontTraitMask)fontTraitMask

    Parameters

    typeface

    The name of the font.

    fontTraitMask

    The font traits to test, specified by combining the font trait mask values described in Constants using the C bitwise OR operator.

    Return Value

    YEStrue if the font named typeface has all the traits specified in fontTraitMask; NOfalse if it doesn’t.

    Discussion

    Using NSUnboldFontMask returns YEStrue if the font is not bold, NOfalse otherwise. Using NSUnitalicFontMask returns YEStrue if the font is not italic, NOfalse otherwise.

    Availability

    Available in OS X v10.0 and later.

  • Returns a rough numeric measure the weight of the given font.

    Declaration

    Swift

    func weightOfFont(_ fontObj: NSFont) -> Int

    Objective-C

    - (NSInteger)weightOfFont:(NSFont *)aFont

    Parameters

    aFont

    The font whose weight is returned.

    Return Value

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

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates if the font conversion system’s user interface items (the Font panel and Font menu items) are enabled.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(getter=isEnabled) BOOL enabled

    Discussion

    When the value of this property is YEStrue, the font conversion system’s user interface items (the Font panel and Font menu items) are enabled; when the value is NOfalse, these items are not enabled.

    Availability

    Available in OS X v10.0 and later.

    See Also

    isEnabled (NSFontPanel)
    isEnabled (NSMenuItem)

  • Requests permission from the Font panel delegate to display the given font name in the Font panel.

    Deprecation Statement

    Use NSFontCollection for providing filtered font lists.

    Declaration

    Swift

    func fontManager(_ sender: AnyObject, willIncludeFont fontName: String) -> Bool

    Objective-C

    - (BOOL)fontManager:(id)theFontManager willIncludeFont:(NSString *)fontName

    Discussion

    In OS X versions 10.2 and earlier, 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.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • Returns the application’s shared Font panel object, optionally creating it if necessary.

    Declaration

    Swift

    func fontPanel(_ create: Bool) -> NSFontPanel?

    Objective-C

    - (NSFontPanel *)fontPanel:(BOOL)createFlag

    Parameters

    createFlag

    If YEStrue, the Font panel object is created if necessary; if NOfalse, it is not.

    Return Value

    The application’s shared Font panel object.

    Availability

    Available in OS X v10.0 and later.

  • Records the given menu as the application’s Font menu.

    Declaration

    Swift

    func setFontMenu(_ newMenu: NSMenu)

    Objective-C

    - (void)setFontMenu:(NSMenu *)aMenu

    Parameters

    aMenu

    The new Font menu.

    Availability

    Available in OS X v10.0 and later.

    See Also

    – fontMenu:

  • Returns the menu that’s hooked up to the font conversion system, optionally creating it if necessary.

    Declaration

    Swift

    func fontMenu(_ create: Bool) -> NSMenu?

    Objective-C

    - (NSMenu *)fontMenu:(BOOL)createFlag

    Parameters

    createFlag

    If YEStrue, the menu object is created if necessary; if NOfalse, it is not.

    Return Value

    The font conversion system menu.

    Availability

    Available in OS X v10.0 and later.

  • delegate delegate (OS X v10.11) Property

    The font manager’s delegate.

    Deprecation Statement

    There is no font manager delegate; don’t use this property.

    Declaration

    Swift

    unowned(unsafe) var delegate: AnyObject?

    Objective-C

    @property(assign) id delegate

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

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

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    Discussion

    The default action is changeFont:. You should rarely need to change this setting.

    Availability

    Available in OS X v10.0 and later.

  • The target for the action associated with the sendAction property.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    Availability

    Available in OS X v10.5 and later.

Data Types

  • Mask of traits assigned to a font, assigned using the values in “Font traits”.

    Declaration

    Swift

    struct NSFontTraitMask : OptionSetType { init(rawValue rawValue: UInt) static var ItalicFontMask: NSFontTraitMask { get } static var BoldFontMask: NSFontTraitMask { get } static var UnboldFontMask: NSFontTraitMask { get } static var NonStandardCharacterSetFontMask: NSFontTraitMask { get } static var NarrowFontMask: NSFontTraitMask { get } static var ExpandedFontMask: NSFontTraitMask { get } static var CondensedFontMask: NSFontTraitMask { get } static var SmallCapsFontMask: NSFontTraitMask { get } static var PosterFontMask: NSFontTraitMask { get } static var CompressedFontMask: NSFontTraitMask { get } static var FixedPitchFontMask: NSFontTraitMask { get } static var UnitalicFontMask: NSFontTraitMask { get } }

    Objective-C

    typedef unsigned int NSFontTraitMask;

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants specify what action modifyFont: will take.

    Declaration

    Swift

    enum NSFontAction : UInt { case NoFontChangeAction case ViaPanelFontAction case AddTraitFontAction case SizeUpFontAction case SizeDownFontAction case HeavierFontAction case LighterFontAction case RemoveTraitFontAction }

    Objective-C

    typedef enum _NSFontAction { NSNoFontChangeAction = 0, NSViaPanelFontAction = 1, NSAddTraitFontAction = 2, NSSizeUpFontAction = 3, NSSizeDownFontAction = 4, NSHeavierFontAction = 5, NSLighterFontAction = 6, NSRemoveTraitFontAction = 7 } NSFontAction;

    Constants

    • NoFontChangeAction

      NSNoFontChangeAction

      No action; the font is returned unchanged.

      Available in OS X v10.0 and later.

    • ViaPanelFontAction

      NSViaPanelFontAction

      Converts the font according to the NSFontPanel method panelConvertFont:.

      Available in OS X v10.0 and later.

    • AddTraitFontAction

      NSAddTraitFontAction

      Converts the font to have an additional trait using convertFont:toHaveTrait:.

      Available in OS X v10.0 and later.

    • SizeUpFontAction

      NSSizeUpFontAction

      Converts the font to a larger size using convertFont:toSize:.

      Available in OS X v10.0 and later.

    • SizeDownFontAction

      NSSizeDownFontAction

      Converts the font to a smaller size using convertFont:toSize:.

      Available in OS X v10.0 and later.

    • HeavierFontAction

      NSHeavierFontAction

      Converts the font to a heavier weight using convertWeight:ofFont:.

      Available in OS X v10.0 and later.

    • LighterFontAction

      NSLighterFontAction

      Converts the font to a lighter weight using convertWeight:ofFont:.

      Available in OS X v10.0 and later.

    • RemoveTraitFontAction

      NSRemoveTraitFontAction

      Converts the font to remove a trait using convertFont:toNotHaveTrait:.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • This constant specifies options accepted by addCollection:options:.

    Declaration

    Swift

    struct NSFontCollectionOptions : OptionSetType { init(rawValue rawValue: UInt) static var ApplicationOnlyMask: NSFontCollectionOptions { get } }

    Objective-C

    enum { NSFontCollectionApplicationOnlyMask = 1 << 0 };

    Constants

    • ApplicationOnlyMask

      NSFontCollectionApplicationOnlyMask

      Makes the collection available only to the application. This option is not yet implemented.

      Available in OS X v10.3 and later.

  • Font traits defined and supported by NSFontManager.

    Declaration

    Swift

    struct NSFontTraitMask : OptionSetType { init(rawValue rawValue: UInt) static var ItalicFontMask: NSFontTraitMask { get } static var BoldFontMask: NSFontTraitMask { get } static var UnboldFontMask: NSFontTraitMask { get } static var NonStandardCharacterSetFontMask: NSFontTraitMask { get } static var NarrowFontMask: NSFontTraitMask { get } static var ExpandedFontMask: NSFontTraitMask { get } static var CondensedFontMask: NSFontTraitMask { get } static var SmallCapsFontMask: NSFontTraitMask { get } static var PosterFontMask: NSFontTraitMask { get } static var CompressedFontMask: NSFontTraitMask { get } static var FixedPitchFontMask: NSFontTraitMask { get } static var UnitalicFontMask: NSFontTraitMask { get } }

    Objective-C

    enum { NSItalicFontMask = 0x00000001, NSBoldFontMask = 0x00000002, NSUnboldFontMask = 0x00000004, NSNonStandardCharacterSetFontMask = 0x00000008, NSNarrowFontMask = 0x00000010, NSExpandedFontMask = 0x00000020, NSCondensedFontMask = 0x00000040, NSSmallCapsFontMask = 0x00000080, NSPosterFontMask = 0x00000100, NSCompressedFontMask = 0x00000200, NSFixedPitchFontMask = 0x00000400, NSUnitalicFontMask = 0x01000000 };

    Constants

    • ItalicFontMask

      NSItalicFontMask

      A mask that specifies an italic font.

      Available in OS X v10.0 and later.

    • BoldFontMask

      NSBoldFontMask

      A mask that specifies a bold font.

      Available in OS X v10.0 and later.

    • UnboldFontMask

      NSUnboldFontMask

      A mask that specifies a font that is not bold.

      Available in OS X v10.0 and later.

    • NonStandardCharacterSetFontMask

      NSNonStandardCharacterSetFontMask

      A mask that specifies a font that uses a non-standard character set.

      Available in OS X v10.0 and later.

    • NarrowFontMask

      NSNarrowFontMask

      A mask that specifies a narrow font.

      Available in OS X v10.0 and later.

    • ExpandedFontMask

      NSExpandedFontMask

      A mask that specifies an expanded font.

      Available in OS X v10.0 and later.

    • CondensedFontMask

      NSCondensedFontMask

      A mask that specifies a condensed font.

      Available in OS X v10.0 and later.

    • SmallCapsFontMask

      NSSmallCapsFontMask

      A mask that specifies a small-caps font.

      Available in OS X v10.0 and later.

    • PosterFontMask

      NSPosterFontMask

      A mask that specifies a poster-style font.

      Available in OS X v10.0 and later.

    • CompressedFontMask

      NSCompressedFontMask

      A mask that specifies a compressed font.

      Available in OS X v10.0 and later.

    • FixedPitchFontMask

      NSFixedPitchFontMask

      A mask that specifies a fixed pitch font.

      Available in OS X v10.0 and later.

    • UnitalicFontMask

      NSUnitalicFontMask

      A mask that specifies a font that is not italic.

      Available in OS X v10.0 and later.

    Discussion

    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.

    These pairs of traits are mutually exclusive:

    • NSCondensedFontMask and NSExpandedFontMask

    • NSBoldFontMask and NSUnboldFontMask

    • NSItalicFontMask and NSUnitalicFontMask