NSFontCollection Class Reference

Inherits from	NSObject
Conforms to	NSCoding NSCopying NSMutableCopying NSObject (NSObject)
Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in OS X v10.7 and later.
Declared in	NSFontCollection.h

Overview

The NSFontCollection class represents a font collection, that is, a group of font descriptors taken together as a single object. You can publicize the font collection as a named collection and it is presented through the System user interface such as the font panel & Font Book. The queries can be modifed using the NSMutableFontCollection subclass.

Tasks

Creating Font Collections

Naming Font Collections

Font Collection Descriptor Matching

Class Methods

allFontCollectionNames

Returns all named collections visible to this process.

+ (NSArray *)allFontCollectionNames

Return Value

NSString objects containing the names of all the named collections.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

fontCollectionWithAllAvailableDescriptors

Returns a font collection matching all registered fonts.

+ (id)fontCollectionWithAllAvailableDescriptors

Return Value

The collection of all fonts available to the current application.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

fontCollectionWithDescriptors:

Returns a font collection matching the given descriptors.

+ (id)fontCollectionWithDescriptors:(NSArray *)queryDescriptors

Parameters

queryDescriptors: The descriptors used to match the returned collection.

Return Value

The font collection matching the given descriptors.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

fontCollectionWithLocale:

Returns a collection of fonts matching the given locale.

+ (id)fontCollectionWithLocale:(NSLocale *)locale

Parameters

locale: The locale to match.

Return Value

A collection of fonts matching the given locale.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

fontCollectionWithName:

Returns the font collection with the specified name.

+ (id)fontCollectionWithName:(NSString *)name

Parameters

name: The name of the collection.

Return Value

The named font collection.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

fontCollectionWithName:visibility:

Returns the font collection with the specified name and visibility.

+ (id)fontCollectionWithName:(NSString *)name visibility:(NSFontCollectionVisibility)visibility

Parameters

name: The name of the collection.
visibility: The visibility of the collection.

Return Value

The font collection with the specified nam and visibility.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

hideFontCollectionWithName:visibility:error:

Remove from view the named font collection with the specified visibility.

+ (BOOL)hideFontCollectionWithName:(NSString *)name visibility:(NSFontCollectionVisibility)visibility error:(NSError **)error

Parameters

name: The name of the collection.
visibility: The visibility of the collection.
error: If unsuccessful, a reference to an NSFileManager error object that encapsulates the reason the font collection could not be returned.

Return Value

YES if the method was successful; NO otherwise.

Discussion

For a persistent font collection, this method deletes the named font collection from disk.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

renameFontCollectionWithName:visibility:toName:error:

Renames the font collection with the specified name and visibility to the second name specified.

+ (BOOL)renameFontCollectionWithName:(NSString *)name visibility:(NSFontCollectionVisibility)visibility toName:(NSString *)name error:(NSError **)error

Parameters

name: The collection to rename.
visibility: The visibility of the collection to rename.
name: The new name to give to the collection.
error: If unsuccessful, a reference to an NSFileManager error object that encapsulates the reason the font collection could not be renamed.

Return Value

YES if the method was successful; NO otherwise.

Discussion

Named collections are shown by user interfaces such as the Font panel. When you change the collection, you must show it again to see the changes reflected on disk or in the Font panel.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

showFontCollection:withName:visibility:error:

Make the given font collection visible by giving it a name.

+ (BOOL)showFontCollection:(NSFontCollection *)collection withName:(NSString *)name visibility:(NSFontCollectionVisibility)visibility error:(NSError **)error

Parameters

collection: The font collection to make visible.
name: The name to associate with the collection.
visibility: The visibility of the collection to show.
error: If unsuccessful, a reference to an NSFileManager error object that encapsulates the reason the font collection could not be renamed.

Return Value

YES if the method was successful; NO otherwise.

Discussion

Named collections are shown by user interfaces such as the Font panel. When you change the collection, you must show it again to see the changes reflected on disk or in the Font panel.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

Instance Methods

exclusionDescriptors

Returns a list of query font descriptors whose matching results are excluded from the list of matching descriptors.

- (NSArray *)exclusionDescriptors

Return Value

The font descriptors used to match for exclusion descriptors.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

matchingDescriptors

Returns an array of font descriptors matching the logical descriptors.

- (NSArray *)matchingDescriptors

Return Value

The font descriptors matching queryDescriptors minus those matching exclusionDescriptors.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

matchingDescriptorsForFamily:

Returns an array of font descriptors matching the logical descriptors for the given font family.

- (NSArray *)matchingDescriptorsForFamily:(NSString *)family

Parameters

family: The font family whose descriptors are matched.

Return Value

The matchingDescriptors for the given family.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

matchingDescriptorsForFamily:options:

Returns an array of font descriptors matching the logical descriptors for the given font family and options.

- (NSArray *)matchingDescriptorsForFamily:(NSString *)family options:(NSDictionary *)options

Parameters

family: The font family whose descriptors are matched.
options: A dictionary containing any combination of the “Matching Descriptors Options” keys or nil.

Return Value

The matchingDescriptors for the given family and options.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

matchingDescriptorsWithOptions:

Returns an array of font descriptors matching the logical descriptors with the given options.

- (NSArray *)matchingDescriptorsWithOptions:(NSDictionary *)options

Parameters

options: A dictionary containing any combination of the “Matching Descriptors Options” keys or nil.

Return Value

The matchingDescriptors for the given options.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

queryDescriptors

Returns an array of font descriptors whose matching results produce the collection’s matching descriptors.

- (NSArray *)queryDescriptors

Return Value

The font descriptors matched at runtime to produce matchingDescriptors.

Discussion

The font descriptors matching exclusionDescriptors are removed from matchingDescriptors.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

Constants

Standard Named Font Collections

The constants represent the standard mutable collection names—these names are included in the list of allFontCollectionNames--they have special meaning to the Cocoa font system and should not be hidden or renamed.

NSString * const NSFontCollectionAllFonts;
NSString * const NSFontCollectionUser;
NSString * const NSFontCollectionFavorites;
NSString * const NSFontCollectionRecentlyUsed;

Constants

NSFontCollectionAllFonts

All fonts in the system.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionUser

Per-user unmodifiable collection.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionFavorites

Font collection of the user's preferred font descriptors.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionRecentlyUsed

Font collection automatically maintained by NSFontManager.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

Matching Descriptors Options

These constants are used by the matchingDescriptorsWithOptions: and matchingDescriptorsForFamily:options: options dictionary parameters.

NSString * const NSFontCollectionIncludeDisabledFontsOption;
NSString * const NSFontCollectionRemoveDuplicatesOption;
NSString * const NSFontCollectionDisallowAutoActivationOption;

Constants

NSFontCollectionIncludeDisabledFontsOption

An NSNumber object containing a Boolean value specifying whether disabled fonts should be included in the list of matching descriptors; YES if they should be included, NO otherwise.. When unspecified, CoreText assumes NO. This option is intended only for font management applications. This option will make descriptor matching slower.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionRemoveDuplicatesOption

An NSNumber object containing a Boolean value controlling whether more than one copy of a font with the same PostScript name should be included in the list of matching descriptors.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionDisallowAutoActivationOption

An NSNumber object containing a Boolean value specifying that auto-activation should not be used to find missing fonts.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionVisibility

These constants specify the visibility of font collections.

enum {
   NSFontCollectionVisibilityProcess = (1UL << 0),
   NSFontCollectionVisibilityUser = (1UL << 1),
   NSFontCollectionVisibilityComputer = (1UL << 2)
};
typedef NSUInteger NSFontCollectionVisibility;

Constants

NSFontCollectionVisibilityProcess

The font collection is visible within this process and is not persistent.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionVisibilityUser

The font collection is visible to all processes and is stored persistently.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionVisibilityComputer

The font collection is visible to all users and is stored persistently.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionDidChangeNotification UserInfo Keys

These constants are used as keys in the NSFontCollectionDidChangeNotification userInfo dictionary to indicate the changes that have taken place.

NSString * const NSFontCollectionActionKey;
NSString * const NSFontCollectionNameKey;
NSString * const NSFontCollectionOldNameKey;
NSString * const NSFontCollectionVisibilityKey;

Constants

NSFontCollectionActionKey

An action was taken. See “NSFontCollectionAction Key Values” for the possible values. An NSString.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionNameKey

The font collection’s name. If renamed, this is the new name. An NSString.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionOldNameKey

Included as a value for the NSFontCollectionOldNameKey key, if present. This is the previous name. An NSString.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionVisibilityKey

The visibly of the font collection. An NSNumber containing a value from the “NSFontCollectionVisibility” enum.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionAction Key Values

The following actions are possible values of the NSFontCollectionActionKey in the NSFontCollectionDidChangeNotification userInfo method.

NSString * const NSFontCollectionWasShown;
NSString * const NSFontCollectionWasHidden;
NSString * const NSFontCollectionWasRenamed;

Constants

NSFontCollectionWasShown

The font collection was shown.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionWasHidden

The font collection was hidden.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

NSFontCollectionWasRenamed

The font collection was renamed.

Available in OS X v10.7 and later.

Declared in NSFontCollection.h.

Notifications

NSFontCollectionDidChangeNotification

Posted whenever a font collection is changed.

The notification's object is the font collection that was affected. The notification's userInfo dictionary contains information about the the collection change containing the keys defined in “NSFontCollectionDidChangeNotification UserInfo Keys” and the corresponding values.

Availability

Available in OS X v10.7 and later.

Declared In

NSFontCollection.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.