NSString Application Kit Additions Reference

Inherits from
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSStringDrawing.h
Companion guides

Overview

The Application Kit adds three methods to the NSString class to support drawing string objects directly in an NSView instance: drawAtPoint:withAttributes:, drawInRect:withAttributes:, and sizeWithAttributes:.

The Application Kit adds similar methods to the NSAttributedString class, described in NSAttributedString AppKit Additions Reference. The two drawing methods draw a string object with a single set of attributes that apply to the entire string. To draw a string with multiple attributes, such as multiple text fonts, you must use an attributed string.

Tasks

Drawing String Objects

Getting the Bounding Rect of Rendered Strings

Instance Methods

boundingRectWithSize:options:attributes:

Calculates and returns the bounding rect for the receiver drawn using the given options and display characteristics, within the specified rectangle in the current graphics context.

- (NSRect)boundingRectWithSize:(NSSize)size options:(NSStringDrawingOptions)options attributes:(NSDictionary *)attributes
Parameters
size

The size of the rectangle to draw in.

options

String drawing options.

attributes

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Return Value

The bounding rect for the receiver drawn using the given options and display characteristics. The rect origin returned from this method is the first glyph origin.

Special Considerations

This method works in single-line, baseline rendering configuration by default. If the string drawing option NSStringDrawingUsesLineFragmentOrigin is specified, the method behaves in multiline configuration.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSStringDrawing.h

drawAtPoint:withAttributes:

Draws the receiver with the font and other display characteristics of the given attributes, at the specified point in the currently focused view.

- (void)drawAtPoint:(NSPoint)aPoint withAttributes:(NSDictionary *)attributes
Parameters
aPoint

The origin for the bounding box for drawing the string. If the focused view is flipped, the origin is the upper-left corner of the drawing bounding box; otherwise, the origin is the lower-left corner.

attributes

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

The width (height for vertical layout) of the rendering area is unlimited, unlike drawInRect:withAttributes:, which uses a bounding rectangle. As a result, this method renders the text in a single line.

You should only invoke this method when an NSView object has focus.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSStringDrawing.h

drawInRect:withAttributes:

Draws the receiver with the font and other display characteristics of the given attributes, within the specified rectangle in the currently focused NSView.

- (void)drawInRect:(NSRect)aRect withAttributes:(NSDictionary *)attributes
Parameters
aRect

The rectangle in which to draw the string.

attributes

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

The rendering area is bounded by aRect, unlike drawAtPoint:withAttributes:, which has an unlimited width. As a result, this method renders the text in multiple lines.

You should only invoke this method when an NSView object has focus.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSStringDrawing.h

drawWithRect:options:attributes:

Draws the receiver with the specified options and other display characteristics of the given attributes, within the specified rectangle in the current graphics context.

- (void)drawWithRect:(NSRect)rect options:(NSStringDrawingOptions)options attributes:(NSDictionary *)attributes
Parameters
rect

The rectangle in which to draw the string.

options

String drawing options.

attributes

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

This method works in single-line, baseline rendering configuration by default. That is, the rect argument's origin field specifies the rendering origin, and that point is interpreted as the baseline origin by default. If the string drawing option NSStringDrawingUsesLineFragmentOrigin is specified, origin is interpreted as the upper left corner of the line fragment rectangle, and the method behaves in multiline configuration.

The size field specifies the text container size. The width part of the size field specifies the maximum line fragment width if larger than 0.0. The height defines the maximum size that can be occupied with text if larger than 0.0 and NSStringDrawingUsesLineFragmentOrigin is specified. If NSStringDrawingUsesLineFragmentOrigin is not specified, height is ignored and considered to be single-line rendering (NSLineBreakByWordWrapping and NSLineBreakByCharWrapping are treated as NSLineBreakByClipping).

You should only invoke this method when there is a current graphics context.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSStringDrawing.h

sizeWithAttributes:

Returns the bounding box size the receiver occupies when drawn with the given attributes.

- (NSSize)sizeWithAttributes:(NSDictionary *)attributes
Parameters
attributes

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Return Value

The bounding box size the receiver occupies when drawn with attributes.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSStringDrawing.h

Constants

NSStringDrawingOptions

The following constants are provided as rendering options for a string when it is drawn.

enum {
   NSStringDrawingUsesLineFragmentOrigin = (1 << 0),
   NSStringDrawingUsesFontLeading = (1 << 1),
   NSStringDrawingDisableScreenFontSubstitution = (1 << 2),
   NSStringDrawingUsesDeviceMetrics = (1 << 3),
   NSStringDrawingOneShot = (1 << 4),
   NSStringDrawingTruncatesLastVisibleLine = (1 << 5)
};
typedef NSInteger NSStringDrawingOptions;
Constants
NSStringDrawingUsesLineFragmentOrigin

The specified origin is the line fragment origin, not the baseline origin.

Available in OS X v10.4 and later.

Declared in NSStringDrawing.h.

NSStringDrawingUsesFontLeading

Uses the font leading for calculating line heights.

Available in OS X v10.4 and later.

Declared in NSStringDrawing.h.

NSStringDrawingDisableScreenFontSubstitution

Disable screen font substitution (equivalent to [NSLayoutManager setUsesScreenFonts:NO]).

Available in OS X v10.4 and later.

Declared in NSStringDrawing.h.

NSStringDrawingUsesDeviceMetrics

Uses image glyph bounds instead of typographic bounds.

Available in OS X v10.4 and later.

Declared in NSStringDrawing.h.

NSStringDrawingOneShot

Suppresses caching layout information.

Available in OS X v10.4 and later.

Declared in NSStringDrawing.h.

NSStringDrawingTruncatesLastVisibleLine

Truncates and adds the ellipsis character to the last visible line if the text doesn't fit into the bounds specified.

This option is ignored if NSStringDrawingUsesLineFragmentOrigin is not also set. In addition, the line break mode must be either NSLineBreakByWordWrapping or NSLineBreakByCharWrapping for this option to take effect. The line break mode can be specified in a paragraph style passed in the attributes dictionary argument of the drawing methods.

Available in OS X v10.5 and later.

Declared in NSStringDrawing.h.