Up
Authors
- Generated by Richard Frith-Macdonald
-
Date: Generated at 2025-12-03
- Declared in:
- AppKit/NSFontCollection.h
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
Availability: MacOS-X 10.7.0
NSFontCollection provides a way to organize
and manage groups of fonts through collections of font
descriptors. It allows applications to create,
store, and retrieve sets of fonts based on various
criteria such as family, style, or custom
requirements. Font collections can be created
from explicit lists of font descriptors, from all
available fonts in the system, or filtered by
locale-specific requirements. The collections
support sophisticated matching operations that can
find fonts meeting specific criteria while respecting
various filtering options. Collections can be saved
and managed at different visibility levels:
process-local, user-specific, or system-wide.
This enables sharing of font collections across
applications and users while maintaining
appropriate access controls. The class supports
both immutable collections (NSFontCollection) and
mutable variants (NSMutableFontCollection) for
dynamic modification of font sets. Collections can
include both query descriptors (fonts to include) and
exclusion descriptors (fonts to explicitly exclude)
for fine-grained control over the final font set. Font
collections are commonly used in font panels,
document templates, style systems, and any
application that needs to provide curated sets of
fonts to users while maintaining consistency and
organization.
NSFontCollection declares 1 Instance Variables
+ (
NSArray*)
allFontCollectionNames;
Availability: MacOS-X 10.7.0
Returns the names of all available font
collections. This method retrieves a list of
names for all font collections that are currently
accessible to the application, including system,
user, and process-local collections. Returns an array
of NSFontCollectionName strings identifying available
collections.
+ (
NSFontCollection*)
fontCollectionWithAllAvailableDescriptors;
Availability: MacOS-X 10.7.0
Creates a font collection containing all available
fonts in the system. This method creates a
comprehensive collection that includes every
font currently available to the application,
regardless of family, style, or other
characteristics. This is useful for
providing complete font access or as a starting
point for filtering operations. Returns a new font
collection containing all system fonts.
+ (
NSFontCollection*)
fontCollectionWithDescriptors: (
NSArray*)queryDescriptors;
Availability: MacOS-X 10.7.0
Creates a font collection from an array of font
descriptors. This method creates a new font
collection that contains fonts matching the
provided descriptors. The
queryDescriptors parameter specifies an
array of NSFontDescriptor objects that define the
criteria for fonts to include in the collection.
Returns a new font collection containing fonts that
match the specified descriptors.
+ (
NSFontCollection*)
fontCollectionWithLocale: (
NSLocale*)locale;
Availability: MacOS-X 10.7.0
Creates a font collection filtered by
locale-specific requirements. This method
creates a collection containing fonts that are
appropriate for the specified locale
, taking into account language-specific character sets,
writing systems, and cultural font preferences. The
locale parameter specifies the target
locale for font selection. Returns a new
font collection with fonts suitable for the given
locale.
+ (
NSFontCollection*)
fontCollectionWithName: (
NSFontCollectionName)name;
Availability: MacOS-X 10.7.0
Retrieves a font collection by name
from any visibility level. This method searches for a
font collection with the specified name
across all visibility levels (process, user, and
system) and returns the first match found. The
name parameter specifies the collection to
retrieve. Returns the named font collection, or
nil if no collection with that
name exists.
+ (
NSFontCollection*)
fontCollectionWithName: (
NSFontCollectionName)name
visibility: (
NSFontCollectionVisibility)visibility;
Availability: MacOS-X 10.7.0
Retrieves a font collection by name
from a specific visibility level. This
method searches for a font collection with the
specified name at the given
visibility level only. The name
parameter specifies the collection to retrieve,
and visibility indicates where to search for
it. Returns the named font collection from the
specified level, or nil if not
found.
+ (BOOL)
hideFontCollectionWithName: (
NSFontCollectionName)name
visibility: (
NSFontCollectionVisibility)visibility
error: (
NSError**)error;
Availability: MacOS-X 10.7.0
Hides a previously saved font collection from system
visibility. This method removes a saved
font collection from the specified
visibility level, making it no longer
accessible by name. The
name parameter specifies the collection to
remove, visibility indicates where to
remove it from, and error receives any
error information if the operation fails.
Returns YES if the collection was
successfully hidden, NO if an
error occurred.
+ (BOOL)
renameFontCollectionWithName: (
NSFontCollectionName)name
visibility: (
NSFontCollectionVisibility)visibility
toName: (
NSFontCollectionName)name
error: (
NSError**)error;
Availability: MacOS-X 10.7.0
Renames an existing font collection. This method
changes the name of a saved
font collection at the specified visibility
level. The name parameter
specifies the current name
name, visibility indicates
where the collection is stored, toName provides the
new name name, and
error receives any error
information if the operation fails. Returns
YES if the collection was successfully
renamed, NO if an error
occurred.
+ (BOOL)
showFontCollection: (
NSFontCollection*)collection
withName: (
NSFontCollectionName)name
visibility: (
NSFontCollectionVisibility)visibility
error: (
NSError**)error;
Availability: MacOS-X 10.7.0
Makes a font collection visible in the
system with the specified name. This
method saves a font collection so it can
be accessed by name at the specified
visibility level. The
collection parameter is the font
collection to save, name
provides the identifier for later retrieval,
visibility determines where the
collection is accessible (process, user,
or system-wide), and error receives any
error information if the operation fails.
Returns YES if the
collection was successfully saved,
NO if an error occurred.
- (
NSArray*)
exclusionDescriptors;
Availability: MacOS-X 10.7.0
Returns the exclusion descriptors that define fonts
to exclude from the collection. Exclusion descriptors
specify fonts that should be explicitly removed
from the collection's results, even if they would
otherwise match the query descriptors. This
provides fine-grained control over the final font
set. Returns an array of NSFontDescriptor objects
defining exclusion criteria.
- (
NSArray*)
matchingDescriptors;
Availability: MacOS-X 10.7.0
Returns font descriptors that match the
collection's criteria. This method evaluates
the collection's query and exclusion descriptors
against the available fonts and returns descriptors
for fonts that meet the criteria. The results represent
the actual fonts included in the collection. Returns an
array of NSFontDescriptor objects for matching fonts.
- (
NSArray*)
matchingDescriptorsForFamily: (
NSString*)family;
Availability: MacOS-X 10.7.0
Returns font descriptors for fonts within a
specific family that match the
collection. This method filters the
collection's matching fonts to include only
those from the specified font family. The
family parameter specifies the font
family name to filter by. Returns an array
of NSFontDescriptor objects for matching fonts in the
specified family.
- (
NSArray*)
matchingDescriptorsForFamily: (
NSString*)family
options: (
NSDictionary*)options;
Availability: MacOS-X 10.7.0
Returns font descriptors for fonts within a
specific family with additional
options. This method combines
family filtering with option-based
matching. The family parameter
specifies the font family to filter
by, and options can include settings for
disabled fonts, duplicates, and font activation
behavior. Returns an array of NSFontDescriptor
objects for matching family fonts with
options applied.
- (
NSArray*)
matchingDescriptorsWithOptions: (
NSDictionary*)options;
Availability: MacOS-X 10.7.0
Returns font descriptors that match the
collection's criteria with additional
options. This method performs the same
matching as matchingDescriptors but allows
additional options to be specified.
The options parameter can include keys for
including disabled fonts, removing duplicates, or
controlling font activation. Returns an array
of NSFontDescriptor objects for matching fonts with
options applied.
- (
NSArray*)
queryDescriptors;
Availability: MacOS-X 10.7.0
Returns the query descriptors that define fonts to
include in the collection. Query descriptors
specify the criteria for fonts that should be
included in the collection's results. These
descriptors define characteristics like font
family, weight, style, and other attributes that
fonts must match to be considered part of the
collection. Returns an array of
NSFontDescriptor objects defining
inclusion criteria.
Instance Variables for NSFontCollection Class
@protected NSMutableDictionary*
_fontCollectionDictionary;
Availability: MacOS-X 10.7.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.
- Declared in:
- AppKit/NSFontCollection.h
Availability: MacOS-X 10.7.0
NSMutableFontCollection extends
NSFontCollection to provide methods for
dynamically modifying font collections after
creation. This allows applications to build and
adjust font collections programmatically based on
changing requirements or user preferences. The
mutable variant supports adding and removing query
descriptors, changing exclusion criteria, and
updating the collection's font matching behavior
without creating entirely new collection objects.
This is particularly useful for interactive font
selection interfaces, style editors, and
applications that need to respond to dynamic
font requirements. Like its immutable counterpart,
mutable font collections can be saved and retrieved
by name at various visibility levels, allowing modified
collections to be preserved and shared across
application sessions or between applications.
+ (
NSMutableFontCollection*)
fontCollectionWithAllAvailableDescriptors;
Availability: MacOS-X 10.7.0
Creates a mutable font collection containing all
available fonts. This method creates a mutable
collection that initially contains all system
fonts, but can be modified after creation to add
filters, exclusions, or other constraints. Returns
a new mutable font collection containing all system
fonts.
+ (
NSMutableFontCollection*)
fontCollectionWithDescriptors: (
NSArray*)queryDescriptors;
Availability: MacOS-X 10.7.0
Creates a mutable font collection from an array of
font descriptors. This method creates a new mutable
font collection that can be modified after creation.
The queryDescriptors parameter specifies the
initial set of font descriptors defining the
collection's content. Returns a new mutable
font collection with the specified initial
descriptors.
+ (
NSMutableFontCollection*)
fontCollectionWithLocale: (
NSLocale*)locale;
Availability: MacOS-X 10.7.0
Creates a mutable font collection filtered by
locale. This method creates a mutable
collection with an initial set of fonts
appropriate for the specified locale
, but allows subsequent modification of the collection's
criteria. The locale parameter
specifies the target locale. Returns a
new mutable font collection suitable for the given
locale.
+ (
NSMutableFontCollection*)
fontCollectionWithName: (
NSFontCollectionName)name;
Availability: MacOS-X 10.7.0
Creates a mutable font collection by loading a
saved collection by name. This method
retrieves a saved font collection and returns it
as a mutable collection that can be modified. The
name parameter specifies the collection to
load from any visibility level. Returns a mutable copy
of the named font collection, or nil if not
found.
+ (
NSMutableFontCollection*)
fontCollectionWithName: (
NSFontCollectionName)name
visibility: (
NSFontCollectionVisibility)visibility;
Availability: MacOS-X 10.7.0
Creates a mutable font collection by loading from a
specific visibility level. This method
retrieves a saved font collection from the
specified visibility level and returns
it as a mutable collection. The name
parameter specifies the collection to load, and
visibility indicates where to search.
Returns a mutable copy of the named collection from
the specified level, or nil if not found.
- (void)
addQueryForDescriptors: (
NSArray*)descriptors;
Availability: MacOS-X 10.7.0
Adds additional query descriptors to the
collection. This method expands the
collection's inclusion criteria by adding new
query descriptors to the existing set.
Fonts matching any of the descriptors
(existing or new) will be included in the
collection. The descriptors
parameter specifies the additional criteria to
add.
- (
NSArray*)
exclusionDescriptors;
Availability: MacOS-X 10.7.0
Returns the exclusion descriptors for the mutable
collection. This method returns the current set
of exclusion descriptors that define which fonts are
explicitly excluded from the collection, even if
they would otherwise match the query descriptors.
Returns an array of NSFontDescriptor objects
defining current exclusion criteria.
- (
NSArray*)
queryDescriptors;
Availability: MacOS-X 10.7.0
Returns the query descriptors for the mutable
collection. This method returns the current set
of query descriptors that define which fonts are
included in the collection. The returned array can
be used to examine the current inclusion criteria.
Returns an array of NSFontDescriptor objects
defining current inclusion criteria.
- (void)
removeQueryForDescriptors: (
NSArray*)descriptors;
Availability: MacOS-X 10.7.0
Removes query descriptors from the
collection. This method narrows the
collection's inclusion criteria by removing
specific query descriptors from the
existing set. Fonts that only matched the removed
descriptors will no longer be included in
the collection. The descriptors parameter
specifies the criteria to remove.
- (void)
setExclusionDescriptors: (
NSArray*)exclusionDescriptors;
Availability: MacOS-X 10.7.0
Sets the exclusion descriptors for the mutable
collection. This method replaces the current
exclusion descriptors with a new set, changing
which fonts are explicitly excluded from the
collection. The exclusionDescriptors
parameter specifies the new exclusion criteria.
- (void)
setQueryDescriptors: (
NSArray*)queryDescriptors;
Availability: MacOS-X 10.7.0
Sets the query descriptors for the mutable collection.
This method replaces the current query descriptors
with a new set, changing which fonts are included in
the collection. The queryDescriptors
parameter specifies the new inclusion criteria.
Up