NSTextContainer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSTextContainer.h
Companion guides
Related sample code

Overview

The NSTextContainer class defines a region where text is laid out. An NSLayoutManager uses NSTextContainer to determine where to break lines, lay out portions of text, and so on. NSTextContainer defines rectangular regions, but you can create subclasses that define regions of other shapes, such as circular regions, regions with holes in them, or regions that flow alongside graphics.

Tasks

Creating an Instance

Managing Text Components

Controlling Size

Setting Line Fragment Padding

Calculating Text Layout

Mouse Hit Testing

Instance Methods

containerSize

Returns the size of the receiver’s bounding rectangle, regardless of the size of its region.

- (NSSize)containerSize
Return Value

The size of the receiver’s bounding rectangle, regardless of the size of its region.

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

containsPoint:

Overridden by subclasses to return whether a point lies within the receiver’s region or on the region’s edge—not simply within its bounding rectangle.

- (BOOL)containsPoint:(NSPoint)aPoint
Parameters
aPoint

The point in question.

Return Value

YES if aPoint lies within the receiver’s region or on the region’s edge—not simply within its bounding rectangle—NO otherwise.

Discussion

For example, if the receiver defines a donut shape and aPoint lies in the hole, this method returns NO. This method can be used for hit testing of mouse events.

The default NSTextContainer implementation merely checks that aPoint lies within its bounding rectangle.

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

heightTracksTextView

Returns whether the receiver adjusts the height of its bounding rectangle when its text view is resized.

- (BOOL)heightTracksTextView
Return Value

YES if the receiver adjusts the height of its bounding rectangle when its text view is resized, NO otherwise.

Discussion

If the receiver does track the text view height, its height is adjusted to the height of the text view minus twice the inset height (as given by NSTextView’s textContainerInset method).

See Text System Storage Layer Overview for more information on size tracking.

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

initWithContainerSize:

Initializes a text container with a specified bounding rectangle.

- (id)initWithContainerSize:(NSSize)aSize
Parameters
aSize

The size of the text container's bounding rectangle.

Return Value

The newly initialized text container.

Discussion

The new text container must be added to an NSLayoutManager object before it can be used. The text container must also have an NSTextView object set for text to be displayed. This method is the designated initializer for the NSTextContainer class.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextContainer.h

isSimpleRectangularTextContainer

Overridden by subclasses to return whether the receiver’s region is a rectangle with no holes or gaps and whose edges are parallel to the text view's coordinate system axes.

- (BOOL)isSimpleRectangularTextContainer
Return Value

YES if the receiver’s region is a rectangle with no holes or gaps and whose edges are parallel to the text view's coordinate system axes, NO otherwise.

Discussion

A text container whose shape changes can return YES if its region is currently a simple rectangle, but when its shape does change it must send textContainerChangedGeometry: to its layout manager so the layout can be recalculated.

The default NSTextContainer implementation of this method returns YES.

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

layoutManager

Returns the receiver’s layout manager.

- (NSLayoutManager *)layoutManager
Return Value

The text container's layout manager.

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

lineFragmentPadding

Returns the amount by which text is inset within line fragment rectangles.

- (CGFloat)lineFragmentPadding
Return Value

The amount by which text is inset within line fragment rectangles, in points.

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

lineFragmentRectForProposedRect:sweepDirection:movementDirection:remainingRect:

Overridden by subclasses to calculate and return the longest rectangle available in the proposed rectangle for displaying text, or NSZeroRect if there is none according to the receiver’s region definition.

- (NSRect)lineFragmentRectForProposedRect:(NSRect)proposedRect sweepDirection:(NSLineSweepDirection)sweepDirection movementDirection:(NSLineMovementDirection)movementDirection remainingRect:(NSRectPointer)remainingRect
Parameters
proposedRect

The proposed rectangle in which to layout text.

sweepDirection

The line sweep direction.

movementDirection

The line movement direction.

remainingRect

Upon return, the unused, possibly shifted, portion of proposedRect that’s available for further text, or NSZeroRect if there is no remainder.

Return Value

The longest rectangle available in the proposed rectangle for displaying text, or NSZeroRect if there is none according to the receiver’s region definition.

Discussion

There is no guarantee as to the width of the proposed rectangle or to its location. For example, the proposed rectangle is likely to be much wider than the width of the receiver. The receiver should examine proposedRect to see that it intersects its bounding rectangle and should return a modified rectangle based on sweepDirection and movementDirection, whose possible values are listed in the class description. If sweepDirection is NSLineSweepRight, for example, the receiver uses this information to trim the right end of proposedRect as needed rather than the left end.

If proposedRect doesn’t completely overlap the region along the axis of movementDirection and movementDirection isn’t NSLineDoesntMove, this method can either shift the rectangle in that direction as much as needed so that it does completely overlap, or return NSZeroRect to indicate that the proposed rectangle simply doesn’t fit.

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

replaceLayoutManager:

Replaces the layout manager for the group of text system objects containing the receiver.

- (void)replaceLayoutManager:(NSLayoutManager *)aLayoutManager
Parameters
aLayoutManager

The new layout manager.

Discussion

All text containers and text views sharing the original layout manager share the new layout manager. This method makes all the adjustments necessary to keep these relationships intact, unlike setLayoutManager:.

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

setContainerSize:

Sets the size of the receiver’s bounding rectangle.

- (void)setContainerSize:(NSSize)aSize
Parameters
aSize

The new size of the text container's bounding rectangle.

Discussion

This method also sends textContainerChangedGeometry: to the text container's layout manager.

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

setHeightTracksTextView:

Controls whether the receiver adjusts the height of its bounding rectangle when its text view is resized.

- (void)setHeightTracksTextView:(BOOL)flag
Parameters
flag

YES if the receiver should follow changes to the height of its text view, NO otherwise.

Discussion

See Text System Storage Layer Overview for more information on size tracking.

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

setLayoutManager:

Sets the receiver’s layout manager.

- (void)setLayoutManager:(NSLayoutManager *)aLayoutManager
Parameters
aLayoutManager

The new layout manager.

Discussion

This method is invoked automatically when you add a text container to a layout manager; you should never need to invoke it directly, but might want to override it. If you want to replace the layout manager for an established group of text system objects, use replaceLayoutManager:.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextContainer.h

setLineFragmentPadding:

Sets the amount by which text is inset within line fragment rectangles.

- (void)setLineFragmentPadding:(CGFloat)aFloat
Parameters
aFloat

The amount by which text is inset within line fragment rectangles, in points.

Discussion

This method also sends textContainerChangedGeometry: to the text container's layout manager.

Line fragment padding is not designed to express text margins. Instead, use the NSTextView method setTextContainerInset:, paragraph margin attributes, or the position of the text view within a superview.

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

setTextView:

Sets the receiver’s text view.

- (void)setTextView:(NSTextView *)aTextView
Parameters
aTextView

The new text view.

Discussion

This method sends setTextContainer: to aTextView to complete the association of the text container and text view.

Because you usually specify a text container when you create a text view, you should rarely need to invoke this method. A text container doesn’t need a text view to calculate line fragment rectangles, but must have one to display text.

You can use this method to disconnect a text view from a group of text system objects by sending this message to its text container and passing nil as aTextView.

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

setWidthTracksTextView:

Controls whether the receiver adjusts the width of its bounding rectangle when its text view is resized.

- (void)setWidthTracksTextView:(BOOL)flag
Parameters
flag

YES if the receiver should follow changes to the width of its text view, NO otherwise.

Discussion

See Text System Storage Layer Overview for more information on size tracking.

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

textView

Returns the receiver’s text view.

- (NSTextView *)textView
Return Value

The receiver's text view, or nil if it has none.

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

widthTracksTextView

Returns whether the receiver adjusts the width of its bounding rectangle when its text view is resized.

- (BOOL)widthTracksTextView
Return Value

YES if the receiver adjusts the width of its bounding rectangle when its text view is resized, NO otherwise.

Discussion

If the receiver does track the text view width, its width is adjusted to the width of the text view minus twice the inset width (as given by NSTextView’s textContainerInset method).

See Text System Storage Layer Overview for more information on size tracking.

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

Constants

NSLineSweepDirection

These constants describe the progression of text on a page. The typesetter decides which way text is supposed to flow and passes these values as arguments to the text container, which uses them to calculate the next line rectangle.

enum {
   NSLineSweepLeft  = 0,
   NSLineSweepRight = 1,
   NSLineSweepDown  = 2,
   NSLineSweepUp    = 3
};
typedef NSUInteger NSLineSweepDirection;
Constants
NSLineSweepLeft

Characters move from right to left.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

NSLineSweepRight

Characters move from left to right.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

NSLineSweepDown

Characters move from top to bottom.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

NSLineSweepUp

Characters move from bottom to top.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

Discussion

Line sweep is the direction text progresses within a line. See Text System Storage Layer Overview.

The only values currently used by the supplied typesetters are NSLineSweepRight and NSLineMovesDown. An NSTextContainer subclass should be prepared to deal with any value, and an NSTypesetter subclass should be able to use any of them.

Declared In
NSTextContainer.h

NSLineMovementDirection

Line movement is the direction in which lines move. See Text System Storage Layer Overview.

enum {
   NSLineDoesntMove = 0,
   NSLineMovesLeft  = 1,
   NSLineMovesRight = 2,
   NSLineMovesDown  = 3,
   NSLineMovesUp    = 4
};
typedef NSUInteger NSLineMovementDirection;
Constants
NSLineMovesLeft

Lines move from right to left.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

NSLineMovesRight

Lines move from left to right.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

NSLineMovesDown

Lines move from top to bottom.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

NSLineMovesUp

Lines move from bottom to top.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

NSLineDoesntMove

Line has no movement.

Available in OS X v10.0 and later.

Declared in NSTextContainer.h.

Declared In
NSTextContainer.h