Core Text Font Manager Reference

Framework
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

Creating and Enabling Font Descriptors

Registering and Activating Fonts

Validating Font Files

Functions

CTFontManagerCreateFontDescriptorsFromURL

Returns an array of font descriptors representing each of the fonts in the specified URL.

CFArrayRef CTFontManagerCreateFontDescriptorsFromURL(
   CFURLRef fileURL
);
Parameters
fileURL

A file system URL referencing a valid font file.

Return Value

This function returns a retained reference to a CFArray of CTFontDescriptorRef objects, or NULL on error. The caller is responsible for releasing the array.

Availability
  • Available in iOS 7.0 and later.
Declared In
CTFontManager.h

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 Registry Change Notification

Notification name for font registry changes.

const CFStringRef kCTFontManagerRegisteredFontsChangedNotification
Constants
kCTFontManagerRegisteredFontsChangedNotification

This is the string to use as the notification name when subscribing to Core Text Font Manager notifications. This notification is posted when fonts are added to the font registry. The client is responsible for registered with the distributed notification center to receive notifications for changes to the session or user scopes, and with a local notification center for changes to the process scope.

Available in iOS 7.0 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 3.2 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 3.2 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.