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

Parameters

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.

Declaration

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

Note

If only one font matches the [NSFontNameAttribute, NSFontFamilyAttribute, NSFontVisibleNameAttribute, NSFontFaceAttribute] attributes, the matchingFontDescriptorWithMandatoryKeys: function returns that font without further filtering for the other mandatory attributes. (This result differs from the result the matchingFontDescriptorsWithMandatoryKeys: function would return.)

In other words, if there is exactly one match with the NSFontNameAttribute, NSFontFamilyAttribute, NSFontVisibleNameAttribute, NSFontFaceAttribute attributes, the matchingFontDescriptorWithMandatoryKeys: function always returns the font, even if the font doesn't match the other mandatory keys.

Availability

See Also

Data Types

Declaration

Swift

typealias NSFontSymbolicTraits = UInt32

Objective-C

typedefuint32_tNSFontSymbolicTraits;

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

Objective-C

@import AppKit;

Swift

import AppKit

Availability

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.

Constants

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.