NSFontDescriptor Class Reference

Inherits from
Conforms to
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
NSCopying

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