iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIFontDescriptor Class Reference

Options
Deployment Target:

On This Page
Language:

UIFontDescriptor

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.

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

    Declaration

    Swift

    func matchingFontDescriptorsWithMandatoryKeys(_ mandatoryKeys: Set<String>) -> [UIFontDescriptor]

    Objective-C

    - (NSArray<UIFontDescriptor *> * _Nonnull)matchingFontDescriptorsWithMandatoryKeys:(NSSet<NSString *> * _Nonnull)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.

Data Types

  • UIFontDescriptorClass classifies certain stylistic qualities of the font.

    Declaration

    Swift

    typealias UIFontDescriptorClass = Int

    Objective-C

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    let UIFontTextStyleHeadline: String let UIFontTextStyleSubheadline: String let UIFontTextStyleBody: String let UIFontTextStyleFootnote: String let UIFontTextStyleCaption1: String let UIFontTextStyleCaption2: String

    Objective-C

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

    Constants

    • UIFontTextStyleHeadline

      UIFontTextStyleHeadline

      The font used for headings.

      Available in iOS 7.0 and later.

    • UIFontTextStyleSubheadline

      UIFontTextStyleSubheadline

      The font used for subheadings.

      Available in iOS 7.0 and later.

    • UIFontTextStyleBody

      UIFontTextStyleBody

      The font used for body text.

      Available in iOS 7.0 and later.

    • UIFontTextStyleFootnote

      UIFontTextStyleFootnote

      The font used in footnotes.

      Available in iOS 7.0 and later.

    • UIFontTextStyleCaption1

      UIFontTextStyleCaption1

      The font used for standard captions.

      Available in iOS 7.0 and later.

    • UIFontTextStyleCaption2

      UIFontTextStyleCaption2

      The font used for alternate captions.

      Available in iOS 7.0 and later.

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

    Declaration

    Swift

    struct UIFontDescriptorSymbolicTraits : OptionSetType { init(rawValue rawValue: UInt32) static var TraitItalic: UIFontDescriptorSymbolicTraits { get } static var TraitBold: UIFontDescriptorSymbolicTraits { get } static var TraitExpanded: UIFontDescriptorSymbolicTraits { get } static var TraitCondensed: UIFontDescriptorSymbolicTraits { get } static var TraitMonoSpace: UIFontDescriptorSymbolicTraits { get } static var TraitVertical: UIFontDescriptorSymbolicTraits { get } static var TraitUIOptimized: UIFontDescriptorSymbolicTraits { get } static var TraitTightLeading: UIFontDescriptorSymbolicTraits { get } static var TraitLooseLeading: UIFontDescriptorSymbolicTraits { get } static var ClassMask: UIFontDescriptorSymbolicTraits { get } static var ClassUnknown: UIFontDescriptorSymbolicTraits { get } static var ClassOldStyleSerifs: UIFontDescriptorSymbolicTraits { get } static var ClassTransitionalSerifs: UIFontDescriptorSymbolicTraits { get } static var ClassModernSerifs: UIFontDescriptorSymbolicTraits { get } static var ClassClarendonSerifs: UIFontDescriptorSymbolicTraits { get } static var ClassSlabSerifs: UIFontDescriptorSymbolicTraits { get } static var ClassFreeformSerifs: UIFontDescriptorSymbolicTraits { get } static var ClassSansSerif: UIFontDescriptorSymbolicTraits { get } static var ClassOrnamentals: UIFontDescriptorSymbolicTraits { get } static var ClassScripts: UIFontDescriptorSymbolicTraits { get } static var ClassSymbolic: UIFontDescriptorSymbolicTraits { get } }

    Objective-C

    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

    • TraitItalic

      UIFontDescriptorTraitItalic

      The font’s typestyle is italic.

      Available in iOS 7.0 and later.

    • TraitBold

      UIFontDescriptorTraitBold

      The font’s typestyle is boldface.

      Available in iOS 7.0 and later.

    • TraitExpanded

      UIFontDescriptorTraitExpanded

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

      Available in iOS 7.0 and later.

    • TraitCondensed

      UIFontDescriptorTraitCondensed

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

      Available in iOS 7.0 and later.

    • TraitMonoSpace

      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.

    • TraitVertical

      UIFontDescriptorTraitVertical

      The font uses vertical glyph variants and metrics.

      Available in iOS 7.0 and later.

    • TraitUIOptimized

      UIFontDescriptorTraitUIOptimized

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

      Available in iOS 7.0 and later.

    • TraitTightLeading

      UIFontDescriptorTraitTightLeading

      The font uses tighter leading values.

      Available in iOS 7.0 and later.

    • TraitLooseLeading

      UIFontDescriptorTraitLooseLeading

      The font uses looser leading values.

      Available in iOS 7.0 and later.

    • ClassMask

      UIFontDescriptorClassMask

      The font family class mask used to access UIFontDescriptorClass values.

      Available in iOS 7.0 and later.

    • ClassUnknown

      UIFontDescriptorClassUnknown

      The font has no design classification.

      Available in iOS 7.0 and later.

    • ClassOldStyleSerifs

      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.

    • ClassTransitionalSerifs

      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.

    • ClassModernSerifs

      UIFontDescriptorClassModernSerifs

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

      Available in iOS 7.0 and later.

    • ClassClarendonSerifs

      UIFontDescriptorClassClarendonSerifs

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

      Available in iOS 7.0 and later.

    • ClassSlabSerifs

      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.

    • ClassFreeformSerifs

      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.

    • ClassSansSerif

      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.

    • ClassOrnamentals

      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.

    • ClassScripts

      UIFontDescriptorClassScripts

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

      Available in iOS 7.0 and later.

    • ClassSymbolic

      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.

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • These font attributes are defined by UIFontDescriptor.

    Declaration

    Swift

    let UIFontDescriptorFamilyAttribute: String let UIFontDescriptorNameAttribute: String let UIFontDescriptorFaceAttribute: String let UIFontDescriptorSizeAttribute: String let UIFontDescriptorVisibleNameAttribute: String let UIFontDescriptorMatrixAttribute: String let UIFontDescriptorCharacterSetAttribute: String let UIFontDescriptorCascadeListAttribute: String let UIFontDescriptorTraitsAttribute: String let UIFontDescriptorFixedAdvanceAttribute: String let UIFontDescriptorFeatureSettingsAttribute: String let UIFontDescriptorTextStyleAttribute: String

    Objective-C

    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

      UIFontDescriptorFamilyAttribute

      An optional NSString object that specifies the font family.

      Available in iOS 7.0 and later.

    • UIFontDescriptorNameAttribute

      UIFontDescriptorNameAttribute

      An optional NSString object that specifies the font name.

      Available in iOS 7.0 and later.

    • UIFontDescriptorFaceAttribute

      UIFontDescriptorFaceAttribute

      An optional NSString object that specifies the font face.

      Available in iOS 7.0 and later.

    • UIFontDescriptorSizeAttribute

      UIFontDescriptorSizeAttribute

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

      Available in iOS 7.0 and later.

    • UIFontDescriptorVisibleNameAttribute

      UIFontDescriptorVisibleNameAttribute

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

      Available in iOS 7.0 and later.

    • UIFontDescriptorMatrixAttribute

      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.

    • UIFontDescriptorCharacterSetAttribute

      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.

    • UIFontDescriptorCascadeListAttribute

      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.

    • UIFontDescriptorTraitsAttribute

      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.

    • UIFontDescriptorFixedAdvanceAttribute

      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.

    • UIFontDescriptorFeatureSettingsAttribute

      UIFontDescriptorFeatureSettingsAttribute

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

      Available in iOS 7.0 and later.

    • UIFontDescriptorTextStyleAttribute

      UIFontDescriptorTextStyleAttribute

      An NSString instance containing the desired text style.

      Available in iOS 7.0 and later.

    Discussion

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

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

    Declaration

    Swift

    let UIFontSymbolicTrait: String let UIFontWeightTrait: String let UIFontWidthTrait: String let UIFontSlantTrait: String

    Objective-C

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

    Constants

    • UIFontSymbolicTrait

      UIFontSymbolicTrait

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

      Available in iOS 7.0 and later.

    • UIFontWeightTrait

      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. You can also use a font weight constant to specify a particular weight; for a list of constants you can use, see Font Weights.

      Available in iOS 7.0 and later.

    • UIFontWidthTrait

      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.

    • UIFontSlantTrait

      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.

    Discussion

    These keys are used with UIFontDescriptorTraitsAttribute.

  • The following constants represent font weights that can be used as values for UIFontWeightTrait.

    Declaration

    Swift

    let UIFontWeightUltraLight: CGFloat let UIFontWeightThin: CGFloat let UIFontWeightLight: CGFloat let UIFontWeightRegular: CGFloat let UIFontWeightMedium: CGFloat let UIFontWeightSemibold: CGFloat let UIFontWeightBold: CGFloat let UIFontWeightHeavy: CGFloat let UIFontWeightBlack: CGFloat

    Objective-C

    const CGFloat UIFontWeightUltraLight; const CGFloat UIFontWeightThin; const CGFloat UIFontWeightLight; const CGFloat UIFontWeightRegular; const CGFloat UIFontWeightMedium; const CGFloat UIFontWeightSemibold; const CGFloat UIFontWeightBold; const CGFloat UIFontWeightHeavy; const CGFloat UIFontWeightBlack;

    Constants

    • UIFontWeightUltraLight

      UIFontWeightUltraLight

      A CGFloat instance that specifies the ultra light font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightThin

      UIFontWeightThin

      A CGFloat instance that specifies the thin font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightLight

      UIFontWeightLight

      A CGFloat instance that specifies the light font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightRegular

      UIFontWeightRegular

      A CGFloat instance that specifies the regular font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightMedium

      UIFontWeightMedium

      A CGFloat instance that specifies the medium font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightSemibold

      UIFontWeightSemibold

      A CGFloat instance that specifies the semibold font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightBold

      UIFontWeightBold

      A CGFloat instance that specifies the bold font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightHeavy

      UIFontWeightHeavy

      A CGFloat instance that specifies the heavy font weight.

      Available in iOS 8.2 and later.

    • UIFontWeightBlack

      UIFontWeightBlack

      A CGFloat instance that specifies the black font weight.

      Available in iOS 8.2 and later.

    Discussion

    You can also use these constants to specify the weight parameter in systemFontOfSize:weight. Note that most fonts do not include variants in all these font weights.

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

    Declaration

    Swift

    let UIFontFeatureTypeIdentifierKey: String let UIFontFeatureSelectorIdentifierKey: String

    Objective-C

    NSString *const UIFontFeatureTypeIdentifierKey; NSString *const UIFontFeatureSelectorIdentifierKey;

    Constants

    • UIFontFeatureTypeIdentifierKey

      UIFontFeatureTypeIdentifierKey

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

      Available in iOS 7.0 and later.

    • UIFontFeatureSelectorIdentifierKey

      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.

    Discussion

    These keys are used with UIFontDescriptorFeatureSettingsAttribute.