---

NSText Class Reference

Class at a Glance

NSText declares the most general programmatic interface for objects that manage text. You usually use instances of its subclass, NSTextView.

Principal Attributes

• Draws text for user interface objects

• Uses a delegate

• Provides text editing capabilities

• Controls text attributes such as typesize, font, and color

Commonly Used Methods

readRTFDFromFile:

Reads an .rtf or .rtfd file.

writeRTFDToFile:atomically:

Writes the receiver’s text to a file.

string

Returns the receiver’s text without attributes.

RTFFromRange:

Returns the receiver’s text with attributes.

RTFDFromRange:

Returns the receiver’s text with attributes and attachments.

Overview

NSText declares the most general programmatic interface for objects that manage text. You usually use instances of its subclass, NSTextView.

NSTextView extends the interface declared by NSText and provides much more sophisticated functionality than that declared in NSText.

NSText initialization creates an instance of a concrete subclass, such as NSTextView. Instances of any of these classes are generically called text objects.

Text objects are used by the Application Kit wherever text appears in interface objects: A text object draws the title of a window, the commands in a menu, the title of a button, and the items in a browser. Your application can also create text objects for its own purposes.

Adopted Protocols

• – changeSpelling:

• – ignoreSpelling:

Tasks

Getting the Characters

• – string

Setting Graphics Attributes

• – setBackgroundColor:
• – backgroundColor
• – setDrawsBackground:
• – drawsBackground

Setting Behavioral Attributes

• – setEditable:
• – isEditable
• – setSelectable:
• – isSelectable
• – setFieldEditor:
• – isFieldEditor
• – setRichText:
• – isRichText
• – setImportsGraphics:
• – importsGraphics

Using the Font Panel and Menu

• – setUsesFontPanel:
• – usesFontPanel

Using the Ruler

• – toggleRuler:
• – isRulerVisible

Changing the Selection

• – setSelectedRange:
• – selectedRange

Replacing Text

• – replaceCharactersInRange:withRTF:
• – replaceCharactersInRange:withRTFD:
• – replaceCharactersInRange:withString:
• – setString:

Action Methods for Editing

• – selectAll:
• – copy:
• – cut:
• – paste:
• – copyFont:
• – pasteFont:
• – copyRuler:
• – pasteRuler:
• – delete:

Changing the Font

• – changeFont:
• – setFont:
• – setFont:range:
• – font

Setting Text Alignment

• – setAlignment:
• – alignCenter:
• – alignLeft:
• – alignRight:
• – alignment

Setting Text Color

• – setTextColor:
• – setTextColor:range:
• – textColor

Writing Direction

• – baseWritingDirection
• – setBaseWritingDirection:

Setting Superscripting and Subscripting

• – superscript:
• – subscript:
• – unscript:

Underlining Text

• – underline:

Reading and Writing RTF Files

• – readRTFDFromFile:
• – writeRTFDToFile:atomically:
• – RTFDFromRange:
• – RTFFromRange:

Checking Spelling

• – checkSpelling:
• – showGuessPanel:

Constraining Size

• – setMaxSize:
• – maxSize
• – setMinSize:
• – minSize
• – setVerticallyResizable:
• – isVerticallyResizable
• – setHorizontallyResizable:
• – isHorizontallyResizable
• – sizeToFit

Scrolling

• – scrollRangeToVisible:

Setting the Delegate

• – setDelegate:
• – delegate

Editing text

• – textShouldBeginEditing:  delegate method
• – textDidBeginEditing:  delegate method
• – textShouldEndEditing:  delegate method
• – textDidEndEditing:  delegate method

Changing text formatting

• – textDidChange:  delegate method

Instance Methods

alignCenter:

This action method applies center alignment to selected paragraphs (or all text if the receiver is a plain text object).

- (void)alignCenter:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – alignLeft:
• – alignRight:
• – alignment
• – setAlignment:

Declared In

NSText.h

alignLeft:

This action method applies left alignment to selected paragraphs (or all text if the receiver is a plain text object).

- (void)alignLeft:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – alignCenter:
• – alignRight:
• – alignment
• – setAlignment:

Declared In

NSText.h

alignment

Returns the alignment of the first paragraph (or all text if the receiver is a plain text object).

- (NSTextAlignment)alignment

Discussion

The returned value is one of the alignments described in NSTextAlignment.

Text using NSNaturalTextAlignment is actually displayed using one of the other alignments, depending on the natural alignment of the text’s script.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSText.h

alignRight:

This action method applies right alignment to selected paragraphs (or all text if the receiver is a plain text object).

- (void)alignRight:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – alignLeft:
• – alignCenter:
• – alignment
• – setAlignment:

Declared In

NSText.h

backgroundColor

Returns the receiver’s background color.

- (NSColor *)backgroundColor

Return Value

The receiver’s background color.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – drawsBackground
• – setBackgroundColor:

Declared In

NSText.h

baseWritingDirection

Returns the initial writing direction used to determine the actual writing direction for text.

- (NSWritingDirection)baseWritingDirection

Discussion

The Text system uses this value as a hint for calculating the actual direction for displaying Unicode characters. You should not need to call this method directly. If no writing direction is set, returns NSWritingDirectionNatural.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setBaseWritingDirection:

Declared In

NSText.h

changeFont:

This action method changes the font of the selection for a rich text object, or of all text for a plain text object.

- (void)changeFont:(id)sender

Discussion

If the receiver doesn’t use the Font panel, this method does nothing.

This method changes the font by sending a convertFont: message to the shared NSFontManager and applying each NSFont returned to the appropriate text. See the NSFontManager class specification for more information on font conversion.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – usesFontPanel

Declared In

NSText.h

checkSpelling:

This action method searches for a misspelled word in the receiver’s text.

- (void)checkSpelling:(id)sender

Discussion

The search starts at the end of the selection and continues until it reaches a word suspected of being misspelled or the end of the text. If a word isn’t recognized by the spelling server, a showGuessPanel: message then opens the Guess panel and allows the user to make a correction or add the word to the local dictionary.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – showGuessPanel:

Declared In

NSText.h

copy:

This action method copies the selected text onto the general pasteboard, in as many formats as the receiver supports.

- (void)copy:(id)sender

Discussion

A plain text object uses NSStringPboardType for plain text, and a rich text object also uses NSRTFPboardType.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – copyFont:
• – copyRuler:
• – cut:
• – paste:

Declared In

NSText.h

copyFont:

This action method copies the font information for the first character of the selection (or for the insertion point) onto the font pasteboard, as NSFontPboardType.

- (void)copyFont:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – copy:
• – copyRuler:
• – cut:
• – paste:

Declared In

NSText.h

copyRuler:

This action method copies the paragraph style information for first selected paragraph onto the ruler pasteboard, as NSRulerPboardType, and expands the selection to paragraph boundaries.

- (void)copyRuler:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – copy:
• – copyFont:
• – cut:
• – paste:

Declared In

NSText.h

cut:

This action method deletes the selected text and places it onto the general pasteboard, in as many formats as the receiver supports.

- (void)cut:(id)sender

Discussion

A plain text object uses NSStringPboardType for plain text, and a rich text object also uses NSRTFPboardType.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – delete:
• – copy:
• – copyFont:
• – copyRuler:
• – paste:

Declared In

NSText.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver’s delegate, or nil if it has none.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDelegate:

Declared In

NSText.h

delete:

This action method deletes the selected text.

- (void)delete:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cut:

Declared In

NSText.h

drawsBackground

Returns a Boolean value that indicates whether the receiver draws its background.

- (BOOL)drawsBackground

Return Value

YES if the receiver draws its background, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – backgroundColor
• – setDrawsBackground:

Declared In

NSText.h

font

Returns the font of the first character in the receiver’s text, or of the insertion point if there’s no text.

- (NSFont *)font

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setFont:
• – setFont:range:

Declared In

NSText.h

importsGraphics

Returns a Boolean value that indicates whether the receiver allows the user to import files by dragging.

- (BOOL)importsGraphics

Return Value

YES if the receiver allows the user to import files by dragging, otherwise NO.

Discussion

A text object that accepts dragged files is also a rich text object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isRichText
• – setImportsGraphics:

Declared In

NSText.h

isEditable

Returns a Boolean value that indicates whether the receiver allows the user to edit text, NO if it doesn’t.

- (BOOL)isEditable

Return Value

YES if the receiver allows the user to edit text, otherwise NO.

Discussion

You can change the receiver’s text programmatically regardless of this setting.

If the receiver is editable, it’s also selectable.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isSelectable
• – setEditable:

Declared In

NSText.h

isFieldEditor

Returns a Boolean value that indicates whether the receiver interprets Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder.

- (BOOL)isFieldEditor

Return Value

YES if the receiver interprets Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder; NO if it accepts them as text input.

Discussion

See the NSWindow class specification for more information on field editors. By default, NSText objects don’t behave as field editors.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setFieldEditor:

Declared In

NSText.h

isHorizontallyResizable

Returns YES if the receiver automatically changes its width to accommodate the width of its text, NO if it doesn’t.

- (BOOL)isHorizontallyResizable

Discussion

By default, an NSText object is not horizontally resizable.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isVerticallyResizable
• – setHorizontallyResizable:

Declared In

NSText.h

isRichText

Returns a Boolean value that indicates whether the receiver allows the user to apply attributes to specific ranges of the text.

- (BOOL)isRichText

Return Value

YES if the receiver allows the user to apply attributes to specific ranges of the text, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – importsGraphics
• – setRichText:

Declared In

NSText.h

isRulerVisible

Returns a Boolean value that indicates whether the receiver’s enclosing scroll view shows its ruler.

- (BOOL)isRulerVisible

Return Value

YES if the receiver’s enclosing scroll view shows its ruler, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – toggleRuler:

Declared In

NSText.h

isSelectable

Returns a Boolean value that indicates whether the receiver allows the user to select text, NO if it doesn’t.

- (BOOL)isSelectable

Return Value

YES if the receiver allows the user to select text, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isEditable
• – setSelectable:

Declared In

NSText.h

isVerticallyResizable

Returns YES if the receiver automatically changes its height to accommodate the height of its text, NO if it doesn’t.

- (BOOL)isVerticallyResizable

Discussion

By default, an NSText object is vertically resizable.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isHorizontallyResizable
• – setVerticallyResizable:

Declared In

NSText.h

maxSize

Returns the receiver’s maximum size.

- (NSSize)maxSize

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – minSize
• – setMaxSize:

Declared In

NSText.h

minSize

Returns the receiver’s minimum size.

- (NSSize)minSize

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – maxSize
• – setMinSize:

Declared In

NSText.h

paste:

This action method pastes text from the general pasteboard at the insertion point or over the selection.

- (void)paste:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – copy:
• – cut:
• – pasteFont:
• – pasteRuler:

Declared In

NSText.h

pasteFont:

This action method pastes font information from the font pasteboard onto the selected text or insertion point of a rich text object, or over all text of a plain text object.

- (void)pasteFont:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – copyFont:
• – pasteRuler:

Declared In

NSText.h

pasteRuler:

This action method pastes paragraph style information from the ruler pasteboard onto the selected paragraphs of a rich text object.

- (void)pasteRuler:(id)sender

Discussion

It doesn’t apply to a plain text object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – copyFont:
• – pasteRuler:

Declared In

NSText.h

readRTFDFromFile:

Attempts to read the RTFD file at path, returning YES if successful and NO if not.

- (BOOL)readRTFDFromFile:(NSString *)path

Discussion

path should be the path for an .rtf file or an .rtfd file wrapper, not for the RTF file within an .rtfd file wrapper.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – writeRTFDToFile:atomically:

Declared In

NSText.h

replaceCharactersInRange:withRTF:

Replaces the characters in the given range with RTF text interpreted from the given RTF data.

- (void)replaceCharactersInRange:(NSRange)aRange withRTF:(NSData *)rtfData

Parameters

aRange

The range of characters to be replaced.

rtfData

The RTF data from which to derive the replacement string.

Discussion

This method applies only to rich text objects.

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

This method is designed for transferring text from out-of-process sources such as the pasteboard. In most cases, programmatic modification of the text is best done by operating on the text storage directly, using the general methods of NSMutableAttributedString.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – replaceCharactersInRange:withRTFD:
• – replaceCharactersInRange:withString:

Declared In

NSText.h

replaceCharactersInRange:withRTFD:

Replaces the characters in the given range with RTFD text interpreted from the given RTFD data.

- (void)replaceCharactersInRange:(NSRange)aRange withRTFD:(NSData *)rtfdData

Parameters

aRange

The range of characters to be replaced.

rtfdData

The RTFD data from which to derive the replacement string.

Discussion

This method applies only to rich text objects.

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

This method is designed for transferring text from out-of-process sources such as the pasteboard. In most cases, programmatic modification of the text is best done by operating on the text storage directly, using the general methods of NSMutableAttributedString.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – replaceCharactersInRange:withRTF:
• – replaceCharactersInRange:withString:

Declared In

NSText.h

replaceCharactersInRange:withString:

Replaces the characters in the given range with those in the given string.

- (void)replaceCharactersInRange:(NSRange)aRange withString:(NSString *)aString

Parameters

aRange

The range of characters to be replaced.

aString

The replacement string.

Discussion

For a rich text object, the text of aString is assigned the formatting attributes of the first character of the text it replaces, or of the character immediately before aRange if the range’s length is 0. If the range’s location is 0, the formatting attributes of the first character in the receiver are used.

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

In most cases, programmatic modification of the text is best done by operating on the text storage directly, using the general methods of NSMutableAttributedString.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – replaceCharactersInRange:withRTF:
• – replaceCharactersInRange:withRTFD:

Declared In

NSText.h

RTFDFromRange:

Returns an NSData object that contains an RTFD stream corresponding to the characters and attributes within aRange.

- (NSData *)RTFDFromRange:(NSRange)aRange

Discussion

Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters.

When writing data to the pasteboard, you can use the NSData object as the first argument to NSPasteboard's setData:forType: method, with a second argument of NSRTFDPboardType.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – RTFFromRange:

Declared In

NSText.h

RTFFromRange:

Returns an NSData object that contains an RTF stream corresponding to the characters and attributes within aRange, omitting any attachment characters and attributes.

- (NSData *)RTFFromRange:(NSRange)aRange

Discussion

Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters.

When writing data to the pasteboard, you can use the NSData object as the first argument to NSPasteboard's setData:forType: method, with a second argument of NSRTFPboardType.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – RTFDFromRange:

Declared In

NSText.h

scrollRangeToVisible:

Scrolls the receiver in its enclosing scroll view so the first characters of aRange are visible.

- (void)scrollRangeToVisible:(NSRange)aRange

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSText.h

selectAll:

This action method selects all of the receiver’s text.

- (void)selectAll:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSText.h

selectedRange

Returns the range of selected characters.

- (NSRange)selectedRange

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setSelectedRange:

Declared In

NSText.h

setAlignment:

Sets the alignment of all the receiver’s text to mode.

- (void)setAlignment:(NSTextAlignment)mode

Discussion

The value of mode must be one of the alignments described in NSTextAlignment.

Text using NSNaturalTextAlignment is actually displayed using one of the other alignments, depending on the natural alignment of the text’s script.

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – alignment
• – alignLeft:
• – alignCenter:
• – alignRight:

Declared In

NSText.h

setBackgroundColor:

Sets the receiver’s background color to a given color.

- (void)setBackgroundColor:(NSColor *)aColor

Parameters

aColor

The background color for the receiver.

Discussion

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDrawsBackground:
• – backgroundColor

Declared In

NSText.h

setBaseWritingDirection:

Sets the initial writing direction used to determine the actual writing direction for text.

- (void)setBaseWritingDirection:(NSWritingDirection)writingDirection

Discussion

If you know the base writing direction of the text you are rendering, you can use this method to specify that direction to the text system.

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – baseWritingDirection

Declared In

NSText.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject

Parameters

anObject

The delegate for the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – delegate

Declared In

NSText.h

setDrawsBackground:

Controls whether the receiver draws its background.

- (void)setDrawsBackground:(BOOL)flag

Parameters

flag

If flag is YES, the receiver fills its background with the background color, if flag is NO, it doesn’t.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setBackgroundColor:
• – drawsBackground

Declared In

NSText.h

setEditable:

Controls whether the receiver allows the user to edit its text.

- (void)setEditable:(BOOL)flag

Parameters

flag

If flag is YES, the receiver allows the user to edit text and attributes; if flag is NO, it doesn’t.

Discussion

You can change the receiver’s text programmatically regardless of this setting. If the receiver is made editable, it’s also made selectable. NSText objects are by default editable.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setSelectable:
• – isEditable

Declared In

NSText.h

setFieldEditor:

Controls whether the receiver interprets Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder.

- (void)setFieldEditor:(BOOL)flag

Parameters

flag

If flag is YES, the receiver interprets Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder; if flag is NO, it doesn’t, instead accepting these characters as text input.

Discussion

See the NSWindow class specification for more information on field editors. By default, NSText objects don’t behave as field editors.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isFieldEditor

Declared In

NSText.h

setFont:

Sets the font of all the receiver’s text to aFont.

- (void)setFont:(NSFont *)aFont

Discussion

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setFont:range:
• – font

Declared In

NSText.h

setFont:range:

Sets the font of characters within aRange to aFont.

- (void)setFont:(NSFont *)aFont range:(NSRange)aRange

Discussion

This method applies only to a rich text object.

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges:replacementStrings: or shouldChangeTextInRange:replacementString: to include this method in an undoable action.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setFont:
• – font

Declared In

NSText.h

setHorizontallyResizable:

Controls whether the receiver changes its width to fit the width of its text.

- (void)setHorizontallyResizable:(BOOL)fl