Next Page >

Hide TOC

NSString Application Kit Additions Reference

Inherits from	NSObject
Framework	/System/Library/Frameworks/AppKit.framework
Declared in	NSStringDrawing.h
Companion guides	String Programming Guide for Cocoa Attributed Strings Programming Guide

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 Application Kit 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.

Availability

Available in Mac 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 Mac 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 has focus.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

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

The rect argument's origin field specifies the rendering origin. The point is interpreted as the baseline origin by default. With NSStringDrawingUsesLineFragmentOrigin, it is interpreted as the upper left corner of the line fragment rect. 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 Mac 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 Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSStringDrawing.h

Constants

String Drawing Options

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;