CTFontDescriptor Reference

Overview

The CTFontDescriptor opaque type represents a font descriptor, that is, a dictionary of attributes (such as name, point size, and variation) that can completely specify a font.

A font descriptor can be an incomplete specification, in which case the system chooses the most appropriate font to match the given attributes.

Functions by Task

Creating Font Descriptors

• CTFontDescriptorCreateWithNameAndSize
• CTFontDescriptorCreateWithAttributes
• CTFontDescriptorCreateCopyWithAttributes
• CTFontDescriptorCreateCopyWithVariation
• CTFontDescriptorCreateCopyWithFeature
• CTFontDescriptorCreateMatchingFontDescriptors
• CTFontDescriptorCreateMatchingFontDescriptor

Getting Attributes

• CTFontDescriptorCopyAttributes
• CTFontDescriptorCopyAttribute
• CTFontDescriptorCopyLocalizedAttribute

Getting the Font Descriptor Type

• CTFontDescriptorGetTypeID

Functions

CTFontDescriptorCopyAttribute

Returns the value associated with an arbitrary attribute.

CFTypeRef CTFontDescriptorCopyAttribute (
   CTFontDescriptorRef descriptor,
   CFStringRef attribute
);

CTFontDescriptorCopyAttributes

Returns the attributes dictionary of the font descriptor.

CFDictionaryRef CTFontDescriptorCopyAttributes (
   CTFontDescriptorRef descriptor
);

CTFontDescriptorCopyLocalizedAttribute

Returns a localized value for the requested attribute, if available.

CFTypeRef CTFontDescriptorCopyLocalizedAttribute (
   CTFontDescriptorRef descriptor,
   CFStringRef attribute,
   CFStringRef *language
);

CTFontDescriptorCreateCopyWithAttributes

Creates a copy of the original font descriptor with new attributes.

CTFontDescriptorRef CTFontDescriptorCreateCopyWithAttributes (
   CTFontDescriptorRef original,
   CFDictionaryRef attributes
);

CTFontDescriptorCreateCopyWithFeature

Copies a font descriptor with new feature settings.

CTFontDescriptorRef CTFontDescriptorCreateCopyWithFeature (
   CTFontDescriptorRef original,
   CFNumberRef featureTypeIdentifier,
   CFNumberRef featureSelectorIdentifier
);

CTFontDescriptorCreateCopyWithVariation

Creates a copy of the original font descriptor with a new variation instance.

CTFontDescriptorRef CTFontDescriptorCreateCopyWithVariation (
   CTFontDescriptorRef original,
   CFNumberRef variationIdentifier,
   CGFloat variationValue
);

CTFontDescriptorCreateMatchingFontDescriptor

Returns the single preferred matching font descriptor based on the original descriptor and system precedence.

CTFontDescriptorRef CTFontDescriptorCreateMatchingFontDescriptor (
   CTFontDescriptorRef descriptor,
   CFSetRef mandatoryAttributes
);

CTFontDescriptorCreateMatchingFontDescriptors

Returns an array of normalized font descriptors matching the provided descriptor.

CFArrayRef CTFontDescriptorCreateMatchingFontDescriptors (
   CTFontDescriptorRef descriptor,
   CFSetRef mandatoryAttributes
);

CTFontDescriptorCreateWithAttributes

Creates a new font descriptor reference from a dictionary of attributes.

CTFontDescriptorRef CTFontDescriptorCreateWithAttributes (
   CFDictionaryRef attributes
);

CTFontDescriptorCreateWithNameAndSize

Creates a new font descriptor with the provided PostScript name and size.

CTFontDescriptorRef CTFontDescriptorCreateWithNameAndSize (
   CFStringRef name,
   CGFloat size
);

CTFontDescriptorGetTypeID

Returns the type identifier for Core Text font descriptor references.

CFTypeID CTFontDescriptorGetTypeID (
   void
);

Data Types

CTFontDescriptorRef

A reference to a CTFontDescriptor object.

typedef const struct __CTFontDescriptor *CTFontDescriptorRef;

Constants

Font Attributes

Font Attribute Constants

These constants are keys for accessing font attributes from a font descriptor.

const CFStringRef kCTFontURLAttribute;
const CFStringRef kCTFontNameAttribute;
const CFStringRef kCTFontDisplayNameAttribute;
const CFStringRef kCTFontFamilyNameAttribute;
const CFStringRef kCTFontStyleNameAttribute;
const CFStringRef kCTFontTraitsAttribute;
const CFStringRef kCTFontVariationAttribute;
const CFStringRef kCTFontSizeAttribute;
const CFStringRef kCTFontMatrixAttribute;
const CFStringRef kCTFontCascadeListAttribute;
const CFStringRef kCTFontCharacterSetAttribute;
const CFStringRef kCTFontLanguagesAttribute;
const CFStringRef kCTFontBaselineAdjustAttribute;
const CFStringRef kCTFontMacintoshEncodingsAttribute;
const CFStringRef kCTFontFeaturesAttribute;
const CFStringRef kCTFontFeatureSettingsAttribute;
const CFStringRef kCTFontFixedAdvanceAttribute;
const CFStringRef kCTFontOrientationAttribute;
const CFStringRef kCTFontFormatAttribute;
const CFStringRef kCTFontRegistrationScopeAttribute;
const CFStringRef kCTFontPriorityAttribute;
const CFStringRef kCTFontEnabledAttribute;

Constants

kCTFontURLAttribute

Key for accessing the font URL from the font descriptor. The value associated with this key is a CFURLRef object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontNameAttribute

Key for accessing the PostScript name from the font descriptor. The value associated with this key is a CFStringRef object. If the value is unspecified, it defaults to Helvetica, and if that font is unavailable, it falls back to the global font cascade list.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontDisplayNameAttribute

Key for accessing the name used to display the font. Most commonly this is the full name. The value associated with this key is a CFStringRef object. If the value is unspecified, it defaults to Helvetica, and if that font is unavailable, it falls back to the global font cascade list.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFamilyNameAttribute

Key for accessing the font family name from the font descriptor. The value associated with this key is a CFStringRef object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontStyleNameAttribute

Key for accessing the style name of the font. This name represents the designer's description of the font's style. The value associated with this key is a CFStringRef object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontTraitsAttribute

Key for accessing the dictionary of font traits for stylistic information. See “Font Traits” for the list of font traits. The value associated with this key is a CFDictionaryRef object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontVariationAttribute

Key to obtain the font variation dictionary instance as a CFDictionaryRef object. If specified in a font descriptor, fonts with the specified axes are primary match candidates; if no such fonts exist, this attribute is ignored.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontSizeAttribute

Key to obtain or specify the font point size. Creating a font with this unspecified will default to a point size of 12.0. The value for this key is represented as a CFNumberRef object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontMatrixAttribute

Key to specify the font transformation matrix when creating a font. If unspecified it defaults to the unit matrix. The value for this key is a CFDataRef object containing a CGAffineTransform object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontCascadeListAttribute

Key to specify or obtain the cascade list used for a font reference. The cascade list is a CFArrayRef object containing CTFontDescriptorRef elements. If unspecified, the global cascade list is used.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontCharacterSetAttribute

Key to specify or obtain the Unicode character coverage set for a font reference. The value for this key is a CFCharacterSetRef object. If specified, this attribute can be used to restrict the font to a subset of its actual character set. If unspecified, this attribute is ignored and the actual character set is used.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontLanguagesAttribute

Key to specify or obtain a list of covered languages for a font reference. The value for this key is a CFArrayRef object containing CFStringRef elements. If specified, this attribute restricts the search to matching fonts that support the specified languages. The language identifier string should conform to the RFC 3066bis standard. If unspecified, this attribute is ignored.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontBaselineAdjustAttribute

Key to specify or obtain the baseline adjustment for a font reference. This is primarily used when defining font descriptors for a cascade list to keep the baseline of all fonts even. The value associated with this is a float represented as a CFNumberRef object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontMacintoshEncodingsAttribute

Key to specify or obtain the Macintosh encodings for a font reference. The value associated with this key is a CFNumberRef object containing a bit field of the Macintosh encodings. This attribute is provided for legacy compatibility.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFeaturesAttribute

Key to specify or obtain the font features for a font reference. The value associated with this key is a CFArrayRef object containing font feature dictionaries. This feature list contains the feature information from the 'feat' table of the font. For more information, see CTFontCopyFeatures.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFeatureSettingsAttribute

Key to specify or obtain the font features settings for a font reference. The value associated with this key is a CFArrayRef object containing font feature-setting dictionaries. A feature-setting dictionary contains a tuple of a kCTFontFeatureTypeIdentifierKey key-value pair and a kCTFontFeatureSelectorIdentifierKey key-value pair. Each setting dictionary indicates which setting should be turned on. In the case of duplicate or conflicting setting, the last setting in the list takes precedence. It is the caller's responsibility to handle exclusive and nonexclusive settings as necessary.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFixedAdvanceAttribute

Key to specify a fixed advance to be used for a font reference. If present and specified, this attribute is used to specify a constant advance to override any font values. The value associated with this key is a float represented as a CFNumberRef object.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontOrientationAttribute

Key to specify a particular orientation for the glyphs of the font. The value associated with this key is an integer represented as a CFNumberRef object containing one of the constants in “Font Orientation Constants.” If you want to receive vertical metrics from a font for vertical rendering, specify kCTFontVerticalOrientation. If unspecified, the font uses its native orientation.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFormatAttribute

Key to specify or obtain the recognized format of the font. The value associated with this key is an integer represented as a CFNumberRef object containing one of the constants in “Font Format Constants.”

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontRegistrationScopeAttribute

Key to specify or obtain the font descriptor's registration scope. The value associated with this key is an integer represented as a CFNumberRef object containing one of the CTFontManagerScope enumerated values. A value of NULL can be returned for font descriptors that are not registered.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontPriorityAttribute

Key to specify or obtain the font priority used by font descriptors when resolving duplicates and sorting match results. The value associated with this key is an integer represented as a CFNumberRef object containing one of the values enumerated in “Font Priority Constants.” The higher the value, the higher the priority of the font. Only registered fonts have a priority. Unregistered font descriptors return NULL.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontEnabledAttribute

Key to obtain the font enabled state. The returned value is an integer represented as a CFNumberRef object representing a Boolean value. Unregistered font descriptors return NULL, which is equivalent to false.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

Font Orientation Constants

Specifies the intended rendering orientation of the font for obtaining glyph metrics. These constants are used as values of kCTFontOrientationAttribute.

enum {
   kCTFontDefaultOrientation = 0,
   kCTFontHorizontalOrientation = 1,
   kCTFontVerticalOrientation = 2
};
typedef uint32_t CTFontOrientation;

Constants

kCTFontDefaultOrientation

The native orientation of the font.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontHorizontalOrientation

Specifies horizontal orientation.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontVerticalOrientation

Specifies vertical orientation.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

Font Format Constants

Specifies the recognized format of the font.

enum {
   kCTFontFormatUnrecognized       = 0,
   kCTFontFormatOpenTypePostScript = 1,
   kCTFontFormatOpenTypeTrueType   = 2,
   kCTFontFormatTrueType           = 3,
   kCTFontFormatPostScript         = 4,
   kCTFontFormatBitmap             = 5
};
typedef uint32_t CTFontFormat;

Constants

kCTFontFormatUnrecognized

The font is not a recognized format.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFormatOpenTypePostScript

The font is an OpenType format containing PostScript data.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFormatOpenTypeTrueType

The font is an OpenType format containing TrueType data.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFormatTrueType

The font is a recognized TrueType format.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFormatPostScript

The font is a recognized PostScript format.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontFormatBitmap

The font is a bitmap-only format.

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

Font Priority Constants

Specifies the priority of font descriptors when resolving duplicates and sorting match results.

enum {
   kCTFontPrioritySystem =  10000,
   kCTFontPriorityNetwork =  20000,
   kCTFontPriorityComputer =  30000,
   kCTFontPriorityUser =  40000,
   kCTFontPriorityDynamic =  50000,
   kCTFontPriorityProcess =  60000
};
typedef uint32_t CTFontPriority;

Constants

kCTFontPrioritySystem

Priority of system fonts (located in /System/Library/Fonts).

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontPriorityNetwork

Priority of network fonts (located in /Network/Library/Fonts).

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontPriorityComputer

Priority of computer local fonts (located in /Library/Fonts).

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontPriorityUser

Priority of local fonts (located in user's Library/Fonts).

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontPriorityDynamic

Priority of fonts registered dynamically, not located in a standard location (either kCTFontManagerScopeUser or kCTFontManagerScopeSession).

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

kCTFontPriorityProcess

Priority of fonts registered for the process (kCTFontManagerScopeProcess).

Available in iOS 3.2 and later.

Declared in CTFontDescriptor.h.

Font Traits

Font Trait Constants

These constants are keys for accessing font traits from a font descriptor.

const CFStringRef kCTFontSymbolicTrait;
const CFStringRef kCTFontWeightTrait;
const CFStringRef kCTFontWidthTrait;
const CFStringRef kCTFontSlantTrait;

Constants

kCTFontSymbolicTrait

Key to access the symbolic traits value from the font traits dictionary. The value is returned as a CFNumberRef object.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontWeightTrait

Key to access the normalized weight trait from the font traits dictionary. The value returned is a CFNumberRef representing a float value between -1.0 and 1.0 for normalized weight. The value of 0.0 corresponds to the regular or medium font weight.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontWidthTrait

Key to access the normalized proportion (width condense or expand) trait from the font traits dictionary. This value corresponds to the relative interglyph spacing for a given font. The value returned is a CFNumberRef object representing a float between -1.0 and 1.0. The value of 0.0 corresponds to regular glyph spacing, and negative values represent condensed glyph spacing.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontSlantTrait

Key to access the normalized slant angle from the font traits dictionary. The value returned is a CFNumberRef object representing a float value between -1.0 and 1.0 for normalized slant angle. The value of 0.0 corresponds to 0 degrees clockwise rotation from the vertical and 1.0 corresponds to 30 degrees clockwise rotation.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

Font Class Mask Shift Constants

These constants represent the font class mask shift.

enum { kCTFontClassMaskShift = 28};

Constants

kCTFontClassMaskShift

Value used to shift the font class to the uppermost four bits of the symbolic traits

Font Symbolic Traits Constants

These constants represent the symbolic representation of stylistic font attributes.

enum {
kCTFontItalicTrait = (1 << 0),
kCTFontBoldTrait = (1 << 1),
kCTFontExpandedTrait = (1 << 5),
kCTFontCondensedTrait = (1 << 6),
kCTFontMonoSpaceTrait = (1 << 10),
kCTFontVerticalTrait = (1 << 11),
kCTFontUIOptimizedTrait = (1 << 12),
kCTFontClassMaskTrait = (15 << kCTFontClassMaskShift)
};
typedef uint32_t CTFontSymbolicTraits;

Constants

kCTFontItalicTrait

The font typestyle is italic. Additional detail is available via kCTFontSlantTrait.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontBoldTrait

The font typestyle is boldface. Additional detail is available via kCTFontWeightTrait.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontExpandedTrait

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontCondensedTrait

The font typestyle is condensed. Expanded and condensed traits are mutually exclusive. Additional detail is available via kCTFontWidthTrait.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontMonoSpaceTrait

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontVerticalTrait

The font uses vertical glyph variants and metrics.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontUIOptimizedTrait

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontClassMaskTrait

Mask for the font class.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

Font Stylistic Class Constants

These constants represent the stylistic class values of the font.

enum {
kCTFontUnknownClass = (0 << kCTFontClassMaskShift),
kCTFontOldStyleSerifsClass = (1 << kCTFontClassMaskShift),
kCTFontTransitionalSerifsClass = (2 << kCTFontClassMaskShift),
kCTFontModernSerifsClass = (3 << kCTFontClassMaskShift),
kCTFontClarendonSerifsClass = (4 << kCTFontClassMaskShift),
kCTFontSlabSerifsClass = (5 << kCTFontClassMaskShift),
kCTFontFreeformSerifsClass = (7 << kCTFontClassMaskShift),
kCTFontSansSerifClass = (8 << kCTFontClassMaskShift),
kCTFontOrnamentalsClass = (9 << kCTFontClassMaskShift),
kCTFontScriptsClass = (10 << kCTFontClassMaskShift),
kCTFontSymbolicClass = (12 << kCTFontClassMaskShift)
};
typedef uint32_t CTFontStylisticClass;

Constants

kCTFontUnknownClass

The font has no design classification.

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontOldStyleSerifsClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontTransitionalSerifsClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontModernSerifsClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontClarendonSerifsClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontSlabSerifsClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontFreeformSerifsClass

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 3.2 and later.

Declared in CTFontTraits.h.

kCTFontSansSerifClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontOrnamentalsClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontScriptsClass

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

Available in iOS 3.2 and later.

Declared in CTFontTraits.h.

kCTFontSymbolicClass

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 3.2 and later.

Declared in CTFontTraits.h.