Creating a Font Panel

In general, you add the facilities of the Font panel to your application, along with the NSFontManager object and the Font menu, through which the user opens the Font panel, using Interface Builder. You do this by dragging a Font or Format menu (which contains a Font submenu) into one of your application’s menus. At runtime, the Font panel object is created and hooked into the font conversion system. You can also create (or access) the Font panel using the sharedFontPanel class method.

You can add a custom view object to an NSFontPanel object using setAccessoryView:, allowing you to add custom controls to the Font panel. You can also limit the fonts displayed (by default, all fonts are displayed) by assigning a delegate to the application’s font manager object.

If you want the NSFontManager object to instantiate the Font panel from some class other than NSFontPanel, use the NSFontManager class method setFontPanelFactory:. See Converting Fonts Manually for more information on using the font conversion system.

Using the Font Panel

You can enable the interaction between a text object and the Font panel using the NSTextView (or NSText) method setUsesFontPanel: method. Doing so is recommended for a text view that serves as a field editor, for example.

You can use the Font panel on objects other than standard text fields. The NSFontManager method setAction: sets the action (specified by a selector) that is sent up the first responder chain when a new font is selected. The default selector is changeFont:. Any object that receives this message from the responder chain should send a convertFont: message back to the NSFontManager to convert the font in a manner the user has specified.

This example assumes there is only one font selected:

– (void)changeFont:(id)sender

{

    NSFont *oldFont = [self font];

    NSFont *newFont = [sender convertFont:oldFont];

    [self setFont:newFont];

    return;

}

If multiple fonts are selected, changeFont: must send conversion messages for each selected font. This is useful for objects such as table views, which do not inherently respond to messages from the Font panel.

Font Descriptors

Font descriptors, instantiated from the NSFontDescriptor class, provide a way to describe a font with a dictionary of attributes. The font descriptor can then be used to create or modify an NSFont object. In particular, you can make an NSFont object from a font descriptor, you can get a descriptor from an NSFont object, and you can change a descriptor and use it to make a new font object. You can also use a font descriptor to specify custom fonts provided by an app.

Font descriptors provide a font matching capability by which you can partially describe a font by creating a font descriptor with, for example, just a family name. You can then find all the available fonts on the system with a matching family name using matchingFontDescriptorsWithMandatoryKeys:.

Font descriptors can be archived, which is preferrable to archiving a font object because a font object is immutable and provides access to a particular font installed on a particular system. A font descriptor, on the other hand, describes a font in terms of its characteristics, its attributes, and provides access at runtime to the fonts currently available that match those attributes.

That is, you can use font descriptors to query the system for available fonts that match particular attributes, and then create instances of NSFont matching those attributes, such as names, traits, languages, and other features. For example, you can use a font descriptor to retrieve all the fonts matching a given font family name, using the PostScript family names (as defined by the CSS standard) as shown in Listing 6-1.

Listing 6-1  Font family name matching

NSFontDescriptor *helveticaNeueFamily =

    [NSFontDescriptor fontDescriptorWithFontAttributes:

        @{ NSFontFamilyAttribute: @"Helvetica Neue" }];

NSArray *matches =

    [helveticaNeueFamily matchingFontDescriptorsWithMandatoryKeys: nil];

The matchingFontDescriptorsWithMandatoryKeys: method as shown returns an array of font descriptors for all the Helvetica Neue fonts on the system, such as HelveticaNeue, HelveticaNeue-Medium, HelveticaNeue-Light, HelveticaNeue-Thin, and so on. (PostScript font and font family names for the fonts available on a given OS X installation are displayed by the Font Book app in the Font Info window.)

Querying Font Metrics

NSFont defines a number of methods for accessing a font’s metrics information, when that information is available. Methods such as boundingRectForGlyph:, boundingRectForFont, xHeight, and so on, all correspond to standard font metrics information. Figure 6-1 shows how the font metrics apply to glyph dimensions, and Table 6-1 lists the method names that correlate with the metrics. See the various method descriptions for more specific information.

Querying Standard Font Variations

Using the methods of NSFont listed in Table 6-2, you can query all of the standard font variations. To request the default font size for the standard fonts, you can either explicitly pass in default sizes (obtained from class methods such as systemFontSize and labelFontSize), or pass in 0 or a negative value.

Characters, Glyphs, and the Layout Manager

Characters are conceptual entities that correspond to units of written language. Generally, a glyph is the concrete, rendered image of a character. (Typographical Concepts presents a more detailed discussion of characters and glyphs.)

In English, there’s often a one-to-one mapping between characters and glyphs, but that is not always the case. For example, the glyph “ö” can be the result of two characters, one representing the base character “o” and the other representing the umlaut diacritical mark “¨”. A user of a word processor can press an arrow key one time to move the insertion point from one side of the “ö” glyph to the other; however, the current position in the character stream must be incremented by two to account for the two characters that make up the single glyph.

Thus, the text system must manage two related but different streams of data: the stream of characters (and their attributes) and the stream of glyphs that are derived from these characters. The NSTextStorage object stores the attributed characters, and the NSLayoutManager object stores the derived glyphs. Finding the correspondence between these two streams is the responsibility of the layout manager. For example, when a user selects a range of text, working with glyphs displayed on screen, the layout manager must determine which range of characters corresponds to the selection.

When characters are deleted, some glyphs may have to be redrawn. For example, if the user deletes the characters “ee” from the word “feel”, then the “f” and “l” are now adjacent and can be represented by the “fl” ligature rather than the two glyphs “f” and “l”. The NSLayoutManager object directs a glyph generator object to generate new glyphs as needed. Once the glyphs are regenerated, the text must be laid out and displayed. Working with the NSTextContainer object and other objects of the text system, the layout manager determines where each glyph appears in the text view. Finally, the text view renders the text.

Because an NSLayoutManager object is central to the operation of the text system, it also serves as the repository of information shared by various components of the system. For more information about NSLayoutManager, refer to NSLayoutManager Class Reference and to Text Layout Programming Guide.

Getting the View Coordinates of a Glyph

Glyph locations are figured relative to the origin of the bounding rectangle of the line fragment in which they are laid out. To get the rectangle of the glyph’s line fragment in its container coordinates, use the NSLayoutManager method lineFragmentRectForGlyphAtIndex:effectiveRange:. Then add the origin of that rectangle to the location of the glyph returned by locationForGlyphAtIndex: to get the glyph location in container coordinates.

The following code fragment from the CircleView sample code project illustrates this technique.

usedRect = [layoutManager usedRectForTextContainer:textContainer];

NSRect lineFragmentRect = [layoutManager lineFragmentRectForGlyphAtIndex:glyphIndex

                            effectiveRange:NULL];

NSPoint viewLocation, layoutLocation = [layoutManager

                            locationForGlyphAtIndex:glyphIndex];

// Here layoutLocation is the location (in container coordinates) where the glyph was laid out.

layoutLocation.x += lineFragmentRect.origin.x;

layoutLocation.y += lineFragmentRect.origin.y;

Creating a Font Manager

You normally set up a font manager and the Font menu using Interface Builder. However, you can also do so programmatically by getting the shared font manager instance and having it create the standard Font menu at runtime, as in this example:

NSFontManager *fontManager = [NSFontManager sharedFontManager];

NSMenu *fontMenu = [fontManager fontMenu:YES];

You can then add the Font menu to your application’s menus. Once the Font menu is installed, your application automatically gains the functionality of both the Font menu and the Font panel.

Handling Font Changes

The user normally changes the font of the selection by manipulating the Font panel (also called the Fonts window) and the Font menu. These objects initiate the intended change by sending an action message to the font manager. There are four font-changing action methods:

• addFontTrait:

• removeFontTrait:

• modifyFont:

• modifyFontViaPanel:

The first three cause the font manager to query the sender of the message in order to determine which trait to add or remove, or how to modify the font. The last causes the font manager to use the settings in the Font panel to modify the font. The font manager records this information and uses it in later requests to convert fonts.

When the font manager receives an addFontTrait: or removeFontTrait: message, it queries the sender with a tag message, interpreting the return value as a trait mask for use with convertFont:toHaveTrait: or convertFont:toNotHaveTrait:, as described in Converting Fonts Manually. The Font menu commands Italic and Bold, for example, have trait mask values of NSItalicFontMask and NSBoldFontMask, respectively. See the Constants section in NSFontManager Class Reference for a list of trait mask values.

When the font manager receives a modifyFont: message, it queries the sender with a tag message and interprets the return value as a particular kind of conversion to perform, via the various conversion methods described in Converting Fonts Manually. For example, a button whose tag value is SizeUpFontAction causes the font manager’s convertFont: method to increase the size of the NSFont object passed as the parameter. See the NSFontManager method modifyFont: for a list of conversion tag values.

For modifyFontViaPanel:, the font manager sends the application’s Font panel a panelConvertFont: message. The Font panel in turn uses the font manager to convert the font provided according to the user’s choices. For example, if the user selects only the font family in the Font panel (perhaps Helvetica), then for whatever fonts are provided to panelConvertFont:, only the family is changed: Courier Medium 10.0 point becomes Helvetica Medium 10.0 point, and Times Italic 12.0 point becomes Helvetica Oblique 12.0 point.

The font manager responds to a font-changing action method by sending a changeFont: action message up the responder chain. A text-bearing object that receives this message should have the font manager convert the fonts in its selection by invoking convertFont: for each font and using the NSFont object returned. The convertFont: method uses the information recorded by the font-changing action method, such as addFontTrait:, modifying the font provided appropriately. (There’s no way to explicitly set the font-changing action or trait; instead, you use the methods described in Converting Fonts Manually.)

This simple example assumes there’s only one font in the selection:

- (void)changeFont:(id)sender

{

    NSFont *oldFont = [self selectionFont];

    NSFont *newFont = [sender convertFont:oldFont];

    [self setSelectionFont:newFont];

    return;

}

Most text-bearing objects have to scan the selection for ranges with different fonts and invoke convertFont: for each one.

Converting Fonts Manually

NSFontManager defines a number of methods for explicitly converting particular traits and characteristics of a font. Table 6-3 lists these conversion methods.

Each method returns a transformed version of the font provided, or the original font if it can’t be converted.

The default implementation of font conversion is very conservative, making a change only if no other trait or aspect is affected. For example, if you try to convert Helvetica Oblique 12.0 point by adding the Bold trait, and only Helvetica Bold is available, the font isn’t converted. You can create a subclass of NSFontManager and override the conversion methods to perform less conservative conversion, perhaps using Helvetica Bold in this case and losing the Oblique trait.

In addition to the font-conversion methods, NSFontManager defines fontWithFamily:traits:weight:size: to construct a font with a given set of characteristics. If you don’t care to make a subclass of NSFontManager, you can use this method to perform approximate font conversions yourself.

Setting Font Styles and Traits

This section shows how to programmatically set font styles, such as bold or italic, and font attributes, such as underlining, in an attributed string.

Underlining is an attribute that can be easily set on an attributed string, using the NSUnderlineStyleAttributeName constant, as explained in NSMutableAttributedString Class Reference. Use the following method:

- (void)addAttribute:(NSString *)name value:(id)value range:(NSRange)aRange

Pass NSUnderlineStyleAttributeName for the name parameter with a value of [NSNumber numberWithInt:1].

Unlike underlining, bold and italic are traits of the font, so you need to use a font manager instance to convert the font to have the desired trait, then add the font attribute to the mutable attributed string. For a mutable attributed string named attributedString, use the following technique:

NSFontManager *fontManager = [NSFontManager sharedFontManager];

unsigned idx = range.location;

NSRange fontRange;

NSFont *font;

while (NSLocationInRange(idx, range)){

    font = [attributedString attribute:NSFontAttributeName atIndex:idx

                            longestEffectiveRange:&fontRange inRange:range];

    fontRange = NSIntersectionRange(fontRange, range);

    [attributedString applyFontTraits:NSBoldFontMask range:fontRange];

    idx = NSMaxRange(fontRange);

}

If your mutable attributed string is actually an NSTextStorage object, place this code between beginEditing and endEditing calls.

Examining Fonts

In addition to converting fonts, NSFontManager provides information on which fonts are available to the application and on the characteristics of any given font. The availableFonts method returns an array of the names of all fonts available. The availableFontNamesWithTraits: method filters the available fonts based on a font trait mask.

There are three methods for examining individual fonts. The fontNamed:hasTraits: method returns true if the font matches the trait mask provided. The traitsOfFont: method returns a trait mask for a given font. The weightOfFont: method returns an approximate ranking of a font’s weight on a scale of 0–15, where 0 is the lightest possible weight, 5 is Normal or Book weight, 9 is the equivalent of Bold, and 15 is the heaviest possible (often called Black or Ultra Black).

Customizing the Font Conversion System

If you need to customize the font conversion system by creating subclasses of NSFontManager or NSFontPanel, you must inform the NSFontManager class of this change with a setFontManagerFactory: or setFontPanelFactory: message, before either the shared font manager or shared Font panel is created. These methods record your class as the one to instantiate the first time the font manager or Font panel is requested. You may be able to avoid using subclasses if all you need is to add some custom controls to the Font panel. In this case, you can invoke the NSFontPanel method setAccessoryView: to add an NSView object below its font browser.

If you provide your own Font menu, you should register it with the font manager using the setFontMenu: method. The font manager is responsible for validating Font menu items and changing their titles and tags according to the selected font. For example, when the selected font is Italic, the font manager adds a check mark to the Italic Font menu item and changes its tag to UnitalicMask. Your Font menu’s items should use the appropriate action methods and tags, as shown in Table 6-4.

See also the following documents: Attributed String Programming Guide describes NSAttributedString objects, which manage sets of attributes, such as font and kerning, that are associated with character strings or individual characters. Text Layout Programming Guide describes how the Cocoa text system converts strings of text characters, font information, and page specifications into lines of glyphs placed at specific locations on a page, suitable for display and printing.