Next Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

NSText

Inherits from	NSView : NSResponder : NSObject
Implements	NSChangeSpelling NSIgnoreMisspelledWords NSCoding (NSResponder)
Package	com.apple.cocoa.application
Companion guide	Text System Overview

Class at a Glance

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

Commonly Used Methods

readRTFDFromFile: Reads an .rtf or .rtfd file.
writeRTFDToFile: 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

The NSText class declares the most general programmatic interface to objects that manage text. Cocoa offers a subclass of NSText, NSTextView, that extends the interface declared by NSText and provides much more sophisticated functionality than that declared in NSText.

NSText’s constructor 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.

Interfaces Implemented

NSChangeSpelling

changeSpelling

NSIgnoreMisspelledWords

ignoreSpelling

Tasks

Constructors

Getting the Characters

Setting Graphics Attributes

Setting Behavioral Attributes

Using the Font Panel and Menu

Using the Ruler

Changing the Selection

Replacing Text

Action Methods for Editing

Changing the Font

Setting Text Alignment

Setting Text Color

Setting Superscripting and Subscripting

Underlining Text

Reading and Writing RTF Files

Checking Spelling

Constraining Size

Scrolling

Setting the Delegate

Editing text

Changing text formatting

Constructors

NSText

Creates an NSText with a zero-sized frame rectangle.

public NSText()

Creates a text object with frameRect as its frame rectangle.

public NSText(NSRect frameRect)

Discussion

This method actually substitutes an instance of a concrete subclass of NSText, such as NSTextView, and configures that instance to archive itself.

Instance Methods

alignCenter

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

public void alignCenter(Object sender)

alignLeft

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

public void alignLeft(Object sender)

alignment

Returns the alignment of the first selected paragraph, or of all text for a plain text object.

public int alignment()

Discussion

This value is one of the alignments described in “Constants.”

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

alignRight

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

public void alignRight(Object sender)

backgroundColor

Returns the receiver’s background color.

public NSColor backgroundColor()

changeFont

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

public void changeFont(Object 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.

changeSpelling

Replaces the selected word in the receiver with a corrected version from the Spelling panel.

public void changeSpelling(Object sender)

Discussion

This message is sent by the NSSpellChecker to the object whose text is being checked. To get the corrected spelling, ask sender for the string value of its selected cell (visible to the user as the text field in the Spelling panel). This method should replace the selected portion of the text with the string that it gets from the NSSpellChecker.

checkSpelling

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

public void checkSpelling(Object 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.

copy

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

public void copy(Object sender)

Discussion

A plain text object uses NSPasteboard.StringPboardType for plain text, and a rich text object also uses NSPasteboard.RTFPboardType.

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 NSPasteboard.FontPboardType.

public void copyFont(Object sender)

copyRuler

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

public void copyRuler(Object sender)

cut

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

public void cut(Object sender)

Discussion

A plain text object uses NSPasteboard.StringPboardType for plain text, and a rich text object also uses NSPasteboard.RTFPboardType.

delegate

Returns the receiver’s delegate, or null if it has none.

public Object delegate()

delete

This action method deletes the selected text.

public void delete(Object sender)

drawsBackground

Returns true if the receiver draws its background, false if it doesn’t.

public boolean drawsBackground()

font

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

public NSFont font()

ignoreSpelling

This action method informs the receiver to ignore misspelled words on a document-by-document basis. This method is sent by the NSSpellChecker instance.

public void ignoreSpelling(Object sender)

importsGraphics

Returns true if the receiver allows the user to import files by dragging, false if it doesn’t.

public boolean importsGraphics()

Discussion

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

isEditable

Returns true if the receiver allows the user to edit text, false if it doesn’t.

public boolean isEditable()

Discussion

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

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

isFieldEditor

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

public boolean isFieldEditor()

Discussion

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

isHorizontallyResizable

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

public boolean isHorizontallyResizable()

Discussion

By default, an NSText object is not horizontally resizable.

isRichText

Returns true if the receiver allows the user to apply attributes to specific ranges of the text, false if it doesn’t.

public boolean isRichText()

isRulerVisible

Returns true if the receiver’s enclosing scroll view shows its ruler, false otherwise.

public boolean isRulerVisible()

isSelectable

Returns true if the receiver allows the user to select text, false if it doesn’t.

public boolean isSelectable()

isVerticallyResizable

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

public boolean isVerticallyResizable()

Discussion

By default, an NSText object is vertically resizable.

maxSize

Returns the receiver’s maximum size.

public NSSize maxSize()

minSize

Returns the receiver’s minimum size.

public NSSize minSize()

paste

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

public void paste(Object sender)

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.

public void pasteFont(Object sender)

pasteRuler

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

public void pasteRuler(Object sender)

Discussion

It doesn’t apply to a plain text object.

readRTFDFromFile

Attempts to read the RTFD file at path, returning true if successful and false if not.

public boolean readRTFDFromFile(String 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.

replaceCharactersInRange

Replaces the characters in aRange with aString.

public void replaceCharactersInRange(NSRange aRange, String aString)

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 or shouldChangeTextInRange to include this method in an undoable action.

replaceCharactersInRangeWithRTF

Replaces the characters in aRange with RTF text interpreted from rtfData.

public void replaceCharactersInRangeWithRTF(NSRange aRange, NSData rtfData)

Discussion

This method applies only to rich text objects.

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

replaceCharactersInRangeWithRTFD

Replaces the characters in aRange with RTFD text interpreted from rtfdData.

public void replaceCharactersInRangeWithRTFD(NSRange aRange, NSData rtfdData)

Discussion

This method applies only to rich text objects.

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

RTFDFromRange

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

public NSData RTFDFromRange(NSRange aRange)

Discussion

Throws a RangeException 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 setDataForType method, with a second argument of NSPasteboard.RTFDPboardType.

RTFFromRange

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

public NSData RTFFromRange(NSRange aRange)

Discussion

Throws a RangeException 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 setDataForType method, with a second argument of NSPasteboard.RTFPboardType.

scrollRangeToVisible

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

public void scrollRangeToVisible(NSRange aRange)

selectAll

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

public void selectAll(Object sender)

selectedRange

Returns the range of selected characters.

public NSRange selectedRange()

setAlignment

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

public void setAlignment(int mode)

Discussion

mode may be one of the alignments described in “Constants.”

Text using NaturalTextAlignment 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 or shouldChangeTextInRange to include this method in an undoable action.

setBackgroundColor

Sets the receiver’s background color to aColor.

public void setBackgroundColor(NSColor aColor)

Discussion

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

setDelegate

Sets the receiver’s delegate to anObject, without retaining it.

public void setDelegate(Object anObject)

setDrawsBackground

Controls whether the receiver draws its background.

public void setDrawsBackground(boolean flag)

Discussion

If flag is true, the receiver fills its background with the background color; if flag is false, it doesn’t.

setEditable

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

public void setEditable(boolean flag)

Discussion

If flag is true, the receiver allows the user to edit text and attributes; if flag is false, it doesn’t. 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.

setFieldEditor

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

public void setFieldEditor(boolean flag)

Discussion

If flag is true, it does; if flag is false, it doesn’t, instead accepting these characters as text input. See the NSWindow class specification for more information on field editors. By default, NSText objects don’t behave as field editors.

setFont

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

public void setFont(NSFont aFont)

Discussion

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

setFontInRange

Sets the font of characters within aRange to aFont.

public void setFontInRange(NSFont aFont, 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 or shouldChangeTextInRange to include this method in an undoable action.

setHorizontallyResizable

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

public void setHorizontallyResizable(boolean flag)

Discussion

If flag is true it does; if flag is false it doesn’t.

setImportsGraphics

Controls whether the receiver allows the user to import files by dragging.

public void setImportsGraphics(boolean flag)

Discussion

If flag is true, it does; if flag is false, it doesn’t. If the receiver is set to accept dragged files, it’s also made a rich text object. Subclasses may or may not accept dragged files by default.

setMaxSize

Sets the receiver’s maximum size to aSize.

public void setMaxSize(NSSize aSize)

setMinSize

Sets the receiver’s minimum size to aSize.

public void setMinSize(NSSize aSize)

setRichText

Controls whether the receiver allows the user to apply attributes to specific ranges of the text.

public void setRichText(boolean flag)

Discussion

If flag is true it does; if flag is false it doesn’t. If flag is false, the receiver is also set not to accept dragged files. Subclasses may or may not let the user apply multiple attributes to the text and accept drag files by default.

setSelectable

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

public void setSelectable(boolean flag)

Discussion

If flag is true, the receiver allows the user to select text; if flag is false, it doesn’t. You can set selections programmatically regardless of this setting. If the receiver is made not selectable, it’s also made not editable. NSText objects are by default editable and selectable.

setSelectedRange

Selects the receiver’s characters within aRange.

public void setSelectedRange(NSRange aRange)

setString

Replaces the receiver’s entire text with aString, applying the formatting attributes of the old first character to its new contents.

public void setString(String aString)

Discussion

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

setTextColor

Sets the text color of all characters in the receiver to aColor.

public void setTextColor(NSColor aColor)

Discussion

Removes the text color attribute if aColor is null.

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

setTextColorInRange

Sets the text color of characters within aRange to aColor.

public void setTextColorInRange(NSColor aColor, NSRange aRange)

Discussion

Removes the text color attribute if aColor is null. This method applies only to rich text objects.

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

setUsesFontPanel

Controls whether the receiver uses the Font panel and Font menu.

public void setUsesFontPanel(boolean flag)

Discussion

If flag is true, the receiver responds to messages from the Font panel and from the Font menu and updates the Font panel with the selection font whenever it changes. If flag is false the receiver doesn’t do any of these actions. By default, an NSText object uses the Font panel and menu.

setVerticallyResizable

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

public void setVerticallyResizable(boolean flag)

Discussion

If flag is true it does; if flag is false it doesn’t.

showGuessPanel

This action method opens the Spelling panel, allowing the user to make a correction during spell checking.

public void showGuessPanel(Object sender)

sizeToFit

Resizes the receiver to fit its text.

public void sizeToFit()

Discussion

The text view will not be sized any smaller than its minimum size, however.

string

Returns the characters of the receiver’s text.

public String string()

Discussion

For performance reasons, this method returns the current backing store of the text object. If you want to maintain a snapshot of this as you manipulate the text storage, you should make a copy of the appropriate substring.

subscript

This action method applies a subscript attribute to selected text (or all text if the receiver is a plain text object), lowering its baseline offset by a predefined amount.

public void subscript(Object sender)

superscript

This action method applies a superscript attribute to selected text (or all text if the receiver is a plain text object), raising its baseline offset by a predefined amount.

public void superscript(Object sender)

textColor

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

public NSColor textColor()

toggleRuler

This action method shows or hides the ruler, if the receiver is enclosed in a scroll view.

public void toggleRuler(Object sender)

underline

This action method underlines selected text for a rich text object, or all text for a plain text object.

public void underline(Object sender)

unscript

This action method removes any superscripting or subscripting from selected text (or all text if the receiver is a plain text object).

public void unscript(Object sender)

usesFontPanel

Returns true if the receiver uses the Font panel, false otherwise.

public boolean usesFontPanel()

writeRTFDToFile

Writes the receiver’s text as RTF with attachments to a file or directory at path.

public boolean writeRTFDToFile(String path, boolean atomicFlag)

Discussion

Returns true on success and false on failure. If atomicFlag is true, attempts to write the file safely so that an existing file at path is not overwritten, nor does a new file at path actually get created, unless the write is successful.

Constants

These constants specify text alignment:

Constant	Description
`LeftTextAlignment`	Text is visually left aligned.
`RightTextAlignment`	Text is visually right aligned.
`CenterTextAlignment`	Text is visually center aligned.
`JustifiedTextAlignment`	Text is justified.
`NaturalTextAlignment`	Use the natural alignment of the text’s script.

These constants specify the reason for a change of editing focus among text fields, in essence answering the question “why am I leaving the field?” They are the possible values for the TextMovement key of the TextDidEndEditingNotification userInfo dictionary. The field editor makes sure that these are the values sent when the user presses the Tab, Backtab, or Return key while editing. The control then uses this information to decide where to send focus next.

Constant	Description
`IllegalTextMovement`	Currently unused.
`ReturnTextMovement`	The Return key was pressed.
`TabTextMovement`	The Tab key was pressed.
`BacktabTextMovement`	The Backtab (Shift-Tab) key was pressed.
`LeftTextMovement`	The left arrow key was pressed.
`RightTextMovement`	The right arrow key was pressed.
`UpTextMovement`	The up arrow key was pressed.
`DownTextMovement`	The down arrow key was pressed.
`CancelTextMovement`	The user cancelled the completion.
`OtherTextMovement`	The user performed some undefined action.

These constants specify several commonly used Unicode characters.

Constant	Description
`ParagraphSeparatorCharacter`	The paragraph separator character: `0x2029`
`LineSeparatorCharacter`	The line separator character: `0x2028`
`TabCharacter`	The tab character: `0x0009`
`BackTabCharacter`	The back tab character: `0x0019`
`FormFeedCharacter`	The form feed character: `0x000c`
`NewlineCharacter`	The newline character: `0x000a`
`CarriageReturnCharacter`	The carriage return character: `0x000d`
`EnterCharacter`	The enter character: `0x0003`
`BackspaceCharacter`	The backspace character: `0x0008`
`DeleteCharacter`	The delete character: `0x007f`

Delegate Methods

textDidBeginEditing

Informs the delegate that the text object has begun editing (that the user has begun changing it).

public abstract void textDidBeginEditing(NSNotification aNotification)

Discussion

The name of aNotification is TextDidBeginEditingNotification.

textDidChange

Informs the delegate that the text object has changed its characters or formatting attributes.

public abstract void textDidChange(NSNotification aNotification)

Discussion

The name of aNotification is TextDidChangeNotification.

textDidEndEditing

Informs the delegate that the text object has finished editing (that it has resigned first responder status).

public abstract void textDidEndEditing(NSNotification aNotification)

Discussion

The name of aNotification is TextDidEndEditingNotification.

textShouldBeginEditing

Invoked from a text object’s implementation of becomeFirstResponder, this method requests permission for aTextObject to begin editing.

public abstract boolean textShouldBeginEditing(NSText aTextObject)

Discussion

If the delegate returns true, the text object proceeds to make changes. If the delegate returns false, the text object abandons the editing operation. This method is invoked whenever aTextObject attempts to become first responder. It is also invoked when the user drags and drops a file onto the text object.

textShouldEndEditing

Invoked from a text object’s implementation of resignFirstResponder, this method requests permission for aTextObject to end editing.

public abstract boolean textShouldEndEditing(NSText aTextObject)

Discussion

If the delegate returns true, the text object proceeds to finish editing and resign first responder status. If the delegate returns false, the text object selects all of its text and remains the first responder.

Notifications

TextDidBeginEditingNotification

Posted when an NSText object begins any operation that changes characters or formatting attributes.

The notification object is the notifying NSText object. This notification does not contain a userInfo dictionary.

TextDidChangeNotification

Posted after an NSText object performs any operation that changes characters or formatting attributes.

The notification object is the notifying NSText object. This notification does not contain a userInfo dictionary.

TextDidEndEditingNotification

Posted when an NSText object completes any operation that changes characters or formatting attributes.

The notification object is the notifying NSText object. The userInfo dictionary contains the following information:

Key	Value
`"NSTextMovement"`	Possible movement code values are described in “Constants.”

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Legacy Document

NSText

Class at a Glance

Commonly Used Methods

Overview

Interfaces Implemented

Tasks

Constructors

Getting the Characters

Setting Graphics Attributes

Setting Behavioral Attributes

Using the Font Panel and Menu

Using the Ruler

Changing the Selection

Replacing Text

Action Methods for Editing

Changing the Font

Setting Text Alignment

Setting Text Color

Setting Superscripting and Subscripting

Underlining Text

Reading and Writing RTF Files

Checking Spelling

Constraining Size

Scrolling

Setting the Delegate

Editing text

Changing text formatting

Constructors

NSText

Discussion

Instance Methods

alignCenter

See Also

alignLeft

See Also

alignment

Discussion

alignRight

See Also

backgroundColor

See Also

changeFont

Discussion

See Also

changeSpelling

Discussion

checkSpelling

Discussion

See Also

copy

Discussion

See Also

copyFont

See Also

copyRuler

See Also

cut

Discussion

See Also

delegate

See Also

delete

See Also

drawsBackground

See Also

font

See Also

ignoreSpelling

importsGraphics

Discussion

See Also

isEditable

Discussion

See Also

isFieldEditor

Discussion

See Also

isHorizontallyResizable

Discussion