Mac Developer Library

Developer

AppKit Framework Reference NSFontDescriptor Class Reference

Options
Deployment Target:

On This Page
Language:

NSFontDescriptor

NSFontDescriptor objects provide a mechanism to describe a font with a dictionary of attributes. This font descriptor can be used later to create or modify an NSFont object. OS X v10.4 and later provides a font matching capability, so that you can partially describe a font by creating a font descriptor with, for example, just a family name. You can then find all the available fonts on the system with a matching family name using matchingFontDescriptorsWithMandatoryKeys:. More...

Inheritance


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.3 and later.
  • Initializes and returns a new font descriptor with the specified attributes.

    Declaration

    Swift

    init(fontAttributes attributes: [NSObject : AnyObject]?)

    Objective-C

    - (instancetype)initWithFontAttributes:(NSDictionary *)attributes

    Parameters

    attributes

    The attributes for the new font descriptor. If nil, the font descriptor’s attribute dictionary will be empty.

    Return Value

    The new font descriptor.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns all the fonts available on the system whose specified attributes match those of the receiver.

    Declaration

    Swift

    func matchingFontDescriptorsWithMandatoryKeys(_ mandatoryKeys: NSSet?) -> [AnyObject]

    Objective-C

    - (NSArray *)matchingFontDescriptorsWithMandatoryKeys:(NSSet *)mandatoryKeys

    Parameters

    mandatoryKeys

    Keys that must be identical to be matched. Can be nil.

    Return Value

    The matching font descriptors. If the attribute value specified does not exist in the input dictionary or if there is no font that matches the given mandatory key values, an empty array is returned.

    Discussion

    For example, suppose there are two versions of a given font installed that differ in the number of glyphs covered (the new version has more glyphs). If you explicitly specify NSFontNameAttribute as the only mandatory key, then a font descriptor that specifies a font name and character set by default matches both versions, since the character set attribute is not used for matching. If you specify that font name and character set keys are mandatory, the returned array contains only the font that matches both keys.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns a normalized font descriptor whose specified attributes match those of the receiver.

    Declaration

    Swift

    func matchingFontDescriptorWithMandatoryKeys(_ mandatoryKeys: NSSet?) -> NSFontDescriptor?

    Objective-C

    - (NSFontDescriptor *)matchingFontDescriptorWithMandatoryKeys:(NSSet *)mandatoryKeys

    Parameters

    mandatoryKeys

    Keys that must be identical to be matched. Can be nil.

    Return Value

    The matching font descriptor. If there is no font that matches the given mandatory key values, returns nil.

    Discussion

    If more than one font matches the [NSFontNameAttribute, NSFontFamilyAttribute, NSFontVisibleNameAttribute, NSFontFaceAttribute] attributes, the list of font descriptors is filtered by the other mandatory keys, if any, and the top result that is returned is the same as the first element returned from matchingFontDescriptorsWithMandatoryKeys:.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the receiver’s dictionary of attributes.

    Declaration

    Swift

    var fontAttributes: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *fontAttributes

    Return Value

    The attribute dictionary.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the current transform matrix of the receiver.

    Declaration

    Swift

    @NSCopying var matrix: NSAffineTransform? { get }

    Objective-C

    @property(readonly, copy) NSAffineTransform *matrix

    Return Value

    The transform matrix.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – pointSize

  • Returns the font attribute specified by the given key.

    Declaration

    Swift

    func objectForKey(_ anAttribute: String) -> AnyObject?

    Objective-C

    - (id)objectForKey:(NSString *)anAttribute

    Parameters

    anAttribute

    The font attribute key.

    Return Value

    The font attribute corresponding to anAttribute. For valid values of anAttribute, see “Font Attributes”.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the point size of the receiver.

    Declaration

    Swift

    var pointSize: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat pointSize

    Return Value

    The receiver’s point size.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the PostScript name of the receiver.

    Declaration

    Swift

    var postscriptName: String? { get }

    Objective-C

    @property(readonly, copy) NSString *postscriptName

    Return Value

    The receiver’s Postscript name.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns a bit mask that describes the traits of the receiver.

    Declaration

    Swift

    var symbolicTraits: NSFontSymbolicTraits { get }

    Objective-C

    @property(readonly) NSFontSymbolicTraits symbolicTraits

    Return Value

    The receiver’s font traits.

    Discussion

    The traits describe the font’s characteristics—see NSFontSymbolicTraits.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

Data Types

  • NSFontSymbolicTraits symbolically describes stylistic aspects of a font.

    Declaration

    Swift

    typealias NSFontSymbolicTraits = UInt32

    Objective-C

    typedef uint32_t NSFontSymbolicTraits;

    Discussion

    The upper 16 bits is used to describe appearance of the font (see NSFontFamilyClass) whereas the lower 16 bits is used for typeface information (see “Typeface Information”). The font appearance information represented by the upper 16 bits can be used for stylistic font matching. The symbolic traits supersede the existing NSFontTraitMask type used by NSFontManager. The corresponding values are kept compatible between NSFontTraitMask and NSFontSymbolicTraits.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • These constants classify certain stylistic qualities of the font. These values correspond closely to the font class values in the OpenType OS/2 table. The class values are bundled in the upper four bits of the NSFontSymbolicTraits and can be accessed via NSFontFamilyClassMask. For more information about the specific meaning of each identifier, refer to the OpenType specification.

    Declaration

    Swift

    typealias NSFontFamilyClass = UInt32

    Objective-C

    enum { NSFontUnknownClass = 0 << 28, NSFontOldStyleSerifsClass = 1 << 28, NSFontTransitionalSerifsClass = 2 << 28, NSFontModernSerifsClass = 3 << 28, NSFontClarendonSerifsClass = 4 << 28, NSFontSlabSerifsClass = 5 << 28, NSFontFreeformSerifsClass = 7 << 28, NSFontSansSerifClass = 8 << 28, NSFontOrnamentalsClass = 9 << 28, NSFontScriptsClass = 10 << 28, NSFontSymbolicClass = 12 << 28 }; typedef uint32_t NSFontFamilyClass;

    Constants

    • NSFontUnknownClass

      NSFontUnknownClass

      The font has no design classification.

      Available in OS X v10.4 and later.

    • NSFontOldStyleSerifsClass

      NSFontOldStyleSerifsClass

      The font’s style is based on the Latin printing style of the 15th to 17th century.

      Available in OS X v10.4 and later.

    • NSFontTransitionalSerifsClass

      NSFontTransitionalSerifsClass

      The font’s style is based on the Latin printing style of the 18th to 19th century.

      Available in OS X v10.4 and later.

    • NSFontModernSerifsClass

      NSFontModernSerifsClass

      The font’s style is based on the Latin printing style of the 20th century.

      Available in OS X v10.4 and later.

    • NSFontClarendonSerifsClass

      NSFontClarendonSerifsClass

      The font’s style is a variation of the Oldstyle Serifs and the Transitional Serifs.

      Available in OS X v10.4 and later.

    • NSFontSlabSerifsClass

      NSFontSlabSerifsClass

      The font’s style is characterized by serifs with a square transition between the strokes and the serifs (no brackets).

      Available in OS X v10.4 and later.

    • NSFontFreeformSerifsClass

      NSFontFreeformSerifsClass

      The font’s style includes serifs, but it expresses a design freedom that does not generally fit within the other serif design classifications.

      Available in OS X v10.4 and later.

    • NSFontSansSerifClass

      NSFontSansSerifClass

      The font’s style includes most basic letter forms (excluding Scripts and Ornamentals) that do not have serifs on the strokes.

      Available in OS X v10.4 and later.

    • NSFontOrnamentalsClass

      NSFontOrnamentalsClass

      The font’s style includes highly decorated or stylized character shapes such as those typically used in headlines.

      Available in OS X v10.4 and later.

    • NSFontScriptsClass

      NSFontScriptsClass

      The font’s style is among those typefaces designed to simulate handwriting.

      Available in OS X v10.4 and later.

    • NSFontSymbolicClass

      NSFontSymbolicClass

      The font’s style is generally design independent, making it suitable for special characters (icons, dingbats, technical symbols, and so on) that may be used equally well with any font.

      Available in OS X v10.4 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • These font attributes are defined by NSFontDescriptor.

    Declaration

    Swift

    var NSFontFamilyAttribute: NSString! var NSFontNameAttribute: NSString! var NSFontFaceAttribute: NSString! var NSFontSizeAttribute: NSString! var NSFontVisibleNameAttribute: NSString! var NSFontMatrixAttribute: NSString! var NSFontVariationAttribute: NSString! var NSFontCharacterSetAttribute: NSString! var NSFontCascadeListAttribute: NSString! var NSFontTraitsAttribute: NSString! var NSFontFixedAdvanceAttribute: NSString! var NSFontFeatureSettingsAttribute: NSString!

    Objective-C

    NSString *NSFontFamilyAttribute; NSString *NSFontNameAttribute; NSString *NSFontFaceAttribute; NSString *NSFontSizeAttribute; NSString *NSFontVisibleNameAttribute; NSString *NSFontColorAttribute; NSString *NSFontMatrixAttribute; NSString *NSFontVariationAttribute; NSString *NSFontCharacterSetAttribute; NSString *NSFontCascadeListAttribute; NSString *NSFontTraitsAttribute; NSString *NSFontFixedAdvanceAttribute; NSString *NSFontFeatureSettingsAttribute

    Constants

    • NSFontFamilyAttribute

      NSFontFamilyAttribute

      An optional NSString object that specifies the font family.

      Available in OS X v10.3 and later.

    • NSFontNameAttribute

      NSFontNameAttribute

      An optional NSString object that specifies the font name.

      Available in OS X v10.3 and later.

    • NSFontFaceAttribute

      NSFontFaceAttribute

      An optional NSString object that specifies the font face.

      Available in OS X v10.3 and later.

    • NSFontSizeAttribute

      NSFontSizeAttribute

      An optional NSNumber object, containing a float value, that specifies the font size.

      Available in OS X v10.3 and later.

    • NSFontVisibleNameAttribute

      NSFontVisibleNameAttribute

      An optional NSString object that specifies the font’s visible name.

      Available in OS X v10.3 and later.

    • NSFontColorAttribute

      NSFontColorAttribute

      An optional NSData object that specifies the font color.

      Use NSForegroundColorAttributeName instead.

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.4.

    • NSFontMatrixAttribute

      NSFontMatrixAttribute

      An NSAffineTransform instance that specifies the font’s transformation matrix.

      The default value is the identity matrix.

      Available in OS X v10.4 and later.

    • NSFontVariationAttribute

      NSFontVariationAttribute

      An NSDictionary instance that describes the font’s variation axis.

      The default value is supplied by the font. See “Font Variation Axis Dictionary Keys” for dictionary keys.

      Available in OS X v10.4 and later.

    • NSFontCharacterSetAttribute

      NSFontCharacterSetAttribute

      An NSCharacterSet instance that represents the set of Unicode characters covered by the font.

      The default value is supplied by the font.

      Available in OS X v10.4 and later.

    • NSFontCascadeListAttribute

      NSFontCascadeListAttribute

      An NSArray instance—each member of the array is a sub-descriptor.

      The default value is the system default cascading list for user's locale.

      Available in OS X v10.4 and later.

    • NSFontTraitsAttribute

      NSFontTraitsAttribute

      An NSDictionary instance instance fully describing font traits.

      The default value is supplied by the font. See “Font Traits Dictionary Keys” for dictionary keys.

      Available in OS X v10.4 and later.

    • NSFontFixedAdvanceAttribute

      NSFontFixedAdvanceAttribute

      An NSNumber instance containing a float value that overrides the glyph advancement specified by the font.

      The default value is 0.0.

      Available in OS X v10.4 and later.

    • NSFontFeatureSettingsAttribute

      NSFontFeatureSettingsAttribute

      An array of dictionaries representing non-default font feature settings.

      Each dictionary contains NSFontFeatureTypeIdentifierKey and NSFontFeatureSelectorIdentifierKey.

      Available in OS X v10.5 and later.

    Discussion

    You can retrieve the values for these attributes using objectForKey:.

    Import Statement

  • The following constants can be used as keys to retrieve information about a font descriptor from its trait dictionary.

    Declaration

    Swift

    var NSFontSymbolicTrait: NSString! var NSFontWeightTrait: NSString! var NSFontWidthTrait: NSString! var NSFontSlantTrait: NSString!

    Objective-C

    NSString *NSFontSymbolicTrait; NSString *NSFontWeightTrait; NSString *NSFontWidthTrait; NSString *NSFontSlantTrait;

    Constants

    • NSFontSymbolicTrait

      NSFontSymbolicTrait

      The symbolic traits value as an NSNumber object.

      Available in OS X v10.4 and later.

    • NSFontWeightTrait

      NSFontWeightTrait

      The normalized weight value as an NSNumber object.

      The valid value range is from -1.0 to 1.0. The value of 0.0 corresponds to the regular or medium font weight.

      Available in OS X v10.4 and later.

    • NSFontWidthTrait

      NSFontWidthTrait

      The relative inter-glyph spacing value as an NSNumber object.

      The valid value range is from -1.0 to 1.0. The value of 0.0 corresponds to the regular glyph spacing.

      Available in OS X v10.4 and later.

    • NSFontSlantTrait

      NSFontSlantTrait

      The relative slant angle value as an NSNumber object.

      The valid value range is from -1.0 to 1.0. The value of 0.0 corresponds to 0 degree clockwise rotation from the vertical and 1.0 corresponds to 30 degrees clockwise rotation.

      Available in OS X v10.4 and later.

    Discussion

    These keys are used with NSFontTraitsAttribute.

    Import Statement

  • The following constants can be used as keys to retrieve information about a font descriptor from its variation axis dictionary.

    Declaration

    Swift

    var NSFontVariationAxisIdentifierKey: NSString! var NSFontVariationAxisMinimumValueKey: NSString! var NSFontVariationAxisMaximumValueKey: NSString! var NSFontVariationAxisDefaultValueKey: NSString! var NSFontVariationAxisNameKey: NSString!

    Objective-C

    NSString *NSFontVariationAxisIdentifierKey; NSString *NSFontVariationAxisMinimumValueKey; NSString *NSFontVariationAxisMaximumValueKey; NSString *NSFontVariationAxisDefaultValueKey; NSString *NSFontVariationAxisNameKey;

    Constants

    • NSFontVariationAxisIdentifierKey

      NSFontVariationAxisIdentifierKey

      The axis identifier value as an NSNumber object.

      Available in OS X v10.4 and later.

    • NSFontVariationAxisMinimumValueKey

      NSFontVariationAxisMinimumValueKey

      The minimum axis value as an NSNumber object.

      Available in OS X v10.4 and later.

    • NSFontVariationAxisMaximumValueKey

      NSFontVariationAxisMaximumValueKey

      The maximum axis value as an NSNumber object.

      Available in OS X v10.4 and later.

    • NSFontVariationAxisDefaultValueKey

      NSFontVariationAxisDefaultValueKey

      The default axis value as an NSNumber object.

      Available in OS X v10.4 and later.

    • NSFontVariationAxisNameKey

      NSFontVariationAxisNameKey

      The localized variation axis name.

      Available in OS X v10.4 and later.

    Discussion

    These keys are used with NSFontVariationAttribute.

    Import Statement

  • The following constants can be used as keys to retrieve information about a font descriptor from its feature dictionary.

    Declaration

    Swift

    var NSFontFeatureTypeIdentifierKey: NSString! var NSFontFeatureSelectorIdentifierKey: NSString!

    Objective-C

    NSString *NSFontFeatureTypeIdentifierKey; NSString *NSFontFeatureSelectorIdentifierKey;

    Constants

    • NSFontFeatureTypeIdentifierKey

      NSFontFeatureTypeIdentifierKey

      An NSNumber object specifying a font feature type such as ligature, character shape, and so on. See “Font Features“ in ATSUI Programming Guide for predefined feature types.

      Available in OS X v10.5 and later.

    • NSFontFeatureSelectorIdentifierKey

      NSFontFeatureSelectorIdentifierKey

      An NSNumber object specifying a font feature selector such as common ligature off, traditional character shape, and so on. See “Font Features“ in ATSUI Programming Guide for predefined feature selectors.

      Available in OS X v10.5 and later.

    Discussion

    These keys are used with NSFontFeatureSettingsAttribute.

    Import Statement

  • This constant is used to access NSFontFamilyClass values in the upper four bits of NSFontSymbolicTraits.

    Declaration

    Swift

    var NSFontFamilyClassMask: UInt32 { get }

    Objective-C

    enum { NSFontFamilyClassMask = 0xF0000000 };

    Constants

    • NSFontFamilyClassMask

      NSFontFamilyClassMask

      The font family class mask used to access NSFontFamilyClass values.

      Available in OS X v10.4 and later.

    Import Statement

  • Typeface information is specified by the lower 16 bits of NSFontSymbolicTraits using the following constants.

    Declaration

    Swift

    var NSFontItalicTrait: Int { get } var NSFontBoldTrait: Int { get } var NSFontExpandedTrait: Int { get } var NSFontCondensedTrait: Int { get } var NSFontMonoSpaceTrait: Int { get } var NSFontVerticalTrait: Int { get } var NSFontUIOptimizedTrait: Int { get }

    Objective-C

    enum { NSFontItalicTrait = (1 << 0), NSFontBoldTrait = (1 << 1), NSFontExpandedTrait = (1 << 5), NSFontCondensedTrait = (1 << 6), NSFontMonoSpaceTrait = (1 << 10), NSFontVerticalTrait = (1 << 11), NSFontUIOptimizedTrait = (1 << 12) };

    Constants

    • NSFontItalicTrait

      NSFontItalicTrait

      The font’s typestyle is italic.

      Available in OS X v10.4 and later.

    • NSFontBoldTrait

      NSFontBoldTrait

      The font’s typestyle is boldface.

      Available in OS X v10.4 and later.

    • NSFontExpandedTrait

      NSFontExpandedTrait

      The font’s typestyle is expanded. Expanded and condensed traits are mutually exclusive.

      Available in OS X v10.4 and later.

    • NSFontCondensedTrait

      NSFontCondensedTrait

      The font’s typestyle is condensed. Expanded and condensed traits are mutually exclusive.

      Available in OS X v10.4 and later.

    • NSFontMonoSpaceTrait

      NSFontMonoSpaceTrait

      The font uses fixed-pitch glyphs if available. The font may have multiple glyph advances (many CJK glyphs contain two spaces).

      Available in OS X v10.4 and later.

    • NSFontVerticalTrait

      NSFontVerticalTrait

      The font uses vertical glyph variants and metrics.

      Available in OS X v10.4 and later.

    • NSFontUIOptimizedTrait

      NSFontUIOptimizedTrait

      The font synthesizes appropriate attributes for user interface rendering, such as control titles, if necessary.

      Available in OS X v10.4 and later.

    Import Statement