Declaration

Parameters

attributes

A dictionary containing arbitrary attributes.

Return Value

A new font descriptor with the attributes specified.

Discussion

The provided attribute dictionary can contain arbitrary attributes that are preserved; however, unrecognized attributes are ignored on font creation and and may not be preserved over the round trip from descriptor to font and back to descriptor.

Parameters

A set of attribute keys that must be identically matched in any returned font descriptors. May be NULL.

Return Value

A retained array of normalized font descriptors matching the attributes present in descriptor.

Discussion

If descriptor itself is normalized, then the array will contain only one item: the original descriptor. In the context of font descriptors, normalized infers that the input values were matched up with actual existing fonts, and the descriptors for those existing fonts are the returned normalized descriptors.

Return Value

Discussion

The original descriptor may be returned in normalized form. The caller is responsible for releasing the result. In the context of font descriptors, normalized infers that the input values were matched up with actual existing fonts, and the descriptors for those existing fonts are the returned normalized descriptors.

Parameters

On output, contains a reference to the matched language. The language identifier will conform to the RFC 3066bis standard.

Return Value

A retained reference to a localized attribute based on the global language list.

Discussion

This function passes back the matched language in language. If localization is not possible for the attribute, the behavior matches the value returned from CTFontDescriptorCopyAttribute. Generally, localization of attributes is applicable to name attributes of only a normalized font descriptor.

Constants

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

Available in OS X v10.6 and later.

kCTFontNameAttribute

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

kCTFontDisplayNameAttribute

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

kCTFontFamilyNameAttribute

kCTFontFamilyNameAttribute

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

Available in OS X v10.5 and later.

kCTFontStyleNameAttribute

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

kCTFontTraitsAttribute

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

kCTFontVariationAttribute

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

kCTFontSizeAttribute

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

kCTFontMatrixAttribute

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

kCTFontCascadeListAttribute

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

kCTFontCharacterSetAttribute

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

kCTFontLanguagesAttribute

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

kCTFontBaselineAdjustAttribute

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

kCTFontMacintoshEncodingsAttribute

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

kCTFontFeaturesAttribute

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

kCTFontFeatureSettingsAttribute

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

kCTFontFixedAdvanceAttribute

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

kCTFontOrientationAttribute

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

kCTFontFormatAttribute

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

kCTFontRegistrationScopeAttribute

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

kCTFontPriorityAttribute

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

kCTFontEnabledAttribute

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.

Constants

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

Available in OS X v10.5 and later.

kCTFontWeightTrait

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

kCTFontWidthTrait

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

kCTFontSlantTrait

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.

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

Available in OS X v10.5 and later.

CondensedTrait

kCTFontCondensedTrait

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

Available in OS X v10.5 and later.

MonoSpaceTrait

kCTFontMonoSpaceTrait

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

VerticalTrait

kCTFontVerticalTrait

The font uses vertical glyph variants and metrics.

Available in OS X v10.5 and later.

UIOptimizedTrait

kCTFontUIOptimizedTrait

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

Available in OS X v10.5 and later.

ClassMaskTrait

kCTFontClassMaskTrait

Mask for the font class.

Available in OS X v10.5 and later.

Discussion

CTFontSymbolicTraits symbolically describes stylistic aspects of a font. The upper 16 bits are used to describe appearance of the font, whereas the lower 16 bits are for typeface information. The font appearance information represented by the upper 16 bits can be used for stylistic font matching.

Constants

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

Available in OS X v10.5 and later.

TransitionalSerifsClass

kCTFontTransitionalSerifsClass

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

Available in OS X v10.5 and later.

ModernSerifsClass

kCTFontModernSerifsClass

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

Available in OS X v10.5 and later.

ClarendonSerifsClass

kCTFontClarendonSerifsClass

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

Available in OS X v10.5 and later.

SlabSerifsClass

kCTFontSlabSerifsClass

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

FreeformSerifsClass

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

SansSerifClass

kCTFontSansSerifClass

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

OrnamentalsClass

kCTFontOrnamentalsClass

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

Available in OS X v10.5 and later.

ScriptsClass

kCTFontScriptsClass

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

Available in OS X v10.5 and later.

SymbolicClass

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

Discussion

CTFontStylisticClass classifies 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 “Font Symbolic Traits Constants” and can be obtained via kCTFontClassMaskTrait.