![[image: graphic1.gif]](NSFont0.gif)
Inherits from: NSObject
Conforms to: NSCoding
NSCopying
NSObject (NSObject)
Declared in: AppKit/NSFont.h
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 the alloc and init methods. Instead, you use either fontWithName:matrix: or fontWithName:size: 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:.
In most cases you draw text using an NSTextView object. You can also draw an NSString directly in an NSView using the methods drawAtPoint:withAttributes: and drawInRect:withAttributes:, which the Application Kit adds to NSString. These methods take an NSDictionary of attributes, as used by the NSAttributedString class, and apply them when drawing the string.
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.
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.
<<JPM: I marked this section ObjC-only since most of the methods it references (positionOf...) are not available in Java.>>
The OPENSTEP extended text system handles many complex aspects of laying glyphs out. If you need to calculate layout for your own purposes, you can use several methods defined by NSFont. There are three basic kinds of glyph layout:
Sequential glyph layout is supported by the method positionOfGlyph:precededByGlyph:isNominal:. This method calculates the position of a glyph relative to glyph preceding it, using the glyph's width and kerning information if they're available. This is the most straightforward kind of 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:
OPENSTEP gives you a few methods 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. Try these methods in the following order, to get the best result:
metricsExist argument.
(Use the method boundingRectForGlyph: to
get the bounding rect for the base glyph.) Note that NSFont always
sets metricsExist to NO and
that this method is useful only if you're using a subclass of
NSFont that overrides this method.If you need to place several non-spacing marks with respect to a base glyph, use the method positionsForCompositeSequence:numberOfGlyphs:pointArray:. This method accepts a C array containing the base glyph followed by all of its non-spacing marks, and calculates the positions for as many as of the marks as it can. To place the marks that this method can't handle, use the methods described above.
Stacked glyph layout is supported by the method positionOfGlyph:withRelation:toBaseGlyph:totalAdvancement:metricsExist:. Stacked glyphs often have special compressed forms, which standard font metrics don't account for. NSFont's implementation of this method simply abuts the bounding boxes of the two glyphs for approximate layout of the individual glyphs. Subclasses of NSFont can override this method to access any extra metrics information for more sophisticated layout of stacked glyphs.
NSFont defines two special glyphs. NSNullGlyph 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 NSNullGlyph as the
first glyph to get the nominal advancement of the preceding glyph.
The other special glyph is NSControlGlyph,
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.
These constants describe how to encode the font's glyphs into an array of bytes. They're used by glyphPacking.
| Constant | Description |
NSOneByteGlyphPacking |
<<Description Forthcoming>> |
NSJapaneseEUCGlyphPacking |
<<Description Forthcoming>> |
NSAsciiWithDoubleByteEUCGlyphPacking |
<<Description Forthcoming>> |
NSAsciiWithDoubleByteEUCGlyphPacking |
<<Description Forthcoming>> |
NSTwoByteGlyphPacking |
<<Description Forthcoming>> |
NSFourByteGlyphPacking |
<<Description Forthcoming>> |
- NSCoding
- - encodeWithCoder:
- - initWithCoder:
- NSCopying
- - copyWithZone:
- Creating arbitrary fonts
- + fontWithName:size:
- + fontWithName:matrix:
- 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
- - matrix
- - maximumAdvancement
- - pointSize
- - underlinePosition
- - underlineThickness
- - widthOfString:
- - widths
- - xHeight
- Getting font names
- - displayName
- - familyName
- - fontName
- Laying out sequential glyphs
- - positionOfGlyph:precededByGlyph:isNominal:
- - positionsForCompositeSequence:numberOfGlyphs:pointArray:
- Laying out overstruck glyphs
- - positionOfGlyph:forCharacter:struckOverRect:
- - positionOfGlyph:struckOverGlyph:metricsExist:
- - positionOfGlyph:struckOverRect:metricsExist:
- Laying out stacked glyphs
- - positionOfGlyph:withRelation:toBaseGlyph:totalAdvancement:metricsExist:
- Setting user fonts
- + setUserFont:
- + setUserFixedPitchFont:
- Getting corresponding device fonts
- - printerFont
- - screenFont
+ (NSFont *)boldSystemFontOfSize:(float)fontSize
See Also: + fontWithName:size:
+ (NSFont *)controlContentFontOfSize:(float)fontSize
See Also: + fontWithName:size:
+ (NSFont *)fontWithName:(NSString
*)typeface matrix:(const
float *)fontMatrix
makefont operator.
In most cases, you can simply use fontWithName:size: to create standard
scaled fonts.You can use the defined value NSFontIdentityMatrix for
[1 0 0 1 0 0]. Fonts created with a matrix other than NSFontIdentityMatrix don't
automatically flip themselves in flipped views. <<JPM: There's
no NSFontIdentityMatrix in Java. What do you do in Java?>>
See Also: - isFlipped (NSView)
+ (NSFont *)fontWithName:(NSString
*)fontName size:(float)fontSize
Fonts created with this method automatically flip themselves in flipped views. This method is the preferred means for creating fonts.
+ (NSFont *)menuFontOfSize:(float)fontSize
See Also: + fontWithName:size:
+ (NSFont *)messageFontOfSize:(float)fontSize
See Also: + fontWithName:size:
+ (NSFont *)paletteFontOfSize:(float)fontSize
See Also: + fontWithName:size:, + titleBarFontOfSize:
+ (NSArray *)preferredFontNames
See Also: + setPreferredFontNames:
+ (void)setPreferredFontNames:(NSArray
*)fontNames
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
+ (void)setUserFixedPitchFont:(NSFont
*)aFont
See Also: + setUserFont:, + userFixedPitchFontOfSize:
+ (void)setUserFont:(NSFont
*)aFont
See Also: + setUserFixedPitchFont:, + userFontOfSize:
+ (NSFont *)systemFontOfSize:(float)fontSize
See Also: + boldSystemFontOfSize:, + userFontOfSize:, + userFixedPitchFontOfSize:, + fontWithName:size:
+ (NSFont *)titleBarFontOfSize:(float)fontSize
See Also: + paletteFontOfSize:
+ (NSFont *)toolTipsFontOfSize:(float)fontSize
See Also: + fontWithName:size:
+ (void)useFont:(NSString
*)fontName
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.
+ (NSFont *)userFixedPitchFontOfSize:(float)fontSize
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:, + fontWithName:size:, + setUserFixedPitchFont:
+ (NSFont *)userFontOfSize:(float)fontSize
See Also: + userFixedPitchFontOfSize:, + fontWithName:size:, + setUserFont:
- (NSSize)advancementForGlyph:(NSGlyph)aGlyph
See Also: - boundingRectForGlyph:, - maximumAdvancement
public NSDictionary afmDictionary()
For any other items, use the AFM file contents, as returned by afmFileContents.
- (NSString *)afmFileContents
- (float)ascender
See Also: - descender, - capHeight, - xHeight
- (NSRect)boundingRectForFont
See Also: - boundingRectForGlyph:
- (NSRect)boundingRectForGlyph:(NSGlyph)aGlyph
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
- (float)capHeight
See Also: - ascender, - descender, - xHeight
- (float)descender
- (NSString *)displayName
- (NSString *)encodingScheme
- (NSString *)familyName
See Also: - fontName
- (NSString *)fontName
See Also: - familyName
- (BOOL)glyphIsEncoded:(NSGlyph)aGlyph
YES if
the receiving font encodes aGlyph, NO if
it doesn't contain it.- (NSMultibyteGlyphPacking) glyphPacking
NSOneByteGlyphPackingNSJapaneseEUCGlyphPackingNSAsciiWithDoubleByteEUCGlyphPackingNSTwoByteGlyphPackingNSFourByteGlyphPacking- (NSGlyph)glyphWithName:(NSString
*)glyphName
Glyph names in fonts do not always accurately identify the glyph. If possible, look up the appropriate glyph on your own.
- (BOOL)isBaseFont
YES if
the receiver is a PostScript base font, NO if
it's a PostScript composite font composed of other base fonts.- (BOOL)isFixedPitch
YES if
all glyphs in the receiving font have the same advancement, NO if
any advancements differ.On the Mach platform, 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:
- (float)italicAngle
- (const float *)matrix
makefont operator. In
most cases, with a font of fontSize, this matrix
is [fontSize 0 0 fontSize 0 0].See Also: + fontWithName:matrix:
- (NSSize)maximumAdvancement
See Also: - advancementForGlyph:
- (NSStringEncoding)mostCompatibleStringEncoding
If this method returns NSASCIIStringEncoding,
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:
- (float)pointSize
- (NSPoint)positionOfGlyph:(NSGlyph)aGlyph forCharacter:(unichar)aChar struckOverRect:(NSRect)aRect
NSZeroPoint 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).
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.
This
method is the last fallback mechanism for performing minimally legible typography
when metrics aren't available. Use it when positionOfGlyph:struckOverGlyph:metricsExist: indicates
that metrics don't exist for the base glyph specified, or when
you are combining glyphs from different fonts (for example, the
base glyph is in a different font than the accent). It can account
for the layout and placement of most Latin, Greek, and Cyrillic non-spacing
marks. You should draw the glyph at the returned location, even
if it's NSPoint.ZeroRect.
- (NSPoint)positionOfGlyph:(NSGlyph)aGlyph precededByGlyph:(NSGlyph)prevGlyph isNominal:(BOOL
*)flag
nil, it's filled with NO if
kerning tables are available and were used in the calculation; it
is filled with YES if the default
spacing is used.Returns NSZeroPoint if
either aGlyph or prevGlyph is NSControlGlyph or
is invalid. Returns the nominal advancement of prevGlyph if aGlyph is NSNullGlyph.
This method is useful for sequential glyph placement when glyphs aren't drawn with a single PostScript operation.
- (NSPoint)positionOfGlyph:(NSGlyph)aGlyph struckOverGlyph:(NSGlyph)baseGlyph metricsExist:(BOOL
*)flag
nil it's filled with YES if
font metrics are available, NO if
they're not. If flag is returned as NO, the
result isn't valid and shouldn't be used. In that case, use positionOfGlyph:struckOverRect:metricsExist: or positionOfGlyph:forCharacter:struckOverRect: to
calculate a reasonable offset.See Also: - positionsForCompositeSequence:numberOfGlyphs:pointArray:, - positionOfGlyph:struckOverRect:metricsExist:
- (NSPoint)positionOfGlyph:(NSGlyph)aGlyph struckOverRect:(NSRect)aRect metricsExist:(BOOL
*)flag
NSZeroRect if
the location can't be determined. If flag is non-nil it's
filled with YES if font metrics are
available, NO if they're not. If flag is
returned as NO, the result isn't
valid and shouldn't be used. In that case, use positionOfGlyph:forCharacter:struckOverRect: to
calculate a reasonable offset.Because current Postscript font
metrics don't include support for generic placement relative to
rectangles, NSFont's implementation of this method always returns NSZeroPoint and
returns flag as NO.
- (NSPoint)positionOfGlyph:(NSGlyph)aGlyph withRelation:(NSGlyphRelation)relation toBaseGlyph:(NSGlyph)baseGlyph totalAdvancement:(NSSizePointer)offset metricsExist:(BOOL
*)flag
NSGlyphBelow or NSGlyphAbove. The
point returned should be used relative to whatever location is used
for baseGlyph. This method is useful
for calculating the layout of stacked glyphs, found in some non-Western
scripts.If offset is non-nil,
this method sets it to the larger of the two glyphs' advancements,
allowing for reasonable layout of following glyphs.
If flag is
non-nil, this method sets it to whether
font metrics are available: YES if
they are, NO if they're not. If
metrics aren't available, the location is calculated as a simple
stacking with no gap between baseGlyph and aGlyph. Current
Postscript fonts do not contain appropriate font metrics, so this
method always sets flag to NO. If
you subclass NSFont to handle fonts that do contain metrics, override
this method.
This method supports only horizontally laid-out base glyphs.
- (int)positionsForCompositeSequence:(NSGlyph
*)glyphs numberOfGlyphs:(int)numGlyphs pointArray:(NSPointArray)points
If the number of points calculated is less than numGlyphs, the number of glyphs provided, you can use positionOfGlyph:struckOverRect:metricsExist: to determine the positions for the remaining glyphs. When using that method, calculate the base rectangle for each glyph from the bounding rectangles and positions of all preceding glyphs.
- (NSFont *)printerFont
See Also: - screenFont
- (NSFont *)screenFont
nil if
such a font can't be found. When sent to a font object representing
a bitmapped screen font, returns nil. 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
- (void)set
show and
other text-drawing operators. During a print operation,
also records the font as used in the PostScript code emitted.See Also: + useFont:
- (float)underlinePosition
See Also: - underlineThickness
- (float)underlineThickness
See Also: - underlinePosition
- (float)widthOfString:(NSString
*)aString
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. In new code, use the Application Kit's string-drawing methods, as described under NSString Additions.
See Also: - mostCompatibleStringEncoding
- (float *)widths
This method is for backwards compatibility only. In new code, use advancementForGlyph: instead.
- (float)xHeight
See Also: - ascender, - descender