NSFont

Authors

Ovidiu Predescu (ovidiu@net-community.com)

Date: Generated at 2025-12-03

The font class

Contents -

NSFont
Software documentation for the NSFont(GNUstep) category

NSFont

The NSFont class allows control of the fonts used for displaying text anywhere on the screen. The primary methods for getting a particular font are +fontWithName:matrix: and +fontWithName:size: which take the name and size of a particular font and return the NSFont object associated with that font. In addition there are several convenience mathods which make it easier to get certain types of fonts.

In particular, there are several methods to get the standard fonts used by the Application to display text for a partiuclar purpose. See the class methods listed below for more information. These default fonts can be set using the user defaults system. The default font names available are:

NSBoldFont Helvetica-Bold (System bold font)
NSControlContentFont System font
NSFont Helvetica (System Font)
NSLabelFont System font
NSMenuFont System font
NSMenuBarFont System font
NSMessageFont System font
NSPaletteFont System bold font
NSTitleBarFont System bold font
NSToolTipsFont System font
NSUserFixedPitchFont Courier
NSUserFont System font

The default sizes are:

NSBoldFontSize (none)
NSControlContentFontSize (none)
NSFontSize 12 (System Font Size)
NSLabelFontSize (none)
NSMenuFontSize (none)
NSMiniFontSize 8
NSMessageFontSize (none)
NSPaletteFontSize (none)
NSSmallFontSize 10
NSTitleBarFontSize (none)
NSToolTipsFontSize (none)
NSUserFixedPitchFontSize (none)
NSUserFontSize (none)

Font sizes list with (none) default to NSFontSize.

NSFont : NSObject

Declared in:

AppKit/NSFont.h

Conforms to:

NSCoding

NSCopying

Availability: OpenStep

NSFont encapsulates all the information needed to render text with a specific typeface, size, and style. It provides comprehensive font creation, measurement, and glyph manipulation capabilities for text layout and rendering systems. The font system supports both screen and printer fonts, with automatic conversion between them. Fonts can be created by name and size, or through more advanced methods using font descriptors and transformation matrices. NSFont provides extensive metrics information including ascender, descender, line height, character advancement, and glyph bounding rectangles. It also supports advanced typography features like composite glyph positioning and multi-byte character encoding schemes. The class integrates with the broader text system through glyph manipulation methods that support complex text layout, international text rendering, and precise typographic control needed for high-quality document formatting.

NSFont declares 9 Instance Variables

Method summary

boldSystemFontOfSize:

+ (NSFont*) boldSystemFontOfSize: (CGFloat)fontSize;

Availability: OpenStep

Returns the bold system font at the specified size. The bold system font is used for emphasis in user interface elements and provides consistent bold text appearance across the system. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default system size. Returns a bold variant of the system font at the specified size.

Returns the default bold font for use in menus and heading in standard gui components. If fontSize is <= 0, the default size is used.

controlContentFontOfSize:

+ (NSFont*) controlContentFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used for control content (button titles, text field content). The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard control content font at the specified size.

fontWithDescriptor: size:

+ (NSFont*) fontWithDescriptor: (NSFontDescriptor*)descriptor size: (CGFloat)size;

Availability: MacOS-X 10.4.0

Creates a font using a font descriptor and size. Font descriptors provide a more flexible way to specify font characteristics including family, weight, traits, and other attributes. The descriptor parameter specifies the desired font characteristics. The size parameter sets the font size in points. Returns a font matching the descriptor at the specified size.

fontWithDescriptor: size: textTransform:

+ (NSFont*) fontWithDescriptor: (NSFontDescriptor*)descriptor size: (CGFloat)size textTransform: (NSAffineTransform*)transform;

Availability: MacOS-X 10.4.0

Creates a font using a font descriptor, size, and transformation matrix. This method provides the most comprehensive font creation capabilities, combining descriptor-based selection with size and transformation control. @param descriptor The font descriptor specifying the desired font characteristics. @param size The font size in points. @param transform The transformation to apply to the font. @return A font matching the descriptor at the specified size with transformation applied.

fontWithDescriptor: textTransform:

+ (NSFont*) fontWithDescriptor: (NSFontDescriptor*)descriptor textTransform: (NSAffineTransform*)transform;

Availability: MacOS-X 10.4.0

Creates a font using a font descriptor and transformation matrix. This method combines descriptor-based font selection with custom transformations. The descriptor parameter specifies the desired font characteristics. The transform parameter specifies the transformation to apply to the font. Returns a font matching the descriptor with the specified transformation applied.

fontWithName: matrix:

+ (NSFont*) fontWithName: (NSString*)aFontName matrix: (const CGFloat*)fontMatrix;

Availability: OpenStep

Creates a font with the specified PostScript name and transformation matrix. This method provides the most control over font creation, allowing custom transformation matrices for scaling, rotation, and skewing effects. The aFontName parameter should contain the PostScript name of the font (e.g., "Helvetica-Bold"). The fontMatrix parameter should be a 6-element transformation matrix [a b c d tx ty] for font transformation. Returns a font object with the specified name and transformation, or nil if the font cannot be created.

Returns an autoreleased font with name aFontName and matrix fontMatrix.

The fontMatrix is a standard size element matrix as used in PostScript to describe the scaling of the font, typically it just includes the font size as [fontSize 0 0 fontSize 0 0]. You can use the constant NSFontIdentityMatrix in place of [1 0 0 1 0 0]. If NSFontIdentityMatrix, then the font will automatically flip itself when set in a flipped view.

fontWithName: size:

+ (NSFont*) fontWithName: (NSString*)aFontName size: (CGFloat)fontSize;

Availability: OpenStep

Creates a font with the specified PostScript name and size. This is the most commonly used font creation method for standard text rendering. The aFontName parameter should contain the PostScript name of the font (e.g., "Times-Roman", "Helvetica"). The fontSize parameter specifies the desired font size in points. Returns a font object with the specified name and size, or nil if the font cannot be created.

Returns an autoreleased font with name aFontName and size fontSize.

Fonts created using this method will automatically flip themselves when set in a flipped view.

labelFontOfSize:

+ (NSFont*) labelFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used for labels and non-editable text. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard label font at the specified size.

labelFontSize

+ (CGFloat) labelFontSize;

Availability: MacOS-X 10.0.0

Returns the standard font size for labels. Returns the standard label font size in points.

menuBarFontOfSize:

+ (NSFont*) menuBarFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used in the menu bar. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard menu bar font at the specified size.

menuFontOfSize:

+ (NSFont*) menuFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used in menus. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard menu font at the specified size.

messageFontOfSize:

+ (NSFont*) messageFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used for message text in alerts and dialogs. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard message font at the specified size.

paletteFontOfSize:

+ (NSFont*) paletteFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used in palette windows and tool palettes. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard palette font at the specified size.

preferredFontNames

+ (NSArray*) preferredFontNames;

Availability: OpenStep

Returns the list of preferred font names. The preferred fonts list determines the fallback order when a requested font is not available on the system. Returns an array of NSString objects containing preferred font names.

Returns an array of the names of preferred fonts.

setPreferredFontNames:

+ (void) setPreferredFontNames: (NSArray*)fontNames;

Availability: OpenStep

Sets the list of preferred font names. This establishes the fallback order for font selection when requested fonts are not available. The fontNames parameter should contain an array of NSString objects with preferred font names.

Sets an array of the names of preferred fonts to fontsNames/

setUserFixedPitchFont:

+ (void) setUserFixedPitchFont: (NSFont*)aFont;

Availability: OpenStep

Sets the user's preferred fixed-pitch font. This establishes the default fixed-pitch font that will be returned by userFixedPitchFontOfSize: for subsequent requests. @param aFont The font to set as the user's preferred fixed-pitch font.

setUserFont:

+ (void) setUserFont: (NSFont*)aFont;

Availability: OpenStep

Sets the user's preferred proportional font. This establishes the default proportional font that will be returned by userFontOfSize: for subsequent requests. @param aFont The font to set as the user's preferred proportional font.

smallSystemFontSize

+ (CGFloat) smallSystemFontSize;

Availability: MacOS-X 10.0.0

Returns the standard small system font size. Returns the standard small system font size in points.

systemFontOfSize:

+ (NSFont*) systemFontOfSize: (CGFloat)fontSize;

Availability: OpenStep

Returns the standard system font at the specified size. The system font is the default font used for user interface text throughout the system and provides optimal readability for interface elements. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default system size. Returns the system font at the specified size.

Returns the default font for use in menus and heading in standard gui components. If fontSize is <= 0, the default size is used.

See Also: +boldSystemFontOfSize: userFontOfSize: userFixedPitchFontOfSize: +fontWithName:size:

systemFontSize

+ (CGFloat) systemFontSize;

Availability: MacOS-X 10.0.0

Returns the standard system font size. Returns the standard system font size in points.

systemFontSizeForControlSize:

+ (CGFloat) systemFontSizeForControlSize: (NSControlSize)controlSize;

Availability: MacOS-X 10.0.0

Returns the appropriate system font size for the given control size. This method provides the correct font size for different control sizes (regular, small, mini) to maintain visual consistency. The controlSize parameter specifies the control size (NSRegularControlSize, NSSmallControlSize, NSMiniControlSize). Returns the appropriate font size for the specified control size.

titleBarFontOfSize:

+ (NSFont*) titleBarFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used in window title bars. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard title bar font at the specified size.

toolTipsFontOfSize:

+ (NSFont*) toolTipsFontOfSize: (CGFloat)fontSize;

Availability: MacOS-X 10.0.0

Returns the font used for tooltip text. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the standard tooltip font at the specified size.

useFont:

+ (void) useFont: (NSString*)aFontName;

Availability: OpenStep

Sets the font for subsequent text drawing operations by name. This is a legacy method that establishes a font for text operations by PostScript name. @param aFontName The PostScript name of the font to use for text operations.

userFixedPitchFontOfSize:

+ (NSFont*) userFixedPitchFontOfSize: (CGFloat)fontSize;

Availability: OpenStep

Returns the user's preferred fixed-pitch font at the specified size. Fixed-pitch fonts are essential for code editing, terminal applications, and any context where character alignment is important. The fontSize parameter specifies the desired font size in points. Use 0.0 for the default size. Returns the user's preferred fixed-pitch font at the specified size.

Returns the default fixed pitch font for use in locations other than standard gui components. If fontSize is <= 0, the default size is used.

userFontOfSize:

- (CGFloat) xHeight;

NSFont(GNUstep)

Declared in:

AppKit/NSFont.h

Availability: MacOS-X 10.0.0

Description forthcoming.

Method summary

fontInfo

- (GSFontInfo*) fontInfo;

Availability: MacOS-X 10.0.0

Description forthcoming.

fontRef

- (void*) fontRef;

Availability: MacOS-X 10.0.0

Description forthcoming.