NSTextBlock Class Reference

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

• – init

Working with Dimensions of Content

• – setValue:type:forDimension:
• – valueForDimension:
• – valueTypeForDimension:
• – setContentWidth:type:
• – contentWidth
• – contentWidthValueType

Getting and Setting Margins, Borders, and Padding

• – setWidth:type:forLayer:edge:
• – setWidth:type:forLayer:
• – widthForLayer:edge:
• – widthValueTypeForLayer:edge:

Getting and Setting Alignment

• – setVerticalAlignment:
• – verticalAlignment

Working with Color

• – setBackgroundColor:
• – backgroundColor
• – setBorderColor:forEdge:
• – setBorderColor:
• – borderColorForEdge:

Determining Size and Position of a Text Block

• – rectForLayoutAtPoint:inRect:textContainer:characterRange:
• – boundsRectForContentRect:inRect:textContainer:characterRange:

Drawing Colors and Decorations

• – drawBackgroundWithFrame:inView:characterRange:layoutManager:

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 Mac OS X v10.4 and later.

See Also

• – setBackgroundColor:

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 Mac OS X v10.4 and later.

See Also

• – setBorderColor:forEdge:

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 Mac OS X v10.4 and later.

See Also

• – rectForLayoutAtPoint:inRect:textContainer:characterRange:

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 Mac OS X v10.4 and later.

See Also

• – setContentWidth:type:
• – contentWidthValueType

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 Mac OS X v10.4 and later.

See Also

• – setContentWidth:type:
• – contentWidth

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 Mac 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 Mac 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 Mac OS X v10.4 and later.

See Also

• – boundsRectForContentRect:inRect:textContainer:characterRange:

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 Mac OS X v10.4 and later.

See Also

• – backgroundColor

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 Mac OS X v10.4 and later.

See Also

• – borderColorForEdge:
• – setBorderColor:forEdge:
• – setWidth:type:forLayer:

Related Sample Code

• iSpend

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 Mac OS X v10.4 and later.

See Also

• – borderColorForEdge:
• – setWidth:type:forLayer:

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 Mac OS X v10.4 and later.

See Also

• – contentWidth
• – contentWidthValueType

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 Mac OS X v10.4 and later.

See Also

• – valueForDimension:
• – valueTypeForDimension:

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 Mac OS X v10.4 and later.

See Also

• – verticalAlignment

Related Sample Code

• iSpend

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 Mac OS X v10.4 and later.

See Also

• – widthForLayer:edge:
• – setWidth:type:forLayer:edge:

Related Sample Code

• iSpend

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 Mac OS X v10.4 and later.

See Also

• – setWidth:type:forLayer:
• – widthForLayer:edge:

Related Sample Code

• iSpend

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 Mac OS X v10.4 and later.

See Also

• – setValue:type:forDimension:
• valueTypeForDimension:

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 Mac OS X v10.4 and later.

See Also

• – setValue:type:forDimension:
• valueForDimension:

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 Mac OS X v10.4 and later.

See Also

• – setVerticalAlignment:

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 Mac OS X v10.4 and later.

See Also

• widthValueTypeForLayer:edge:
• – setWidth:type:forLayer:edge:
• – setWidth:type:forLayer:

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 Mac OS X v10.4 and later.

See Also

• widthForLayer:edge:
• – setWidth:type:forLayer:edge:

Declared In

NSTextTable.h

Constants

NSTextBlockValueType

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 Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockPercentageValueType

Percentage value (out of 100)

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockDimension

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 Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMinimumWidth

Minimum width of the text block

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMaximumWidth

Maximum width of the text block

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockHeight

Height of the text block

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMinimumHeight

Minimum height of the text block

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMaximumHeight

Maximum height of the text block

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockLayer

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 Mac 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 Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMargin

Margin of the text block: space surrounding the border

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockVerticalAlignment

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 Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockMiddleAlignment

Aligns adjacent blocks at their middle

Available in Mac OS X v10.4 and later.

Declared in NSTextTable.h.

NSTextBlockBottomAlignment

Aligns adjacent blocks at their bottom

Available in Mac 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 Mac OS X v10.4 and later.

Declared in NSTextTable.h.

---