Core Text Font Manager Reference

Framework	ApplicationServices/CoreText
Declared in	CTFontManager.h CTFontManagerErrors.h

Overview

This reference document describes the functions and constants used to manage fonts in Core Text.

Functions by Task

Registering and Activating Fonts

Validating Font Files

Functions

CTFontManagerIsSupportedFontFile

Determines whether the referenced font data (usually by file URL) is supported on the current platform.

bool CTFontManagerIsSupportedFont(
   CFURLRef fontURL
);

Parameters

fontURL: A URL referring to font data.

Return Value

Returns true if the URL refers to a valid font that can be used on the current platform; false otherwise.

CTFontManagerRegisterFontsForURL

Registers fonts from the specified font URL with the Font Manager. Registered fonts are discoverable through font descriptor matching.

bool CTFontManagerRegisterFontsForURL(
   CFURLRef fontURL,
   CTFontManagerScope scope,
   CFErrorRef * error
);

Parameters

fontURL: The font URL.
scope: Scope constant defining the availability and lifetime of the registration. See “Font Registration Scope” for values to pass for this parameter.
error: Pointer to a CFError object which, in case of failed registration, contains error information.

Return Value

Returns true if registration of the fonts was successful, otherwise false.

Availability

Available in iOS 4.1 and later.

Declared In

CTFontManager.h

CTFontManagerRegisterFontsForURLs

Registers fonts from the specified array of font URLs with the Font Manager. Registered fonts are discoverable through font descriptor matching.

bool CTFontManagerRegisterFontsForURLs(
   CFArrayRef fontURLs,
   CTFontManagerScope scope,
   CFArrayRef * errors
);

Parameters

fontURLs: Array of font URLs.
scope: Scope constant defining the availability and lifetime of the registration. See “Font Registration Scope” for values to pass for this parameter.
errors: Pointer to an array of CFError objects which, in case of failed registration, contain error information. Each error contains a CFArray of font URLs corresponding to kCTFontManagerErrorFontURLsKey. These URLs represent the font files that caused the error and were not successfully registered. The array must be released by the caller. Can be NULL.

Return Value

Returns true if registration of all font URLs was successful, otherwise false.

Availability

Available in iOS 4.1 and later.

Declared In

CTFontManager.h

CTFontManagerRegisterGraphicsFont

Registers the specified graphics font with the font manager.

bool CTFontManagerRegisterGraphicsFont(
   CGFontRef font,
   CFErrorRef *error )

Parameters

font: The graphics font to be registered.
error: Returns by indirection an error object in the case of failed registration.

Return Value

true if registration of the font was successful, otherwise false.

Discussion

Registered fonts are discoverable through font descriptor matching. Any attempt to register a font that is either already registered or contains the same Postscript of an already registered font will fail. This behavior is useful for fonts that may be embedded in documents or constructed in memory. A graphics font is obtained by calling CGFontCreateWithDataProvider. Fonts that are backed by files should be registered using CTFontManagerRegisterFontsForURL.

Availability

Available in iOS 4.1 and later.

Declared In

CTFontManager.h

CTFontManagerUnregisterFontsForURL

Unregisters fonts from the specified font URL with the Font Manager. Unregistered fonts are no longer discoverable through font descriptor matching.

bool CTFontManagerUnregisterFontsForURL(
   CFURLRef fontURL,
   CTFontManagerScope scope,
   CFErrorRef * error
);

Parameters

fontURL: The font URL.
scope: Scope constant defining the availability and lifetime of the registration. See “Font Registration Scope” for values to pass for this parameter.
error: Pointer to a CFError object which, in case of failed registration, contains error information.

Return Value

Returns true if unregistration of the fonts was successful, otherwise false.

Availability

Available in iOS 4.1 and later.

Declared In

CTFontManager.h

CTFontManagerUnregisterFontsForURLs

Unregisters fonts from the specified array of font URLs with the Font Manager. Unregistered fonts are no longer discoverable through font descriptor matching.

bool CTFontManagerUnregisterFontsForURLs(
   CFArrayRef fontURLs,
   CTFontManagerScope scope,
   CFArrayRef * errors
);

Parameters

fontURLs: Array of font URLs.
scope: Scope constant defining the availability and lifetime of the registration. See “Font Registration Scope” for values to pass for this parameter.
errors: Pointer to an array of CFError objects which, in case of failed registration, contain error information. Each error contains a CFArray of font URLs corresponding to kCTFontManagerErrorFontURLsKey. These URLs represent the font files that caused the error and were not successfully registered. The array must be released by the caller. Can be NULL.

Return Value

Returns true if unregistration of all font URLs was successful, otherwise false.

Availability

Available in iOS 4.1 and later.

Declared In

CTFontManager.h

CTFontManagerUnregisterGraphicsFont

Unregisters the specified graphics font with the font manager.

bool CTFontManagerUnregisterGraphicsFont(
   CGFontRef font,
   CFErrorRef *error )(

Parameters

font: The graphics font to be unregistered.
error: Returns by indirection an error object in the case of failed unregistration.

Return Value

true if unregistration of the font was successful, otherwise false.

Discussion

Unregistered fonts are no longer discoverable through font descriptor matching. Fonts that are backed by files should be unregistered using CTFontManagerUnregisterFontsForURL.

Availability

Available in iOS 4.1 and later.

Declared In

CTFontManager.h

Constants

Font Registration Scope

These constants define the scope for font registration.

enum {
   kCTFontManagerScopeNone = 0,
   kCTFontManagerScopeProcess = 1,
   kCTFontManagerScopeUser = 2,
   kCTFontManagerScopeSession = 3
};
typedef uint32_t CTFontManagerScope;

Constants

kCTFontManagerScopeNone

No scope is defined.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

kCTFontManagerScopeProcess

The font is available to the current process for the duration of the process unless directly unregistered.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

kCTFontManagerScopeUser

The font is available to all processes for the current user session and will be available in subsequent sessions unless unregistered.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

kCTFontManagerScopeSession

The font is available to the current user session but will not be available in subsequent sessions.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

Font Auto-Activation Settings

Sets the auto-activation for the specified bundle identifier.

enum {
   kCTFontManagerAutoActivationDefault = 0,
   kCTFontManagerAutoActivationDisabled = 1,
   kCTFontManagerAutoActivationEnabled = 2,
   kCTFontManagerAutoActivationPromptUser = 3
};
typedef uint32_t CTFontManagerAutoActivationSetting;

Constants

kCTFontManagerAutoActivationDefault

Default auto-activation setting. When specified, the application uses the global setting.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

kCTFontManagerAutoActivationDisabled

Disables auto-activation.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

kCTFontManagerAutoActivationEnabled

Enables auto-activation.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

kCTFontManagerAutoActivationPromptUser

Requires user input for auto-activation. A dialog is presented to the user to confirm auto-activation of the font.

Available in iOS 4.1 and later.

Declared in CTFontManager.h.

Font Manager Error Domain and User Info Key

CFError domain and user info key for Font Manager errors.

const CFStringRef kCTFontManagerErrorDomain;
const CFStringRef kCTFontManagerErrorFontURLsKey;

Constants

kCTFontManagerErrorDomain

CFError objects with this domain have error codes corresponding to one of the CTFontManagerError errors listed in “Font Registration Errors” and “Font Unregistration Errors.”

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

kCTFontManagerErrorFontURLsKey

User info key to be used with CFError references returned from registration functions. The value associated with this key in the user info dictionary of a CFError object is a CFArray of font URLs that failed with the given error.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

Font Registration Errors

Errors that would prevent registration of fonts for a specified font file URL.

enum {
   kCTFontManagerErrorFileNotFound = 101,
   kCTFontManagerErrorInsufficientPermissions = 102,
   kCTFontManagerErrorUnrecognizedFormat = 103,
   kCTFontManagerErrorInvalidFontData = 104,
   kCTFontManagerErrorAlreadyRegistered = 105,
};

Constants

kCTFontManagerErrorFileNotFound

The file does not exist at the specified URL.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

kCTFontManagerErrorInsufficientPermissions

Cannot access the file due to insufficient permissions.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

kCTFontManagerErrorUnrecognizedFormat

The file is not a recognized or supported font file format.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

kCTFontManagerErrorInvalidFontData

The file contains invalid font data that could cause system problems.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

kCTFontManagerErrorAlreadyRegistered

The file has already been registered in the specified scope.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

Font Unregistration Errors

Errors that would prevent unregistration of fonts for a specified font file URL.

enum {
   kCTFontManagerErrorNotRegistered = 201,
   kCTFontManagerErrorInUse = 202,
   kCTFontManagerErrorSystemRequired = 202,
};
typedef CFIndex CTFontManagerError;

Constants

kCTFontManagerErrorNotRegistered

The file is not registered in the specified scope.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

kCTFontManagerErrorInUse

The font file is actively in use and cannot be unregistered.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

kCTFontManagerErrorSystemRequired

The file is required by the system and cannot be unregistered.

Available in iOS 4.1 and later.

Declared in CTFontManagerErrors.h.

Did this document help you?

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

Core Text Font Manager Reference

Overview

Functions by Task

Registering and Activating Fonts

Validating Font Files

Functions

CTFontManagerIsSupportedFontFile

Parameters

Return Value

CTFontManagerRegisterFontsForURL

Parameters

Return Value

Availability

Declared In

CTFontManagerRegisterFontsForURLs

Parameters

Return Value

Availability

Declared In

CTFontManagerRegisterGraphicsFont

Parameters

Return Value

Discussion

Availability

See Also

Declared In

CTFontManagerUnregisterFontsForURL

Parameters

Return Value

Availability

Declared In

CTFontManagerUnregisterFontsForURLs

Parameters

Return Value

Availability

Declared In

CTFontManagerUnregisterGraphicsFont

Parameters

Return Value

Discussion

Availability

See Also

Declared In

Constants

Font Registration Scope

Constants

Font Auto-Activation Settings

Constants

Font Manager Error Domain and User Info Key

Constants

Font Registration Errors

Constants

Font Unregistration Errors

Constants