NSTextBlock Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.4 and later.
Declared in
NSTextTable.h
Companion guides
Text System Overview
Text Layout Programming Guide

Overview

NSTextBlock objects represent a block of text laid out in a subregion of the text container. Text blocks appear as attributes on paragraphs, as part of the paragraph style.

The most important subclass is NSTextTableBlock, which represents a block of text that appears as a cell in a table. The table itself is represented by a separate class, NSTextTable, which is referenced by all of its NSTextTableBlock objects and which controls their sizing and positioning.

Tasks

Creating Text Blocks

Working with Dimensions of Content

Getting and Setting Margins, Borders, and Padding

Getting and Setting Alignment

Working with Color

Determining Size and Position of a Text Block

Drawing Colors and Decorations

Instance Methods

backgroundColor

Returns the background color of the text block.

- (NSColor *)backgroundColor
Return Value

The background color of the text block.

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

borderColorForEdge:

Returns the border color of the specified text block edge.

- (NSColor *)borderColorForEdge:(NSRectEdge)edge
Parameters
edge

The edge of the text block in question.

Return Value

The border color of the text block edge edge.

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

boundsRectForContentRect:inRect:textContainer:characterRange:

Returns the rectangle the text in the block actually occupies, including padding, borders, and margins.

- (NSRect)boundsRectForContentRect:(NSRect)contentRect inRect:(NSRect)rect textContainer:(NSTextContainer *)textContainer characterRange:(NSRange)charRange
Parameters
contentRect

The actual rectangle in which the text was laid out, as determined by rectForLayoutAtPoint:inRect:textContainer:characterRange:.

rect

The initial rectangle in textContainer proposed by the typesetter.

textContainer

The text container being used for the layout.

charRange

The range of the characters in the NSTextStorage object whose glyphs are to be drawn.

Return Value

The rectangle the text in the block actually occupies, including padding, borders, and margins.

Discussion

This methods is called by the typesetter after the text block is laid out to return the rectangle the text in the block actually occupies, including padding, borders, and margins.

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

contentWidth

Returns the width of the text block.

- (CGFloat)contentWidth
Return Value

The width of the text block. This value must be interpreted according to the value type returned by contentWidthValueType.

Discussion

This is a convenience method that invokes valueForDimension:NSTextBlockWidth.

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

contentWidthValueType

Returns the type of value stored for the text block width.

- (NSTextBlockValueType)contentWidthValueType
Return Value

The value type for the text block width. This determines how the width value should be interpreted.

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

drawBackgroundWithFrame:inView:characterRange:layoutManager:

Called by the layout manager to draw any colors and other decorations before the text is drawn.

- (void)drawBackgroundWithFrame:(NSRect)frameRect inView:(NSView *)controlView characterRange:(NSRange)charRange layoutManager:(NSLayoutManager *)layoutManager
Parameters
frameRect

The bounds rectangle in view coordinates.

controlView

The view in which drawing occurs.

charRange

The range of the characters in the NSTextStorage object whose glyphs are to be drawn.

layoutManager

The layout manager controlling the typesetting.

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

init

Initializes and returns an empty text block object.

- (id)init
Return Value

An initialized text block object.

Discussion

This is the designated initializer for NSTextBlock.

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

rectForLayoutAtPoint:inRect:textContainer:characterRange:

Returns the rectangle within which glyphs should be laid out for the specified arguments.

- (NSRect)rectForLayoutAtPoint:(NSPoint)startingPoint inRect:(NSRect)rect textContainer:(NSTextContainer *)textContainer characterRange:(NSRange)charRange
Parameters
startingPoint

The location, in container coordinates, where layout begins.

rect

The rectangle in which the block is constrained to lie. For top-level blocks, this is the container rectangle of textContainer; for nested blocks, this is the layout rectangle of the enclosing block.

textContainer

The text container being used for the layout.

charRange

The range of the characters in the NSTextStorage object whose glyphs are to be drawn.

Return Value

The rectangle within which glyphs should be laid out.

Discussion

This method is called by the typesetter before the text block is laid out to return the rectangle within which glyphs should be laid out.

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

setBackgroundColor:

Sets the background color of the text block.

- (void)setBackgroundColor:(NSColor *)color
Parameters
color

The new background color.

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

setBorderColor:

Sets the color of all borders of the text block.

- (void)setBorderColor:(NSColor *)color
Parameters
color

The new color.

Discussion

This setting has no visible effect unless the border width is larger than the default, which is 0.

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

setBorderColor:forEdge:

Sets the border color of the specified edge of the text block.

- (void)setBorderColor:(NSColor *)color forEdge:(NSRectEdge)edge
Parameters
color

The new color.

edge

The edge whose color is to be set.

Discussion

This setting has no visible effect unless the border width is larger than the default, which is 0.

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

setContentWidth:type:

Sets the width of the text block.

- (void)setContentWidth:(CGFloat)val type:(NSTextBlockValueType)type
Parameters
val

The new value for the width.

type

The type of value being provided. This controls how val is interpreted.

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

setValue:type:forDimension:

Sets a dimension of the text block.

- (void)setValue:(CGFloat)val type:(NSTextBlockValueType)type forDimension:(NSTextBlockDimension)dimension
Parameters
val

The new value for the dimension.

type

The type of value being provided. This controls how val is interpreted.

dimension

The dimension to set.

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

setVerticalAlignment:

Sets the vertical alignment of the text block.

- (void)setVerticalAlignment:(NSTextBlockVerticalAlignment)alignment
Parameters
alignment

The new vertical alignment for the text block.

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

setWidth:type:forLayer:

Sets the width of all edges of a specified layer of the text block.

- (void)setWidth:(CGFloat)val type:(NSTextBlockValueType)type forLayer:(NSTextBlockLayer)layer
Parameters
val

The new value for the specified edge width.

type

The type of value being provided. This controls how val is interpreted.

layer

The layer of the text block to modify.

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

setWidth:type:forLayer:edge:

Sets the width of a specified edge of a specified layer of the text block.

- (void)setWidth:(CGFloat)val type:(NSTextBlockValueType)type forLayer:(NSTextBlockLayer)layer edge:(NSRectEdge)edge
Parameters
val

The new value for the specified edge width.

type

The type of value being provided. This controls how val is interpreted.

layer

The layer of the text block to modify.

edge

The edge of the layer to modify.

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

valueForDimension:

Returns the value of the specified text block dimension.

- (CGFloat)valueForDimension:(NSTextBlockDimension)dimension
Return Value

The value for the specified dimension. This value should be interpreted according to the value type returned by valueTypeForDimension:.

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

valueTypeForDimension:

Returns the value type of the specified text block dimension.

- (NSTextBlockValueType)valueTypeForDimension:(NSTextBlockDimension)dimension
Return Value

The value type for the specified text block dimension. This result determines how the value for the dimension should be interpreted.

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

verticalAlignment

Returns the vertical alignment of the text block.

- (NSTextBlockVerticalAlignment)verticalAlignment
Return Value

The vertical alignment of the text block.

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

widthForLayer:edge:

Returns the width of an edge of a specified layer of the text block.

- (CGFloat)widthForLayer:(NSTextBlockLayer)layer edge:(NSRectEdge)edge
Parameters
layer

The layer to examine.

edge

The edge of the layer to examine.

Return Value

The width of the edge of layer. This value must be interpreted according to the value type returned by widthValueTypeForLayer:edge:.

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

widthValueTypeForLayer:edge:

Returns the value type of an edge of a specified layer of the text block.

- (NSTextBlockValueType)widthValueTypeForLayer:(NSTextBlockLayer)layer edge:(NSRectEdge)edge
Parameters
layer

The layer to examine.

edge

The edge of the layer to examine.

Return Value

The value type of the edge of layer. This determines how the value for this edge of layer should be interpreted.

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

Constants

Text Block Value Type Constants

The following constants specify values used by the methods setValue:type:forDimension: and valueTypeForDimension:

enum {
   NSTextBlockAbsoluteValueType    = 0,
   NSTextBlockPercentageValueType  = 1
};
typedef NSUInteger NSTextBlockValueType;
Constants
NSTextBlockAbsoluteValueType

Absolute value in points.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockPercentageValueType

Percentage value (out of 100).

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockValueType

A type defined for the text block value type constants.

Text Block Dimension Constants

The following constants specify values used by the methods setValue:type:forDimension:, valueForDimension:, and valueTypeForDimension:.

enum {
   NSTextBlockWidth            = 0,
   NSTextBlockMinimumWidth     = 1,
   NSTextBlockMaximumWidth     = 2,
   NSTextBlockHeight           = 4,
   NSTextBlockMinimumHeight    = 5,
   NSTextBlockMaximumHeight    = 6
};
typedef NSUInteger NSTextBlockDimension;
Constants
NSTextBlockWidth

Width of the text block.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMinimumWidth

Minimum width of the text block.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMaximumWidth

Maximum width of the text block.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockHeight

Height of the text block.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMinimumHeight

Minimum height of the text block.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMaximumHeight

Maximum height of the text block.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockDimension

A type defined for the text block dimension constants.

Text Block Layer Constants

The following constants specify values used by the methods setContentWidth:type:, contentWidthValueType, setWidth:type:forLayer:edge:, setWidth:type:forLayer:, widthForLayer:edge:, and widthValueTypeForLayer:edge:.

enum {
   NSTextBlockPadding  = -1,
   NSTextBlockBorder   =  0,
   NSTextBlockMargin   =  1
};
typedef NSInteger NSTextBlockLayer;
Constants
NSTextBlockPadding

Padding of the text block: space surrounding the content area extending to the border.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockBorder

Border of the text block: space between padding and margin, typically colored to present a visible boundary.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMargin

Margin of the text block: space surrounding the border.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockLayer

A type defined for the text block layer constants.

Text Block Vertical Alignment Constants

The following constants specify values used by the methods setVerticalAlignment: and verticalAlignment.

enum {
   NSTextBlockTopAlignment         = 0,
   NSTextBlockMiddleAlignment      = 1,
   NSTextBlockBottomAlignment      = 2,
   NSTextBlockBaselineAlignment    = 3
};
typedef NSUInteger NSTextBlockVerticalAlignment;
Constants
NSTextBlockTopAlignment

Aligns adjacent blocks at their top.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMiddleAlignment

Aligns adjacent blocks at their middle.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockBottomAlignment

Aligns adjacent blocks at their bottom.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockBaselineAlignment

Aligns adjacent blocks at the baseline of the first line of text in the block.

Available in OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockVerticalAlignment

A type defined for the text block vertical alignment constants.