NSFontCollection Class Reference

Inherits from
Conforms to
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
Declared In
NSFontCollection.h