Mac Developer Library

Developer

AppKit Framework Reference NSTextContainer Class Reference

Options
Deployment Target:

On This Page
Language:

NSTextContainer

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. An NSTextContainer object normally defines rectangular regions, but you can define exclusion paths inside the text container to create regions where text does not flow. You can also subclass to create text containers with nonrectangular regions, such as circular regions, regions with holes in them, or regions that flow alongside graphics.

Instances of the NSTextContainer, NSLayoutManager, and NSTextStorage classes can be accessed from threads other than the main thread as long as the app guarantees access from only one thread at a time.

  • init(size:) - initWithSize: Designated Initializer

    Initializes a text container with a specified bounding rectangle.

    Declaration

    Swift

    init(size size: NSSize)

    Objective-C

    - (instancetype)initWithSize:(NSSize)size

    Parameters

    size

    The size of the text container's bounding rectangle.

    Return Value

    The size of the text container's bounding rectangle.

    Discussion

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

    Availability

    Available in OS X v10.11 and later.

    See Also

    – addTextContainer: (NSLayoutManager)

  • The receiver’s layout manager.

    Declaration

    Swift

    unowned(unsafe) var layoutManager: NSLayoutManager?

    Objective-C

    @property(assign) NSLayoutManager *layoutManager

    Discussion

    Avoid assigning a layout manager directly through this property. Instead, use the replaceLayoutManager: method when you want to replace the layout manager. The value of this property is set automatically when you add a text container to your layout manager using the addTextContainer: method.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func replaceLayoutManager(_ newLayoutManager: NSLayoutManager)

    Objective-C

    - (void)replaceLayoutManager:(NSLayoutManager *)aLayoutManager

    Parameters

    aLayoutManager

    The new layout manager.

    Discussion

    All text containers and text views attached to the old layout manager are reassigned to the new layout manager. Unlike setting the layoutManager property directly, this method makes all the adjustments necessary to keep the text object relationships intact.

    Availability

    Available in OS X v10.0 and later.

    See Also

    layoutManager

  • The receiver’s text view.

    Declaration

    Swift

    var textView: NSTextView?

    Objective-C

    @property(strong) NSTextView *textView

    Discussion

    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 property 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.

  • size size Property

    The size of the text container’s bounding rectangle.

    Declaration

    Swift

    var size: NSSize

    Objective-C

    @property NSSize size

    Discussion

    This property defines the maximum size for the layout area returned from lineFragmentRectForProposedRect:atIndex:writingDirection:remainingRect:. A value of 0.0 or less means no limitation.

    The default value of this property is CGSizeZero.

    Availability

    Available in OS X v10.11 and later.

    See Also

    heightTracksTextView
    widthTracksTextView

  • An array of path objects representing the regions where text is not displayed in the text container.

    Declaration

    Swift

    var exclusionPaths: [NSBezierPath]

    Objective-C

    @property(copy) NSArray <NSBezierPath *> *exclusionPaths

    Discussion

    The default value of this property is an empty array. Depending on the platform, you can assign an array of NSBezierPath or UIBezierPath objects to exclude text from one or more regions in the text container’s bounds. When the layout manager proposes a line fragment rectangle intersecting one of the regions defined by the exclusion paths, the text container returns an adjusted line fragment rectangle excluding that region.

    Availability

    Available in OS X v10.11 and later.

  • The behavior of the last line inside the text container.

    Declaration

    Swift

    var lineBreakMode: NSLineBreakMode

    Objective-C

    @property NSLineBreakMode lineBreakMode

    Discussion

    The NSLineBreakMode constants specify what happens when a line is too long for its container. For example, wrapping can occur on word boundaries (the default) or character boundaries, or the line can be clipped or truncated. The default value of this property is NSLineBreakByWordWrapping.

    Availability

    Available in OS X v10.11 and later.

  • containerSize containerSize (OS X v10.11) Property

    The size of the receiver’s bounding rectangle.

    Deprecation Statement

    Use size instead.

    Declaration

    Swift

    var containerSize: NSSize

    Objective-C

    @property NSSize containerSize

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

    See Also

    – setTextContainerInset: (NSTextView)

  • A Boolean that controls whether the receiver adjusts the width of its bounding rectangle when its text view is resized.

    Declaration

    Swift

    var widthTracksTextView: Bool

    Objective-C

    @property BOOL widthTracksTextView

    Discussion

    When the value of this property is YEStrue, the text container adjusts its widith when the width of its text view changes. The default value of this property is NOfalse.

    For more information about size tracking, see Text System Storage Layer Overview.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that controls whether the receiver adjusts the height of its bounding rectangle when its text view is resized.

    Declaration

    Swift

    var heightTracksTextView: Bool

    Objective-C

    @property BOOL heightTracksTextView

    Discussion

    When the value of this property is YEStrue, the text container adjusts its height when the height of its text view changes. The default value of this property is NOfalse.

    For more information about size tracking, see Text System Storage Layer Overview.

    Availability

    Available in OS X v10.0 and later.

  • The maximum number of lines that can be stored in the text container.

    Declaration

    Swift

    var maximumNumberOfLines: Int

    Objective-C

    @property NSUInteger maximumNumberOfLines

    Discussion

    The layout manager uses the value of this property to determine the maximum number of lines associated with the text container. The default value of this property is 0, which indicates that there is no limit.

    Availability

    Available in OS X v10.11 and later.

  • The amount by which text is inset within line fragment rectangles.

    Declaration

    Swift

    var lineFragmentPadding: CGFloat

    Objective-C

    @property CGFloat lineFragmentPadding

    Discussion

    The padding appears at the beginning and end of the line fragment rectangles. The layout manager uses this value to determine the layout width. The default value of this property is 5.0.

    Line fragment padding is not designed to express text margins. Instead, you should use insets on your text view, adjust the paragraph margin attributes, or change the position of the text view within its superview.

    Availability

    Available in OS X v10.0 and later.

  • Returns the bounds of a line fragment rectangle inside the receiver for the proposed rectangle.

    Declaration

    Swift

    func lineFragmentRectForProposedRect(_ proposedRect: NSRect, atIndex characterIndex: Int, writingDirection baseWritingDirection: NSWritingDirection, remainingRect remainingRect: UnsafeMutablePointer<NSRect>) -> NSRect

    Objective-C

    - (NSRect)lineFragmentRectForProposedRect:(NSRect)proposedRect atIndex:(NSUInteger)characterIndex writingDirection:(NSWritingDirection)baseWritingDirection remainingRect:(NSRect *)remainingRect

    Parameters

    proposedRect

    A rectangle in which to lay out text proposed by the layout manager.

    characterIndex

    The character location inside the text storage for the line fragment being processed.

    baseWritingDirection

    The direction of advancement for line fragments inside a visual horizontal line. The values passed into the method are either NSWritingDirectionLeftToRight or NSWritingDirectionRightToLeft.

    remainingRect

    The remainder of the proposed rectangle that was excluded from returned rectangle. It can be passed in as the proposed rectangle for the next iteration.

    Discussion

    The bounds of the line fragment rectangle are determined by the intersection of proposedRect and the text container’s bounding rectangle defined by its size property. The regions defined by the exclusionPaths property are excluded from the return value. It is possible that proposedRect can be divided into multiple line fragments due to exclusion paths. In that case, remainingRect returns the remainder that can be passed in as the proposed rectangle for the next iteration.

    This method can be overridden by subclasses for further text container region customization.

    Availability

    Available in OS X v10.11 and later.

  • A boolean that indicates 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. (read-only)

    Declaration

    Swift

    var simpleRectangularTextContainer: Bool { get }

    Objective-C

    @property(getter=isSimpleRectangularTextContainer, readonly) BOOL simpleRectangularTextContainer

    Discussion

    The value of this property is YEStrue when the text container’s region is a rectangle with no holes or gaps and the edges are parallel to the text view's coordinate system axes. The default value of this property is NOfalse when the exclusionPaths property contains one or more items, when the maximumNumberOfLines property is not zero, or when you override the lineFragmentRectForProposedRect:atIndex:writingDirection:remainingRect: method. Otherwise, the default value is YEStrue.

    Availability

    Available in OS X v10.0 and later.

  • Initializes a text container with a specified bounding rectangle.

    Deprecation Statement

    Use initWithSize: instead. For binary compatibility, this method now just calls [self initWithSize:].

    Declaration

    Swift

    convenience init(containerSize aContainerSize: NSSize)

    Objective-C

    - (instancetype)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.

    Deprecated in OS X v10.11.

    See Also

    – addTextContainer: (NSLayoutManager)
    textView

  • 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.

    Declaration

    Swift

    func lineFragmentRectForProposedRect(_ proposedRect: NSRect, sweepDirection sweepDirection: NSLineSweepDirection, movementDirection movementDirection: NSLineMovementDirection, remainingRect remainingRect: NSRectPointer) -> NSRect

    Objective-C

    - (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.

    Deprecated in OS X v10.11.

  • 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.

    Declaration

    Swift

    func containsPoint(_ point: NSPoint) -> Bool

    Objective-C

    - (BOOL)containsPoint:(NSPoint)aPoint

    Parameters

    aPoint

    The point in question.

    Return Value

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

    Discussion

    For example, if the receiver defines a donut shape and aPoint lies in the hole, this method returns NOfalse. 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.

    Deprecated in OS X v10.11.

  • 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.

    Declaration

    Swift

    enum NSLineSweepDirection : UInt { case Left case Right case Down case Up }

    Objective-C

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

    Constants

    • left

      NSLineSweepLeft

      Characters move from right to left.

      Available in OS X v10.0 and later.

    • right

      NSLineSweepRight

      Characters move from left to right.

      Available in OS X v10.0 and later.

    • down

      NSLineSweepDown

      Characters move from top to bottom.

      Available in OS X v10.0 and later.

    • up

      NSLineSweepUp

      Characters move from bottom to top.

      Available in OS X v10.0 and later.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    enum NSLineMovementDirection : UInt { case DoesntMove case MovesLeft case MovesRight case MovesDown case MovesUp }

    Objective-C

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

    Constants

    • movesLeft

      NSLineMovesLeft

      Lines move from right to left.

      Available in OS X v10.0 and later.

    • movesRight

      NSLineMovesRight

      Lines move from left to right.

      Available in OS X v10.0 and later.

    • movesDown

      NSLineMovesDown

      Lines move from top to bottom.

      Available in OS X v10.0 and later.

    • movesUp

      NSLineMovesUp

      Lines move from bottom to top.

      Available in OS X v10.0 and later.

    • doesntMove

      NSLineDoesntMove

      Line has no movement.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.