UIFontDescriptor Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
UIFontDescriptor.h

Overview

UIFontDescriptor objects provide a mechanism to describe a font with a dictionary of attributes. This font descriptor can be used later to create or modify a UIFont object. Font descriptors can be archived and unarchived. Font descriptors have 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 UIFontDescriptor object. To take advantage of text styles and respect the user’s current content size category, use preferredFontDescriptorWithTextStyle:. You can also 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 receiver). 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.

Tasks

Creating a Font Descriptor

Initializing a Font Descriptor

Finding Fonts

Querying a Font Descriptor

Properties

matrix

The current transform matrix of the receiver. (read-only)

@property(nonatomic, readonly) CGAffineTransform matrix
Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

pointSize

The point size of the receiver. (read-only)

@property(nonatomic, readonly) CGFloat pointSize
Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

postscriptName

The PostScript name of the receiver. (read-only)

@property(nonatomic, readonly) NSString *postscriptName
Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

symbolicTraits

A bit mask that describes the traits of the receiver. (read-only)

@property(nonatomic, readonly) UIFontDescriptorSymbolicTraits symbolicTraits
Discussion

The traits describe the font’s characteristics—see “Symbolic Font Traits”.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

Class Methods

fontDescriptorWithFontAttributes:

Returns a font descriptor with a dictionary of attributes.

+ (UIFontDescriptor *)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 iOS 7.0 and later.
Declared In
UIFontDescriptor.h

fontDescriptorWithName:matrix:

Returns a font descriptor with the UIFontDescriptorNameAttribute and UIFontDescriptorMatrixAttribute dictionary attributes set to the given values.

+ (UIFontDescriptor *)fontDescriptorWithName:(NSString *)fontName matrix:(CGAffineTransform)matrix
Parameters
fontName

The value for UIFontDescriptorNameAttribute.

matrix

The value for UIFontDescriptorMatrixAttribute.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

fontDescriptorWithName:size:

Returns a font descriptor with the UIFontDescriptorNameAttribute and UIFontDescriptorSizeAttribute dictionary attributes set to the given values.

+ (UIFontDescriptor *)fontDescriptorWithName:(NSString *)fontName size:(CGFloat)size
Parameters
fontName

The value for UIFontDescriptorNameAttribute.

size

The value for UIFontDescriptorSizeAttribute.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

preferredFontDescriptorWithTextStyle:

Returns a font descriptor containing the given text style and the user's selected content size category.

+ (UIFontDescriptor *)preferredFontDescriptorWithTextStyle:(NSString *)style
Parameters
style

The text style for which to return a font descriptor. See “Text Styles” for valid values.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

Instance Methods

fontAttributes

Returns the receiver’s dictionary of attributes.

- (NSDictionary *)fontAttributes
Return Value

The attribute dictionary.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.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.

- (UIFontDescriptor *)fontDescriptorByAddingAttributes:(NSDictionary *)attributes
Parameters
attributes

The new attributes.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

fontDescriptorWithFace:

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

- (UIFontDescriptor *)fontDescriptorWithFace:(NSString *)newFace
Parameters
newFace

The new font face.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

fontDescriptorWithFamily:

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

- (UIFontDescriptor *)fontDescriptorWithFamily:(NSString *)newFamily
Parameters
newFamily

The new font family.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

fontDescriptorWithMatrix:

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

- (UIFontDescriptor *)fontDescriptorWithMatrix:(CGAffineTransform)matrix
Parameters
matrix

The new font matrix.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

fontDescriptorWithSize:

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

- (UIFontDescriptor *)fontDescriptorWithSize:(CGFloat)newPointSize
Parameters
newPointSize

The new point size.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.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.

- (UIFontDescriptor *)fontDescriptorWithSymbolicTraits:(UIFontDescriptorSymbolicTraits)symbolicTraits
Parameters
symbolicTraits

The new symbolic traits.

Return Value

The new font descriptor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

initWithFontAttributes:

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

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

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.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 UIFontDescriptorNameAttribute 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 iOS 7.0 and later.
Declared In
UIFontDescriptor.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 iOS 7.0 and later.
Declared In
UIFontDescriptor.h

Constants

Text Styles

These constants provide semantic descriptions of the intended use for a font returned by the UIFont class method preferredFontForTextStyle: or a font descriptor returned by preferredFontDescriptorWithTextStyle:.

NSString *const UIFontTextStyleHeadline;
NSString *const UIFontTextStyleSubheadline;
NSString *const UIFontTextStyleBody;
NSString *const UIFontTextStyleFootnote;
NSString *const UIFontTextStyleCaption1;
NSString *const UIFontTextStyleCaption2;
Constants
UIFontTextStyleHeadline

The font used for headings.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontTextStyleSubheadline

The font used for subheadings.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontTextStyleBody

The font used for body text.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontTextStyleFootnote

The font used in footnotes.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontTextStyleCaption1

The font used for standard captions.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontTextStyleCaption2

The font used for alternate captions.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

Symbolic Font Traits

UIFontDescriptorSymbolicTraits symbolically describes stylistic aspects of a font. The lower 16 bits represent the typeface, and the upper 16 bits describe appearance of the font.

typedef enum : uint32_t {
   /* Typeface info (lower 16 bits of UIFontDescriptorSymbolicTraits) */
   UIFontDescriptorTraitItalic = 1u << 0,
   UIFontDescriptorTraitBold = 1u << 1,
   UIFontDescriptorTraitExpanded = 1u << 5,
   UIFontDescriptorTraitCondensed = 1u << 6,
   UIFontDescriptorTraitMonoSpace = 1u << 10,
   UIFontDescriptorTraitVertical = 1u << 11,
   UIFontDescriptorTraitUIOptimized = 1u << 12,
   UIFontDescriptorTraitTightLeading = 1u << 15,
   UIFontDescriptorTraitLooseLeading = 1u << 16,
   
   /* Font appearance info (upper 16 bits of UIFontDescriptorSymbolicTraits */
   UIFontDescriptorClassMask = 0xF0000000,
   
   UIFontDescriptorClassUnknown = 0u << 28,
   UIFontDescriptorClassOldStyleSerifs = 1u << 28,
   UIFontDescriptorClassTransitionalSerifs = 2u << 28,
   UIFontDescriptorClassModernSerifs = 3u << 28,
   UIFontDescriptorClassClarendonSerifs = 4u << 28,
   UIFontDescriptorClassSlabSerifs = 5u << 28,
   UIFontDescriptorClassFreeformSerifs = 7u << 28,
   UIFontDescriptorClassSansSerif = 8u << 28,
   UIFontDescriptorClassOrnamentals = 9u << 28,
   UIFontDescriptorClassScripts = 10u << 28,
   UIFontDescriptorClassSymbolic = 12u << 28
} UIFontDescriptorSymbolicTraits;
Constants
UIFontDescriptorTraitItalic

The font’s typestyle is italic.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitBold

The font’s typestyle is boldface.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitExpanded

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitCondensed

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitMonoSpace

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitVertical

The font uses vertical glyph variants and metrics.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitUIOptimized

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitTightLeading

The font uses tighter leading values.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitLooseLeading

The font uses looser leading values.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassMask

The font family class mask used to access UIFontDescriptorClass values.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassUnknown

The font has no design classification.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassOldStyleSerifs

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassTransitionalSerifs

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassModernSerifs

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassClarendonSerifs

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassSlabSerifs

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassFreeformSerifs

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 iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassSansSerif

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassOrnamentals

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassScripts

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorClassSymbolic

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 iOS 7.0 and later.

Declared in UIFontDescriptor.h.

Discussion

The font appearance information represented by the upper 16 bits of NSFontSymbolicTraits can be used for stylistic font matching. UIFontDescriptorClass constants classify certain stylistic qualities of the font.

Font Descriptor Class

UIFontDescriptorClass classifies certain stylistic qualities of the font.

typedef NSUInteger UIFontDescriptorClass;
Discussion

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 UIFontDescriptorSymbolicTraits and can be accessed via UIFontDescriptorClassMask. For additional information about the specific meaning of each identifier, refer to the OpenType specification.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIFontDescriptor.h

Font Attributes

These font attributes are defined by UIFontDescriptor.

NSString *const UIFontDescriptorFamilyAttribute;
NSString *const UIFontDescriptorNameAttribute;
NSString *const UIFontDescriptorFaceAttribute;
NSString *const UIFontDescriptorSizeAttribute;
NSString *const UIFontDescriptorVisibleNameAttribute;
NSString *const UIFontDescriptorMatrixAttribute;
NSString *const UIFontDescriptorCharacterSetAttribute;
NSString *const UIFontDescriptorCascadeListAttribute;
NSString *const UIFontDescriptorTraitsAttribute;
NSString *const UIFontDescriptorFixedAdvanceAttribute;
NSString *const UIFontDescriptorFeatureSettingsAttribute;
NSString *const UIFontDescriptorTextStyleAttribute;
Constants
UIFontDescriptorFamilyAttribute

An optional NSString object that specifies the font family.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorNameAttribute

An optional NSString object that specifies the font name.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorFaceAttribute

An optional NSString object that specifies the font face.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorSizeAttribute

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorVisibleNameAttribute

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorMatrixAttribute

A CGAffineTransform instance that specifies the font’s transformation matrix. The default value is the identity matrix.

Because the matrix is applied to the text matrix at rendering time, translation is not supported—the rendering engine determines the translation independently.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorCharacterSetAttribute

An NSCharacterSet instance that represents the set of Unicode characters covered by the font. The default value is supplied by the font.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorCascadeListAttribute

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 iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTraitsAttribute

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 iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorFixedAdvanceAttribute

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

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorFeatureSettingsAttribute

An array of dictionaries representing non-default font feature settings. Each dictionary contains UIFontFeatureTypeIdentifierKey and UIFontFeatureSelectorIdentifierKey.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontDescriptorTextStyleAttribute

An NSString instance containing the desired text style.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

Discussion

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

Font Traits Dictionary Keys

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

NSString *const UIFontSymbolicTrait;
NSString *const UIFontWeightTrait;
NSString *const UIFontWidthTrait;
NSString *const UIFontSlantTrait;
Constants
UIFontSymbolicTrait

Used with a trait dictionary to get the symbolic traits value as an NSNumber object.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontWeightTrait

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 iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontWidthTrait

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 iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontSlantTrait

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 iOS 7.0 and later.

Declared in UIFontDescriptor.h.

Discussion

These keys are used with UIFontDescriptorTraitsAttribute.

Font Feature Keys

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

NSString *const UIFontFeatureTypeIdentifierKey;
NSString *const UIFontFeatureSelectorIdentifierKey;
Constants
UIFontFeatureTypeIdentifierKey

An NSNumber object specifying a font feature type such as ligature, character shape, and so on.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

UIFontFeatureSelectorIdentifierKey

An NSNumber object specifying a font feature selector such as common ligature off, traditional character shape, and so on.

Available in iOS 7.0 and later.

Declared in UIFontDescriptor.h.

Discussion

These keys are used with UIFontDescriptorFeatureSettingsAttribute.