---

NSFontDescriptor Class Reference

Overview

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

There are several ways to create a new NSFontDescriptor object. You can use alloc and initWithFontAttributes:, fontDescriptorWithFontAttributes:, fontDescriptorWithName:matrix:, or fontDescriptorWithName:size:. to create a font descriptor based on either your custom attributes dictionary or on a specific font’s name and size. Alternatively you can use one of the fontDescriptor… instance methods (such as fontDescriptorWithFace:) to create a modified version of an existing descriptor. The latter methods are useful if you have an existing descriptor and simply want to change one aspect.

All attributes in the attributes dictionary are optional.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

Tasks

Creating a Font Descriptor

• + fontDescriptorWithFontAttributes:
• + fontDescriptorWithName:matrix:
• + fontDescriptorWithName:size:
• – fontDescriptorByAddingAttributes:
• – fontDescriptorWithFace:
• – fontDescriptorWithFamily:
• – fontDescriptorWithMatrix:
• – fontDescriptorWithSize:
• – fontDescriptorWithSymbolicTraits:

Initializing a Font Descriptor

• – initWithFontAttributes:

Finding Fonts

• – matchingFontDescriptorsWithMandatoryKeys:
• – matchingFontDescriptorWithMandatoryKeys:

Querying a Font Descriptor

• – fontAttributes
• – matrix
• – objectForKey:
• – pointSize
• – postscriptName
• – symbolicTraits

Class Methods

fontDescriptorWithFontAttributes:

Returns a font descriptor with a dictionary of attributes.

+ (NSFontDescriptor *)fontDescriptorWithFontAttributes:(NSDictionary *)attributes

Parameters

attributes

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

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + fontDescriptorWithName:matrix:
• + fontDescriptorWithName:matrix:

Declared In

NSFontDescriptor.h

fontDescriptorWithName:matrix:

Returns a font descriptor with the NSFontNameAttribute and NSFontMatrixAttribute dictionary attributes set to the given values.

+ (NSFontDescriptor *)fontDescriptorWithName:(NSString *)fontName matrix:(NSAffineTransform *)matrix

Parameters

fontName

The value for NSFontNameAttribute.

matrix

The value for NSFontMatrixAttribute.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:
• + fontDescriptorWithName:size:

Declared In

NSFontDescriptor.h

fontDescriptorWithName:size:

Returns a font descriptor with the NSFontNameAttribute and NSFontSizeAttribute dictionary attributes set to the given values.

+ (NSFontDescriptor *)fontDescriptorWithName:(NSString *)fontName size:(CGFloat)size

Parameters

fontName

The value for NSFontNameAttribute.

size

The value for NSFontSizeAttribute.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + fontDescriptorWithFontAttributes:
• + fontDescriptorWithName:matrix:

Declared In

NSFontDescriptor.h

Instance Methods

fontAttributes

Returns the receiver’s dictionary of attributes.

- (NSDictionary *)fontAttributes

Return Value

The attribute dictionary.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSFontDescriptor.h

fontDescriptorByAddingAttributes:

Returns a new font descriptor that is the same as the receiver but with the specified attributes taking precedence over the existing ones.

- (NSFontDescriptor *)fontDescriptorByAddingAttributes:(NSDictionary *)attributes

Parameters

attributes

The new attributes.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:

Declared In

NSFontDescriptor.h

fontDescriptorWithFace:

Returns a new font descriptor that is the same as the receiver but with the specified face.

- (NSFontDescriptor *)fontDescriptorWithFace:(NSString *)newFace

Parameters

newFace

The new font face.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:

Declared In

NSFontDescriptor.h

fontDescriptorWithFamily:

Returns a new font descriptor whose attributes are the same as the receiver but from the specified family.

- (NSFontDescriptor *)fontDescriptorWithFamily:(NSString *)newFamily

Parameters

newFamily

The new font family.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:

Declared In

NSFontDescriptor.h

fontDescriptorWithMatrix:

Returns a new font descriptor that is the same as the receiver but with the specified matrix.

- (NSFontDescriptor *)fontDescriptorWithMatrix:(NSAffineTransform *)matrix

Parameters

matrix

The new font matrix.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:

Declared In

NSFontDescriptor.h

fontDescriptorWithSize:

Returns a new font descriptor that is the same as the receiver but with the specified point size.

- (NSFontDescriptor *)fontDescriptorWithSize:(CGFloat)newPointSize

Parameters

newPointSize

The new point size.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:

Declared In

NSFontDescriptor.h

fontDescriptorWithSymbolicTraits:

Returns a new font descriptor that is the same as the receiver but with the specified symbolic traits taking precedence over the existing ones.

- (NSFontDescriptor *)fontDescriptorWithSymbolicTraits:(NSFontSymbolicTraits)symbolicTraits

Parameters

symbolicTraits

The new symbolic traits.

Return Value

The new font descriptor.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:

Declared In

NSFontDescriptor.h

initWithFontAttributes:

Initializes and returns a new font descriptor with the specified attributes.

- (id)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.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + fontDescriptorWithFontAttributes:

Declared In

NSFontDescriptor.h

matchingFontDescriptorsWithMandatoryKeys:

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

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

Parameters

mandatoryKeys

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

Return Value

The matching font descriptors.

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). A font descriptor that specifies a font name and character set by default matches both versions, since the character set attribute is not usually 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.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSFontDescriptor.h

matchingFontDescriptorWithMandatoryKeys:

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

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

Parameters

mandatoryKeys

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

Return Value

The matching font descriptor.

Discussion

The returned font descriptor is the first element returned from matchingFontDescriptorsWithMandatoryKeys:.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSFontDescriptor.h

matrix

Returns the current transform matrix of the receiver.

- (NSAffineTransform *)matrix

Return Value

The transform matrix.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – pointSize

Declared In

NSFontDescriptor.h

objectForKey:

Returns the font attribute specified by the given key.

- (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”.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + fontDescriptorWithFontAttributes:
• – fontAttributes
• – symbolicTraits

Declared In

NSFontDescriptor.h

pointSize

Returns the point size of the receiver.

- (CGFloat)pointSize

Return Value

The receiver’s point size.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – fontAttributes
• – matrix

Declared In

NSFontDescriptor.h

postscriptName

Returns the PostScript name of the receiver.

- (NSString *)postscriptName

Return Value

The receiver’s Postscript name.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – fontAttributes
• – symbolicTraits

Declared In

NSFontDescriptor.h

symbolicTraits

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

- (NSFontSymbolicTraits)symbolicTraits

Return Value

The receiver’s font traits.

Discussion

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – fontAttributes
• – postscriptName

Declared In

NSFontDescriptor.h

Constants

Font Attributes

These font attributes are defined by NSFontDescriptor.

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

An optional NSString object that specifies the font family.

Available in Mac OS X v10.3 and later.

Declared in NSFontDescriptor.h.

NSFontNameAttribute

An optional NSString object that specifies the font name.

Available in Mac OS X v10.3 and later.

Declared in NSFontDescriptor.h.

NSFontFaceAttribute

An optional NSString object that specifies the font face.

Available in Mac OS X v10.3 and later.

Declared in NSFontDescriptor.h.

NSFontSizeAttribute

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

Available in Mac OS X v10.3 and later.

Declared in NSFontDescriptor.h.

NSFontVisibleNameAttribute

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

Available in Mac OS X v10.3 and later.

Declared in NSFontDescriptor.h.

NSFontColorAttribute

An optional NSData object that specifies the font color. (Deprecated. Use NSForegroundColorAttributeName instead.)

Available in Mac OS X v10.3 and later.

Deprecated in Mac OS X v10.4.

Declared in NSFontDescriptor.h.

NSFontMatrixAttribute

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

The default value is the identity matrix.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontFeatureSettingsAttribute

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

Each dictionary contains NSFontFeatureTypeIdentifierKey and NSFontFeatureSelectorIdentifierKey.

Available in Mac OS X v10.5 and later.

Declared in NSFontDescriptor.h.

Discussion

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

Declared In

NSFontDescriptor.h

Font Traits Dictionary Keys

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

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

Constants

NSFontSymbolicTrait

The symbolic traits value as an NSNumber object.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

Discussion

These keys are used with NSFontTraitsAttribute.

Declared In

NSFontDescriptor.h

Font Variation Axis Dictionary Keys

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

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

Constants

NSFontVariationAxisIdentifierKey

The axis identifier value as an NSNumber object.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVariationAxisMinimumValueKey

The minimum axis value as an NSNumber object.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVariationAxisMaximumValueKey

The maximum axis value as an NSNumber object.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVariationAxisDefaultValueKey

The default axis value as an NSNumber object.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVariationAxisNameKey

The localized variation axis name.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

Discussion

These keys are used with NSFontVariationAttribute.

Declared In

NSFontDescriptor.h

Font Feature Keys

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

NSString *NSFontFeatureTypeIdentifierKey;
NSString *NSFontFeatureSelectorIdentifierKey;

Constants

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 Mac OS X v10.5 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.5 and later.

Declared in NSFontDescriptor.h.

Discussion

These keys are used with NSFontFeatureSettingsAttribute.

Declared In

NSFontDescriptor.h

NSFontSymbolicTraits

NSFontSymbolicTraits symbolically describes stylistic aspects of a font.

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.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSFontDescriptor.h

NSFontFamilyClass

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.

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

The font has no design classification.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontOldStyleSerifsClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontTransitionalSerifsClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontModernSerifsClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontClarendonSerifsClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontSlabSerifsClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontSansSerifClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontOrnamentalsClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontScriptsClass

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

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 Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSFontDescriptor.h

NSFontFamilyClassMask

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

enum {
   NSFontFamilyClassMask = 0xF0000000
};

Constants

NSFontFamilyClassMask

The font family class mask used to access NSFontFamilyClass values.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

Typeface Information

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

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

Constants

NSFontItalicTrait

The font’s typestyle is italic.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontBoldTrait

The font’s typestyle is boldface.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontExpandedTrait

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontCondensedTrait

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontMonoSpaceTrait

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVerticalTrait

The font uses vertical glyph variants and metrics.

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontUIOptimizedTrait

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

Available in Mac OS X v10.4 and later.

Declared in NSFontDescriptor.h.

Declared In

NSFontDescriptor.h

---