Inherits From:
NSObject
Conforms To:
NSCoding
NSCopying
NSObject (NSObject)
Declared In:
AppKit/NSFont.h
set
method.
You don't create Font objects using the alloc
and init
methods. Instead, you use one of the fontWithName:...
methods 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:
.
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.
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
.
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.
positionOfGlyph:struckOverGlyph:metricsExist:
and check the value returned in the metricsExist argument.
positionOfGlyph:struckOverRect:metricsExist:
and check the value returned in the 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.
positionOfGlyph:forCharacter:struckOverRect:
. (Use the method boundingRectForGlyph:
to get the bounding rect for the base glyph.) This method handles all the common non-spacing marks, such as an acute accent, tilde, or cedilla, for Latin script.positionOfGlyph:forCharacter:struckOverRect:
. (Use the method boundingRectForGlyph:
to get the bounding rect for the base glyph.)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.
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.
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 characters 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.
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 insteads, such as userFontOfSize:
, userFixedPitchFontOfSize:
, titleBarFontOfSize:
, menuFontOfSize:
, messageFontOfSize:
, paletteFontOfSize:
, or toolTipsFontOfSize:
.
See also:
+ fontWithName:size:
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:
+ fontWithName:size:
fontWithName:
(NSString *)typeface matrix:
(const float *)fontMatrix
Returns a font object for typeface and fontMatrix. A 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 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.
See also:
- isFlipped
(NSView)
fontWithName:
(NSString *)fontName size:
(float)fontSize
Returns a font object for fontName and fontSize. A typeface 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 fontWithName:matrix:
. If you use a fontSize of 0.0, this method uses the default !!!APPLICATION font size that the user specified in the !!!FONT PREFERENCES.
Fonts created with this method automatically flip themselves in flipped views. This method is the preferred means for creating fonts.
menuFontOfSize:
(float)fontSize
Returns the font used for menu items in fontSize.
See also:
+ fontWithName:size:
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:
+ fontWithName:size:
paletteFontOfSize:
(float)fontSize
Returns the font used for palette window title bars.
See also:
+ fontWithName:size:
, + titleBarFontOfSize:
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:
(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 Cyrillac alphabet font. When you read a document in Russian, you want it to find the Cyrillac font quickly. Ordinarily, the Application Kit will search for the Cyrillac font among all three hunded and one fonts. But if it is in the list of preferred fonts, the Cyrillac font will be one of the one of the first searched.
See also:
+ preferredFontNames
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:
(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:
(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 insteads, such as userFontOfSize:
, userFixedPitchFontOfSize:
, titleBarFontOfSize:
, menuFontOfSize:
, messageFontOfSize:
, paletteFontOfSize:
, or toolTipsFontOfSize:
.
See also:
+ boldSystemFontOfSize:
, + userFontOfSize:
, + userFixedPitchFontOfSize:
,
+ fontWithName:size:
titleBarFontOfSize:
(float)fontSize
Returns the font used for window title bars, in fontSize. This is equivalent to boldSystemFontOfSize:
.
See also:
+ paletteFontOfSize:
toolTipsFontOfSize:
(float)fontSize
Returns the font used for tool-tips labels, in fontSize.
See also:
+ fontWithName:size:
useFont:
(NSString *)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:
(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.
+ userFontOfSize:
, + fontWithName:size:
, + setUserFixedPitchFont:
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:
, + fontWithName:size:
, + setUserFont:
advancementForGlyph:
(NSGlyph)aGlyph
Returns the nominal spacing for aGlyph-the distance that 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
Returns the receiving font's AFM information in dictionary form. It contains the following information under these keys, with all values as strings:
afmFileContents
.
afmFileContents
Returns the receiving font's AFM file as a string object.
ascender
Returns the top y coordinate of the receiving font's longest ascender.
See also:
- descender
, - capHeight
, - xHeight
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:
(NSGlyph)aGlyph
Returns the bounding rectangle for aGlyph, scaled to the receiving font's size.
- boundingRectForFont
capHeight
Returns the receiving font's cap height.
See also:
- ascender
, - descender
, - xHeight
descender
Returns the bottom y coordinate of the receiving font's longest descender.
displayName
Returns the name used to represent the receiving font in the user interface, typically localized for the user's language.
encodingScheme
Returns the name of the receiving font's encoding scheme, such as "AdobeStandardEncoding", "ISOLatin1Encoding", "FontSpecific", and so on.
familyName
Returns the receiving font's family name; for example, "Times" or "Helvetica".
See also:
- fontName
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:
(NSGlyph)aGlyph
Returns YES if the receiving font encodes aGlyph, NO if it doesn't contain it.
glyphWithName:
(NSString *)glyphName
Returns the encoded glyph named glyphName, or -1 if the receiving font contains no such glyph. Also returns -1 if the glyph named glyphName isn't encoded.
isBaseFont
Returns YES if the receiver is a PostScript base font, NO if it's a PostScript composite font composed of other base fonts.
isFixedPitch
Returns YES if all glyphs in the receiving font have the same advancement, NO if any advancements differ.
- advancementForGlyph:
italicAngle
Returns the receiving font's italic angle, the amont that the font is slanted in degress counterclockwise from the verticle, as read from its AFM file.
matrix
Returns the receiver's font matrix, a standard 6-element transformation matrix as used in the PostScript language, specifically with the makefont
operator. In most cases, with a font of fontSize, this matrix is [fontSize 0 0 fontSize 0 0].
See also:
+ fontWithName:matrix:
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
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 NSString's dataUsingEncoding:
or dataUsingEncoding:allowLossyConversion:
method to convert the string to this encoding.
- widthOfString:
pointSize
Returns the receiving font's point size, or the effective vertical point size for a font with a nonstandard matrix.
positionOfGlyph:
(NSGlyph)aGlyphforCharacter:
(unichar)aCharstruckOverRect:
(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 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 performining 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 NSZeroRect.
positionOfGlyph:
(NSGlyph)aGlyphprecededByGlyph:
(NSGlyph)prevGlyphisNominal:
(BOOL *)flag
Calculates and returns the location of aGlyph relative to prevGlyph, assuming that prevGlyph precedes it in the layout (not necessarily in the character stream). The point returned should be used relative to whatever location is used for prevGlyph. If flag is non-NULL, 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.
positionOfGlyph:
(NSGlyph)aGlyphstruckOverGlyph:
(NSGlyph)baseGlyphmetricsExist:
(BOOL *)flag
Calculates and returns a suitable location for aGlyph to be drawn as a diacritic or non-spacing mark relative to baseGlyph. The point returned should be used relative to whatever location is used for baseGlyph. If flag is non-NULL 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:
positionOfGlyph:
(NSGlyph)aGlyphstruckOverRect:
(NSRect)aRectmetricsExist:
(BOOL *)flag
Overridden by subclasses to calculate and return a suitable location for aGlyph to be drawn as a diacritic or non-spacing mark relative to aRect, provided metrics exist. Returns NSZeroRect if the location can't be determined. If flag is non-NULL 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.
positionOfGlyph:
(NSGlyph)aGlyphwithRelation:
(NSGlyphRelation)relationtoBaseGlyph:
(NSGlyph)baseGlyphtotalAdvancement:
(NSSize *)offsetmetricsExist:
(BOOL *)flag
Calculates and returns a suitable location for aGlyph to be drawn relative to baseGlyph, where relation is 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-NULL, this method sets it to the larger of the two glyphs' advancements, allowing for reasonable layout of following glyphs.
If flag is non-NULL, 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 font metrics, so this method always sets flag to NO. If you subclass NSFont to handle fonts that do contain metrics, override this method.
positionsForCompositeSequence:
(NSGlyph *)glyphsnumberOfGlyphs:
(int)numGlyphspointArray:
(NSPoint *)points
Calculates and fills points with the locations for glyphs, assuming that the first glyph is a base character and those following are non-spacing marks. These points should all be interpreted as relative to the location of the first glyph in glyphs. The storage block that points points to should be large enough for at least numgyphs points. Returns the number of points that could be calculated.
If the number of points calculated is less than numGlyphs, the number of glyphs provided, you can use positionOfGlyph:structOverRect: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.
printerFont
When sent to a font object representing a scalable PostScript font, returns self
. When sent to a font object representing a bitmapped screen font, returns its corresponding scalable PostScript font.
See also:
- screenFont
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 nil
if such a font can't be found. When sent to a font object representing a bitmapped screen font, returns nil
.
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
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
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
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:
(NSString *)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. In new code, use the Application Kit's string-drawing methods, as described under NSString Additions.
See also:
- mostCompatibleStringEncoding
widths
Returns a C array of 256 float
s, giving the unscaled width of each glyph in the font. This data is useful only for simple fonts without non-spacing marks, and doesn't account for Unicode-related issues at all.
This method is for backwards compatibility only. In new code, use advancementForGlyph:
instead.
xHeight
Returns the x-height of the receiving font.
See also:
- ascender
, - descender