Up
Authors
- H. Nikolaus Schaller (
hns@computer.org)
-
Date: Generated at 2025-12-03
The font descriptor class
Copyright: (C) 2007-2016 Free Software Foundation, Inc.
- Declared in:
- AppKit/NSFontDescriptor.h
- Conforms to:
- NSCoding
- NSCopying
Availability: MacOS-X 10.3.0
NSFontDescriptor provides a flexible way to
describe fonts using attribute dictionaries rather
than specific font instances. This class serves as an
intermediate representation that can be used to
create fonts with specific characteristics or to find
fonts that match certain criteria. Font descriptors are
particularly useful for: - Font matching and
substitution when exact fonts aren't available -
Describing fonts in a platform-independent way -
Creating variations of existing fonts with modified
attributes - Serializing font information for
storage or transmission - Implementing font panels
and font selection interfaces The descriptor system uses
attribute dictionaries where keys are NSString
constants (like NSFontFamilyAttribute) and values
are appropriate objects (NSString for names, NSNumber for
sizes, etc.). This provides flexibility while
maintaining type safety. Font descriptors work
closely with NSFont for font creation and with
NSFontCollection for organizing and managing
groups of related fonts. They also integrate with the
font panel system for user font selection.
NSFontDescriptor declares 1 Instance Variables
+ (id)
fontDescriptorWithFontAttributes: (
NSDictionary*)attributes;
Availability: MacOS-X 10.3.0
Creates a font descriptor from a dictionary of font
attributes. The attributes
dictionary contains key-value pairs that
describe the desired font characteristics using
standard font attribute keys like
NSFontFamilyAttribute,
NSFontSizeAttribute, and
NSFontTraitsAttribute. Returns a new
font descriptor that encapsulates these
attributes, or nil if the
attributes dictionary is invalid.
+ (id)
fontDescriptorWithName: (
NSString*)name
matrix: (
NSAffineTransform*)matrix;
Availability: MacOS-X 10.4.0
Creates a font descriptor with a specific font
name and transformation matrix.
The name parameter specifies the font family
name and the matrix parameter
provides an affine transformation to apply to the
font, allowing for effects like scaling, rotation, or
skewing. Returns a new font descriptor that
combines the font name with the
geometric transformation.
+ (id)
fontDescriptorWithName: (
NSString*)name
size: (CGFloat)size;
Availability: MacOS-X 10.3.0
Creates a font descriptor with a specific font
family name and point size.
The name parameter specifies the font family
(such as "Helvetica" or "Times") and the
size parameter specifies the font
size in points. This is a convenience
method for creating descriptors with the most
commonly needed attributes. Returns a new font
descriptor with the specified family and
size.
- (
NSDictionary*)
fontAttributes;
Availability: MacOS-X 10.3.0
Returns the complete attribute dictionary for this
font descriptor. The returned dictionary contains all
the font attributes that define this descriptor, using
standard attribute keys like NSFontFamilyAttribute
and NSFontSizeAttribute. This provides access to all
font characteristics in a single collection for
inspection or serialization.
- (
NSFontDescriptor*)
fontDescriptorByAddingAttributes: (
NSDictionary*)attributes;
Availability: MacOS-X 10.4.0
Creates a new font descriptor by adding
attributes to this descriptor. The
attributes parameter contains additional
font attributes to merge with the existing
attributes in this descriptor. If an
attribute key already exists, the new value
replaces the old one. Returns a new font
descriptor with the combined
attributes.
- (
NSFontDescriptor*)
fontDescriptorWithFace: (
NSString*)face;
Availability: MacOS-X 10.4.0
Creates a new font descriptor with a specific font
face name. The face parameter
specifies the font face (such as
"Bold", "Italic", or "Regular") to use with this
descriptor's other attributes. This is useful
for creating variations of an existing font descriptor
with different weights or styles. Returns a new
descriptor with the face attribute.
- (
NSFontDescriptor*)
fontDescriptorWithFamily: (
NSString*)family;
Availability: MacOS-X 10.4.0
Creates a new font descriptor with a specific font
family name. The family
parameter specifies the font family
(such as "Helvetica" or "Times") to use while
preserving other attributes from this
descriptor. This allows changing the font
family while maintaining size, traits, and
other characteristics. Returns a new descriptor with
the family attribute.
- (
NSFontDescriptor*)
fontDescriptorWithMatrix: (
NSAffineTransform*)matrix;
Availability: MacOS-X 10.4.0
Creates a new font descriptor with a specific
transformation matrix. The
matrix parameter provides an
NSAffineTransform to apply to the font,
allowing for geometric transformations like
scaling, rotation, or skewing. Other attributes
from this descriptor are preserved. Returns a new
descriptor with the matrix
transformation applied.
- (
NSFontDescriptor*)
fontDescriptorWithSize: (CGFloat)size;
Availability: MacOS-X 10.4.0
Creates a new font descriptor with a specific point
size. The size parameter
specifies the font size in points
while preserving all other attributes from this
descriptor. This is a convenient way to resize
a font while maintaining its family, traits, and other
characteristics. Returns a new descriptor
with the specified size.
- (
NSFontDescriptor*)
fontDescriptorWithSymbolicTraits: (
NSFontSymbolicTraits)traits;
Availability: MacOS-X 10.4.0
Creates a new font descriptor with specific
symbolic traits. The traits
parameter contains NSFontSymbolicTraits flags
that describe font characteristics like bold, italic,
condensed, etc. Other attributes from this
descriptor are preserved while the symbolic
traits are updated. Returns a new
descriptor with the specified traits.
- (id)
initWithFontAttributes: (
NSDictionary*)attributes;
Availability: MacOS-X 10.3.0
Initializes a font descriptor with the
specified font attributes dictionary.
The attributes dictionary should contain
key-value pairs using standard font attribute
keys. This is the designated initializer for creating
font descriptors with custom attribute combinations.
Returns an initialized font descriptor or
nil if the attributes are
invalid.
- (
NSFontDescriptor*)
matchingFontDescriptorWithMandatoryKeys: (
NSSet*)keys;
Availability: MacOS-X 10.5.0
Finds the best matching font descriptor for this
descriptor's attributes. The keys
parameter is an NSSet containing attribute
keys that must be matched exactly in the
search result. Unlike
matchingFontDescriptorsWithMandatoryKeys:
which returns an array of all matches, this method
returns only the single best matching font
descriptor, or nil if no suitable
match is found. This is useful when you need a
specific font rather than a list of options.
- (
NSArray*)
matchingFontDescriptorsWithMandatoryKeys: (
NSSet*)keys;
Availability: MacOS-X 10.4.0
Finds font descriptors that match this descriptor's
attributes. The keys parameter is an
NSSet containing attribute keys that must
be matched exactly in the search results. Other
attributes may be used for ranking but are not
mandatory. Returns an NSArray of
NSFontDescriptor objects sorted by
relevance, with the best matches first. Returns
an empty array if no matching fonts are found.
- (
NSAffineTransform*)
matrix;
Availability: MacOS-X 10.4.0
Returns the transformation matrix associated with
this font descriptor. Extracts the NSAffineTransform
from the NSFontMatrixAttribute if present, or returns
the identity matrix if no transformation is specified.
This matrix defines geometric transformations like
scaling, rotation, or skewing that should be
applied to the font.
- (id)
objectForKey: (
NSString*)attribute;
Availability: MacOS-X 10.4.0
Returns the value for a specific font
attribute key. The attribute
parameter should be one of the standard font
attribute constants like
NSFontNameAttribute or
NSFontSizeAttribute. Returns the
corresponding value object (NSString,
NSNumber, etc.) or nil if the
attribute is not present in this
descriptor. Provides direct access to
individual attributes without retrieving the
entire dictionary.
- (CGFloat)
pointSize;
Availability: MacOS-X 10.4.0
Returns the point size specified in this font
descriptor. Extracts the font size from the
NSFontSizeAttribute if present, or
returns 0.0 if no size is specified. This provides
convenient access to the font size without
needing to query the attributes dictionary
directly.
- (
NSString*)
postscriptName;
Availability: MacOS-X 10.4.0
Returns the PostScript name for the font described
by this descriptor. The PostScript name is a unique
identifier for the specific font face that
includes family, weight, and style information in
a standardized format. Returns the PostScript name as an
NSString, or nil if the descriptor
doesn't specify a complete font definition.
- (
NSFontSymbolicTraits)
symbolicTraits;
Availability: MacOS-X 10.4.0
Returns the symbolic traits associated with this
font descriptor. Extracts the NSFontSymbolicTraits
flags from the font attributes, providing information
about font characteristics like bold, italic,
condensed, monospace, etc. Returns 0 if no
symbolic traits are specified in this descriptor.
Instance Variables for NSFontDescriptor Class
@protected NSDictionary*
_attributes;
Availability: MacOS-X 10.3.0
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Up