Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSFont


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


NSFont objects represent PostScript fonts to an application, providing access to characteristics of the font and assistance in laying out glyphs relative to one another. Font objects are also used to establish the current font when drawing in an NSView, using the set method.

You don't create Font objects using a constructor. Instead, you use either fontWithNameAndMatrix or fontWithNameAndSize to look up an available font and alter its size or matrix to your needs. These methods check for an existing font object with the specified characteristics, returning it if there is one. Otherwise, they look up the font data requested and create the appropriate object. NSFont also defines a number of methods for getting standard system fonts, such as systemFontOfSize, userFontOfSize, and messageFontOfSize.


Drawing Text with NSFonts


In most cases you draw text using an NSTextView object.

If you need to draw text using PostScript operators such as show, it's recommended that you set the current font using NSFont's set method, rather than the PostScript operators setfont or selectfont. This allows the Application Kit printing mechanism to record the fonts used in the PostScript output. If you absolutely must set the font using a PostScript operator, you can record the font with the Application Kit using the class method useFont. See the description of that method for more information.


Getting 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. See the various method descriptions for specific information. You can also get a complete dictionary of font metrics using the afmDictionary method, or retrieve the original contents of the metrics file using afmFileContents.


Calculating Glyph Layout


The Cocoa extended text system handles many complex aspects of laying glyphs out. If you need to calculate layout for your own purposes, you can use a method defined by NSFont.


Overstruck glyph layout


Overstruck glyph layout is the most complex, as it requires detailed information about placement of many kinds of modifying marks. Generally, you have two characters:

Cocoa gives you a method for combining the two characters together, depending on whether the combination is a common one that the font has metrics for or whether the combination is an unusual one that you need to create on the fly.


Special Glyphs


NSFont defines two special glyphs. NullGlyph indicates no glyph at all, and is useful in some layout methods for calculating information that isn't relative to another glyph. For example, with positionOfGlyph:precededByGlyph:isNominal:, you can specify NullGlyph as the first glyph to get the nominal advancement of the preceding glyph.

The other special glyph is ControlGlyph, which the text system maps onto control functions such as linefeed and tab. This glyph has no graphic representation and has no inherent advancement of its own. Instead, the text system examines the control character underlying the glyph to determine what kind of special layout it needs to perform.




Constants


These constants describe how to encode the font's glyphs into an array of bytes. They're used by glyphPacking.


Constant Description
OneByteGlyphPacking Description forthcoming.
JapaneseEUCGlyphPacking Description forthcoming.
ASCIIWithDoubleByteEUCGlyphPacking Description forthcoming.
AsciiWithDoubleByteEUCGlyphPacking Description forthcoming.
TwoByteGlyphPacking Description forthcoming.
FourByteGlyphPacking Description forthcoming.



Method Types


Constructors
NSFont
Creating arbitrary fonts
fontWithNameAndSize
fontWithNameAndMatrix
Creating user fonts
userFontOfSize
userFixedPitchFontOfSize
Creating system fonts
boldSystemFontOfSize
controlContentFontOfSize
menuFontOfSize
messageFontOfSize
paletteFontOfSize
systemFontOfSize
titleBarFontOfSize
toolTipsFontOfSize
Getting preferred fonts
setPreferredFontNames
preferredFontNames
Using a font to draw
set
Adding fonts to print operations
useFont
Getting general font information
encodingScheme
isBaseFont
isFixedPitch
mostCompatibleStringEncoding
Getting information about glyphs
glyphIsEncoded
glyphPacking
glyphWithName
Getting metrics information
advancementForGlyph
afmDictionary
afmFileContents
ascender
boundingRectForFont
boundingRectForGlyph
capHeight
descender
italicAngle
maximumAdvancement
pointSize
underlinePosition
underlineThickness
widthOfString
xHeight
Getting font names
displayName
familyName
fontName
Laying out overstruck glyphs
positionOfGlyphForCharacterStruckOverRect
Setting user fonts
setUserFont
setUserFixedPitchFont
Getting corresponding device fonts
printerFont
screenFont


Constructors



NSFont

public NSFont()

Description forthcoming.


Static Methods



boldSystemFontOfSize

public static NSFont boldSystemFontOfSize(float fontSize)

Returns the font used for standard interface items that are rendered in boldface type, in fontSize. This is available for backwards compatibility only and calls titleBarFontOfSize. Use one of the specialized methods instead, such as userFontOfSize, userFixedPitchFontOfSize, titleBarFontOfSize, menuFontOfSize, messageFontOfSize, paletteFontOfSize, or toolTipsFontOfSize.

See Also: fontWithNameAndSize



controlContentFontOfSize

public static NSFont controlContentFontOfSize(float fontSize)

Returns the font used for the content of controls, in fontSize. For example, in a table, the user's input uses the control content font and the table's header uses another font.

See Also: fontWithNameAndSize



fontWithNameAndMatrix

public static Object fontWithNameAndMatrix( String typeface, NSArray fontMatrix)

Returns a font object for typeface and fontMatrix. typeface is a fully specified family-face name, such as Helvetica-BoldOblique or Times-Roman (not a name as shown in the Font Panel). fontMatrix is a standard 6-element transformation matrix as used in the PostScript language, specifically with the makefont operator. In most cases, you can simply use fontWithNameAndSize to create standard scaled fonts.

See Also: isFlipped (NSView)



fontWithNameAndSize

public static NSFont fontWithNameAndSize( String fontName, float fontSize)

Returns a font object for fontName and fontSize. fontName is a fully specified family-face name, such as Helvetica-BoldOblique or Times-Roman. fontSize is used to scale the font, and is equivalent to using a font matrix of [fontSize 0 0 fontSize 0 0] with fontWithNameAndMatrix . If you use a fontSize of 0.0, this method uses the default User Font size.

Fonts created with this method automatically flip themselves in flipped views. This method is the preferred means for creating fonts.



menuFontOfSize

public static NSFont menuFontOfSize(float fontSize)

Returns the font used for menu items in fontSize.

See Also: fontWithNameAndSize



messageFontOfSize

public static NSFont messageFontOfSize(float fontSize)

Returns the font used for standard interface items, such as button labels, menu items, and so on, in fontSize. This is equivalent to systemFontOfSize.

See Also: fontWithNameAndSize



paletteFontOfSize

public static NSFont paletteFontOfSize(float fontSize)

Returns the font used for palette window title bars.

See Also: fontWithNameAndSize, titleBarFontOfSize



preferredFontNames

public static NSArray preferredFontNames()

Returns the names of fonts that the Application Kit tries first when a character has no font specified, or when the font specified doesn't have a glyph for that character. If none of these fonts provides a glyph, the remaining fonts on the system are searched for a glyph.

See Also: setPreferredFontNames



setPreferredFontNames

public static void setPreferredFontNames(NSArray fontNames)

Sets the list of preferred font names to fontNames, and records them in the user defaults database for all applications. The Application Kit tries these fonts first when a character has no font specified, or when the font specified doesn't have a glyph for that character. If none of these fonts provides a glyph, the remaining fonts on the system are searched for a glyph.

This method is useful for optimizing glyph rendering for uncommon scripts, by guaranteeing that appropriate fonts are searched first. For example, suppose you have three hundred Latin alphabet fonts and one Cyrillic alphabet font. When you read a document in Russian, you want it to find the Cyrillic font quickly. Ordinarily, the Application Kit will search for the Cyrillic font among all three hundred and one fonts. But if it is in the list of preferred fonts, the Cyrillic font will be one of the first searched.

See Also: preferredFontNames



setUserFixedPitchFont

public static void setUserFixedPitchFont(NSFont aFont)

Sets the font used by default for documents and other text under the user's control, when that font should be fixed-pitch, to aFont, and records the font in the user defaults database for all applications.

See Also: setUserFont, userFixedPitchFontOfSize



setUserFont

public static void setUserFont(NSFont aFont)

Sets the font used by default for documents and other text under the user's control to aFont, and records the font in the user defaults database for all applications.

See Also: setUserFixedPitchFont, userFontOfSize



systemFontOfSize

public static NSFont systemFontOfSize(float fontSize)

Returns the font used for standard interface items, such as button labels, menu items, and so on, in fontSize. This is available for backwards compatibility only and calls messageFontOfSize. Use one of the specialized methods instead, such as userFontOfSize, userFixedPitchFontOfSize, titleBarFontOfSize, menuFontOfSize, messageFontOfSize, paletteFontOfSize, or toolTipsFontOfSize .

See Also: boldSystemFontOfSize, userFontOfSize, userFixedPitchFontOfSize, fontWithNameAndSize



titleBarFontOfSize

public static NSFont titleBarFontOfSize(float fontSize)

Returns the font used for window title bars, in fontSize. This is equivalent to boldSystemFontOfSize.

See Also: paletteFontOfSize



toolTipsFontOfSize

public static NSFont toolTipsFontOfSize(float fontSize)

Returns the font used for tool-tips labels, in fontSize.

See Also: fontWithNameAndSize



useFont

public static void useFont(String fontName)

Records fontName as one used in the current print operation.

The NSFont class object keeps track of the fonts used in an NSView by recording each one that receives a set message. When the view is called upon to generate conforming PostScript language output (such as during printing), the NSFont class provides the list of fonts required for the %%DocumentFonts comment, as required by Adobe's Document Structuring Conventions.

useFont augments this system by providing a way to register fonts that are included in the document but not set using NSFont's set method. For example, you might set a font by executing the setfont operator within a function created by the pswrap utility. In such a case, be sure to pair the use of the font with a useFont message to register the font for listing in the document comments.



userFixedPitchFontOfSize

public static NSFont userFixedPitchFontOfSize(float fontSize)

Returns the font used by default for documents and other text under the user's control (that is, text whose font the user can normally change), when that font should be fixed-pitch.

The system does not guarantee that all the glyphs in a fixed-pitch font are the same width. For example certain Japanese fonts are dual-pitch, and other fonts may have non-spacing marks which can affect the display of other glyphs.

See Also: userFontOfSize, fontWithNameAndSize, setUserFixedPitchFont



userFontOfSize

public static NSFont userFontOfSize(float fontSize)

Returns the font used by default for documents and other text under the user's control (that is, text whose font the user can normally change).

See Also: userFixedPitchFontOfSize, fontWithNameAndSize, setUserFont




Instance Methods



advancementForGlyph

public NSSize advancementForGlyph(int aGlyph)

Returns the nominal spacing for aGlyph-the distance the current point moves after showing the glyph-accounting for the receiving font's size. This spacing is given according to the glyph's movement direction, which is either strictly horizontal or strictly vertical.

See Also: boundingRectForGlyph, maximumAdvancement



afmDictionary

- (NSDictionary *)afmDictionary

Returns the receiving font's AFM information in dictionary form. It contains the following information under these keys, with all values as strings:

For any other items, use the AFM file contents, as returned by afmFileContents.



afmFileContents

public String afmFileContents()

Returns the receiving font's AFM file as a string object.

ascender

public float ascender()

Returns the top y coordinate of the receiving font's longest ascender.

See Also: descender, capHeight, xHeight



boundingRectForFont

public NSRect boundingRectForFont()

Returns the receiving font's bounding rectangle, scaled to the font's size. The bounding rectangle is the union of the bounding rectangles of every glyph in the font.

See Also: boundingRectForGlyph



boundingRectForGlyph

public NSRect boundingRectForGlyph(int aGlyph)

Returns the bounding rectangle for aGlyph, scaled to the receiving font's size.

Japanese fonts encoded with the scheme "EUC12-NJE-CFEncoding" do not have individual metrics or bounding boxes available for the glyphs above 127. For those glyphs, this method returns the bounding rectangle for the font, instead.

See Also: boundingRectForFont



capHeight

public float capHeight()

Returns the receiving font's cap height.

See Also: ascender, descender, xHeight



descender

public float descender()

Returns the bottom y coordinate of the receiving font's longest descender.

displayName

public String displayName()

Returns the name used to represent the receiving font in the user interface, typically localized for the user's language.

encodingScheme

public String encodingScheme()

Returns the name of the receiving font's encoding scheme, such as "AdobeStandardEncoding", "ISOLatin1Encoding", "FontSpecific", and so on.

familyName

public String familyName()

Returns the receiving font's family name; for example, "Times" or "Helvetica". This is the name that NSFontManager uses and may differ slightly from the AFM name.

See Also: fontName



fontName

public String fontName()

Returns the receiver's full font name, as used in PostScript language code; for example, "Times-Roman" or "Helvetica-Oblique".

See Also: - familyName



glyphIsEncoded

public boolean glyphIsEncoded(int aGlyph)

Returns true if the receiving font encodes aGlyph, false if it doesn't contain it.

glyphPacking

public int glyphPacking()

Returns the best way to encode the font's glyphs into an array of bytes. The return value is one of the following:

glyphWithName

public int glyphWithName(String glyphName)

Returns the encoded glyph named glyphName, or -1 if the receiving font contains no such glyph. Returns -1 if the glyph named glyphName isn't encoded.

Glyph names in fonts do not always accurately identify the glyph. If possible, look up the appropriate glyph on your own.



isBaseFont

public boolean isBaseFont()

Returns true if the receiver is a PostScript base font, false if it's a PostScript composite font composed of other base fonts.

isFixedPitch

public boolean isFixedPitch()

Returns true if all glyphs in the receiving font have the same advancement, false if any advancements differ.

Some Japanese fonts encoded with the scheme "EUC12-NJE-CFEncoding" return that they have the same advancement, but actually encode glyphs with one of two advancements. This is for historical compatibility. You may need to handle such fonts specially for some applications.

See Also: advancementForGlyph



italicAngle

public float italicAngle()

Returns the receiving font's italic angle, the amount that the font is slanted in degrees counterclockwise from the vertical, as read from its AFM file.

maximumAdvancement

public NSSize maximumAdvancement()

Returns the greatest advancement of any of the receiving font's glyphs. This is always either strictly horizontal or strictly vertical.

See Also: advancementForGlyph



mostCompatibleStringEncoding

public int mostCompatibleStringEncoding()

Returns the string encoding that works best with the receiving font, where there are the fewest possible unmatched characters in the string encoding and glyphs in the font. You can use NSStringReferences's dataUsingEncoding method to convert the string to this encoding.

If this method returns NSStringReference.ASCIIStringEncoding, it could not determine the correct encoding and assumed that the font can render only ASCII characters.

This method works heuristically using well-known font encodings, so for nonstandard encodings it may not in fact return the optimal string encoding.

See Also: widthOfString



pointSize

public float pointSize()

Returns the receiving font's point size, or the effective vertical point size for a font with a nonstandard matrix.

positionOfGlyphForCharacterStruckOverRect

public NSPoint positionOfGlyphForCharacterStruckOverRect( int aGlyph, char aChar, NSRect aRect)

Calculates and returns a suitable location for aGlyph to be drawn as a diacritic or non-spacing mark relative to aRect, assuming that aGlyph represents aChar. Returns NSPoint.ZeroPoint if the location can't be calculated. The nature of aChar as one appearing above or below its base character determines the location returned. For example, in the first figure below, the gray tilde and box represent aGlyph and aRect, and the black dot is the point returned (defined relative to the origin of the aRect).
[image: Art/NSFont-GlyphOverRect.gif]

To place multiple glyphs with respect to a rectangle, work from the innermost glyphs to the outermost. As you calculate the position of each glyph, enlarge the rectangle to include the bounding rectangle of the glyph in preparation for the next glyph. The second figure shows a tilde, acute accent, and cedilla all placed in their appropriate positions with respect to a rectangle, with the acute accent placed relative to the expanded bounding box of the base rectangle and the tilde.



printerFont

public NSFont printerFont()

When sent to a font object representing a scalable PostScript font, returns this. When sent to a font object representing a bitmapped screen font, returns its corresponding scalable PostScript font.

See Also: screenFont



screenFont

public NSFont screenFont()

When sent to a font object representing a scalable PostScript font, returns a bitmapped screen font matching the receiver in typeface and matrix (or size), or null if such a font can't be found. When sent to a font object representing a bitmapped screen font, returns null.

Screen fonts are for direct use with the Window Server only. Never use them with Application Kit objects, such as in setFont methods. Internally, the Application Kit automatically uses the corresponding screen font for a font object as long as the view is not rotated or scaled.

See Also: printerFont



set

public void set()

Establishes the receiving font as the current font for PostScript show and other text-drawing operators. During a print operation, also records the font as used in the PostScript code emitted.

See Also: useFont



underlinePosition

public float underlinePosition()

Returns the baseline offset that should be used when drawing underlines with the receiving font, as determined by the font's AFM file. This value is usually negative, which must be considered when drawing in a flipped coordinate system.

See Also: underlineThickness



underlineThickness

public float underlineThickness()

Returns the thickness that should be used when drawing underlines with the receiving font, as determined by the font's AFM file.

See Also: underlinePosition



widthOfString

public float widthOfString(String aString)

Returns the x axis offset of the current point when aString is drawn with a PostScript show operator in the receiving font. This method performs lossy conversion of aString to the most compatible encoding for the receiving font.

Use this method only when you're sure all of aString can be rendered with the receiving font.

This method is for backwards compatibility only.

See Also: mostCompatibleStringEncoding



xHeight

public float xHeight()

Returns the x-height of the receiving font.

See Also: ascender, descender




Table of Contents