NSFontDescriptor Class Reference

Inherits from	NSObject
Conforms to	NSCoding NSCopying NSObject (NSObject)
Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in OS X v10.3 and later.
Companion guide	Font Handling
Declared in	NSFontDescriptor.h

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

NSCoding

encodeWithCoder:
initWithCoder:

NSCopying

copyWithZone:

Tasks

Creating a Font Descriptor

Initializing a Font Descriptor

Finding Fonts

Querying a Font Descriptor

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

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

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

Declared In

NSFontDescriptor.h

Instance Methods

fontAttributes

Returns the receiver’s dictionary of attributes.

- (NSDictionary *)fontAttributes

Return Value

The attribute dictionary.

Availability

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

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

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

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

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

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

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

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

Availability

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

Availability

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

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

Declared In

NSFontDescriptor.h

pointSize

Returns the point size of the receiver.

- (CGFloat)pointSize

Return Value

The receiver’s point size.

Availability

Available in OS X v10.4 and later.

Declared In

NSFontDescriptor.h

postscriptName

Returns the PostScript name of the receiver.

- (NSString *)postscriptName

Return Value

The receiver’s Postscript name.

Availability

Available in OS X v10.4 and later.

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

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

Declared in NSFontDescriptor.h.

NSFontNameAttribute

An optional NSString object that specifies the font name.

Available in OS X v10.3 and later.

Declared in NSFontDescriptor.h.

NSFontFaceAttribute

An optional NSString object that specifies the font face.

Available in 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 OS X v10.3 and later.

Declared in NSFontDescriptor.h.

NSFontVisibleNameAttribute

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

Available in 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 OS X v10.3 and later.

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

Declared in NSFontDescriptor.h.

NSFontVariationAxisMinimumValueKey

The minimum axis value as an NSNumber object.

Available in OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVariationAxisMaximumValueKey

The maximum axis value as an NSNumber object.

Available in OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVariationAxisDefaultValueKey

The default axis value as an NSNumber object.

Available in OS X v10.4 and later.

Declared in NSFontDescriptor.h.

NSFontVariationAxisNameKey

The localized variation axis name.

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

Declared in NSFontDescriptor.h.

Availability

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

Declared in NSFontDescriptor.h.

NSFontBoldTrait

The font’s typestyle is boldface.

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

Declared in NSFontDescriptor.h.

NSFontVerticalTrait

The font uses vertical glyph variants and metrics.

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

Declared in NSFontDescriptor.h.

Declared In

NSFontDescriptor.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

NSFontDescriptor Class Reference

Overview

Adopted Protocols

Tasks

Creating a Font Descriptor

Initializing a Font Descriptor

Finding Fonts

Querying a Font Descriptor

Class Methods

fontDescriptorWithFontAttributes:

Parameters

Return Value

Availability

See Also

Declared In

fontDescriptorWithName:matrix:

Parameters

Return Value

Availability

See Also

Declared In

fontDescriptorWithName:size:

Parameters

Return Value

Availability

See Also

Declared In

Instance Methods

fontAttributes

Return Value

Availability

Declared In

fontDescriptorByAddingAttributes:

Parameters

Return Value

Availability

See Also

Declared In

fontDescriptorWithFace:

Parameters

Return Value

Availability

See Also

Declared In

fontDescriptorWithFamily:

Parameters

Return Value

Availability

See Also

Declared In

fontDescriptorWithMatrix:

Parameters

Return Value

Availability

See Also

Declared In

fontDescriptorWithSize:

Parameters

Return Value

Availability

See Also

Declared In

fontDescriptorWithSymbolicTraits:

Parameters

Return Value

Availability

See Also

Declared In

initWithFontAttributes:

Parameters

Return Value

Availability

See Also

Declared In

matchingFontDescriptorsWithMandatoryKeys:

Parameters

Return Value

Discussion

Availability

Declared In