- Inherits from:
- NSView : NSResponder : NSObject
- Conforms to:
- NSChangeSpelling
- NSIgnoreMisspelledWords
- NSCoding (NSResponder)
- NSObject (NSObject)
Declared in:
- AppKit/NSText.h
NSText declares the most general programmatic interface for objects that manage text. You usually use instances of its subclass, NSTextView.
- 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. |
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 initialization method 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.
The text classes are unlike most other classes in the Application Kit in the richness and complexity of their interface. One of their design goals is to provide a comprehensive set of text-handling features so that you'll rarely need to create a subclass. Among other things, a text object can:
Graphical user-interface building tools (such as Interface Builder) may give you access to text objects in several different configurations, such as those found in the NSTextField, NSForm, and NSScrollView objects. These classes configure a text object for their own specific purposes. Additionally, all NSTextFields, NSForms, NSButtons within the same window-in short, all objects that access a text object through associated cells-share the same text object, reducing the memory demands of an application. Thus, it's generally best to use one of these classes whenever it meets your needs, rather than create text objects yourself. If one of these classes doesn't provide enough flexibility for your purposes, you can create text objects programmatically.
Text objects typically work closely with various other objects. Some of these-such as the delegate or an embedded graphic object-require a degree of programming on your part. Others-such as the Font Panel, spell checker, or ruler-take no effort other than deciding whether the service should be enabled or disabled. Several of the following sections discuss these interrelationships.
Text objects are differentiated into two groups: those that allow only one set of text attributes for all of their text, and those that allow multiple fonts, sizes, indents, and other attributes for different sets of characters and paragraphs. Text objects in the former group are called plain text objects, while those in the latter are called rich text objects. You can control whether a text object is plain or rich using the setRichText: method. Rich text objects are also capable of allowing the user to drag images and files into them. This behavior is controlled by the setImportsGraphics: method.
A rich NSText object can use RTF (Rich Text Format) as an interchange format. Not all RTF control words are supported: On input, an NSText object ignores any control word it doesn't recognize; some of those it can read and interpret it doesn't write out. The table below lists the RTF control words that any text object recognizes. Subclasses may recognize more.
Control Word | Read | Write |
\ansi |
yes | yes |
\b |
yes | yes |
\cb |
yes | yes |
\cf |
yes | yes |
\colortbl |
yes | yes |
\dnn |
yes | yes |
\fin |
yes | yes |
\fn |
yes | yes |
\fonttbl |
yes | yes |
\fsn |
yes | yes |
\i |
yes | yes |
\lin |
yes | yes |
\margrn |
yes | yes |
\paperwn |
yes | yes |
\mac |
yes | no |
\margln |
yes | yes |
\par |
yes | yes |
\pard |
yes | no |
\pca |
yes | no |
\qc |
yes | yes |
\ql |
yes | yes |
\qr |
yes | yes |
\sn |
yes | no |
\tab |
yes | yes |
\upn |
yes | yes |
Many of an NSText object's actions can be controlled through an associated object, the NSText object's delegate. The delegate can be any object you choose, and one delegate can control multiple NSText objects. If it implements any of the following methods, the delegate receives the corresponding message at the appropriate time:
Of special note are the two "textShould..."
methods. These methods are requests for permission. Any time a text
object begins an operation that would change its text or attributes,
it uses textShouldBeginEditing: to
request approval for the change. The delegate can return YES
to
permit the change, or NO
to forbid
it. Similarly, textShouldEndEditing: enables
the delegate to prevent a text object from ending editing, such
as when it contains an invalid value.
A rich text object may allow graphics or other file attachments to be embedded in the text. Each graphic is treated as a single (possibly large) "character": The text's line height and character placement are adjusted to accommodate the graphic. Graphics are embedded in the text in either of two ways: programmatically or directly through user actions. In the programmatic approach, graphic objects can be added using replaceRange:WithRTFD:, or through a more specific method defined by a subclass.
An alternate means of adding an image or other attachment to the text is for the user to drag an image or other file directly into the text object. The text object automatically creates an attachment object to manage the display of the image. This feature requires a rich text object that has been configured to receive dragged images using the setImportsGraphics: method.
Images that have been imported can be written as part of an
RTFD document. RTFD documents use a file package, or directory,
to store the components of the document (the "D" stands for
"directory"). The file package has the name of the document
plus an .rtfd
extension.
The file package always contains a file called TXT.rtf
for
the text of the document, and one or more TIFF or EPS files for
the images, plus the files for other attachments. A text object
can transfer information in an RTFD document to a file and read
it from a file using the writeRTFDToFile:atomically: and readRTFDFromFile: methods.
Text objects are designed to work with the Application Kit's font conversion system, defined by the NSFontPanel and NSFontManager classes. By default, a text object keeps the Font Panel updated with the first font in its selection, or of its typing attributes (defined below). It also changes the font in response to messages from the Font Panel and Font menu. Such changes apply to the selected text or typing attributes for a rich text object, or to all the text in a plain text object. You can turn this behavior off using the setUsesFontPanel: method. Doing so is recommended for a text object that serves as a field editor, for example.
Text objects also provide for a ruler, by which the user can edit paragraph attributes such as indents and tabs. NSTextView works with the NSRulerView class and uses the NSTextStorage and NSParagraphStyle classes to handle paragraph attributes. To show or hide a text object's ruler, use the toggleRuler: action method. Similar to the Font Panel, NSTextView can be set not to use a ruler with the setUsesRuler: method.
These constants specify text alignment:
Constants | Description |
NSLeftTextAlignment |
Description forthcoming. |
NSRightTextAlignment |
Description forthcoming. |
NSCenterTextAlignment |
Description forthcoming. |
NSJustifiedTextAlignment |
Description forthcoming. |
NSNaturalTextAlignment |
Use the natural alignment of the text's script |
These constants specify the movement between fields. They are used by NSTextDidEndEditingNotification.
Constants | Description |
NSIllegalTextMovement |
Description forthcoming. |
NSReturnTextMovement |
Description forthcoming. |
NSTabTextMovement |
Description forthcoming. |
NSBacktabTextMovement |
Description forthcoming. |
NSLeftTextMovement |
Description forthcoming. |
NSRightTextMovement |
Description forthcoming. |
NSUpTextMovement |
Description forthcoming. |
NSDownTextMovement |
Description forthcoming. |
These constants specify several commonly-used Unicode characters.
Constants | Description |
NSParagraphSeparatorCharacter |
Description forthcoming. |
NSLineSeparatorCharacter |
Description forthcoming. |
NSTabCharacter |
Description forthcoming. |
NSFormFeedCharacter |
Description forthcoming. |
NSNewlineCharacter |
Description forthcoming. |
NSCarriageReturnCharacter |
Description forthcoming. |
NSEnterCharacter |
Description forthcoming. |
NSBackspaceCharacter |
Description forthcoming. |
NSDeleteCharacter |
Description forthcoming. |
NSChangeSpelling
- - changeSpelling:
NSIgnoreMisspelledWords
- - ignoreSpelling:
- Getting the characters
- - string
- Setting graphic 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
- Setting super- and subscripting
- - superscript:
- - subscript:
- - unscript:
- Underlining text
- - underline:
- Reading and writing RTF
- - 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
- (void)alignCenter:(id)sender
See Also: - alignLeft:, - alignRight:, - alignment, - setAlignment:
- (void)alignLeft:(id)sender
See Also: - alignCenter:, - alignRight:, - alignment, - setAlignment:
- (void)alignRight:(id)sender
See Also: - alignLeft:, - alignCenter:, - alignment, - setAlignment:
- (NSTextAlignment)alignment
Text using NSNaturalTextAlignment
is
actually displayed using one of the other alignments, depending
on the natural alignment of the text's script.
- (NSColor *)backgroundColor
See Also: - drawsBackground, - setBackgroundColor:
- (void)changeFont:(id)sender
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.
See Also: - usesFontPanel
- (void)checkSpelling:(id)sender
See Also: - showGuessPanel:
- (void)copy:(id)sender
NSStringPboardType
for
plain text, and a rich text object also uses NSRTFPboardType
.See Also: - copyFont:, - copyRuler:, - cut:, - paste:
- (void)copyFont:(id)sender
NSFontPboardType
.See Also: - copy:, - copyRuler:, - cut:, - paste:
- (void)copyRuler:(id)sender
NSRulerPboardType
,
and expands the selection to paragraph boundaries.See Also: - copy:, - copyFont:, - cut:, - paste:
- (void)cut:(id)sender
NSStringPboardType
for
plain text, and a rich text object also uses NSRTFPboardType
.See Also: - delete:, - copy:, - copyFont:, - copyRuler:, - paste:
- (id)delegate
nil
if it has none.See Also: - setDelegate:
- (void)delete:(id)sender
See Also: - cut:
- (BOOL)drawsBackground
YES
if
the receiver draws its background, NO
if
it doesn't.See Also: - backgroundColor, - setDrawsBackground:
- (NSFont *)font
See Also: - setFont:, - setFont:range:
- (BOOL)importsGraphics
YES
if
the receiver allows the user to import files by dragging, NO
if
it doesn't. A text object that accepts dragged
files is also a rich text object.See Also: - isRichText, - setImportsGraphics:
- (BOOL)isEditable
YES
if
the receiver allows the user to edit text, NO
if
it doesn't. You can change the receiver's text
programmatically regardless of this setting.If the receiver is editable, it's also selectable.
See Also: - isSelectable, - setEditable:
- (BOOL)isFieldEditor
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. See the NSWindow
class specification for more information on field editors. By default,
NSText objects don't behave as field editors.See Also: - setFieldEditor:
- (BOOL)isHorizontallyResizable
YES
if
the receiver automatically changes its width to accommodate the
width of its text, NO
if it doesn't.See Also: - isVerticallyResizable, - setHorizontallyResizable:
- (BOOL)isRichText
YES
if
the receiver allows the user to apply attributes to specific ranges
of the text, NO
if it doesn't.See Also: - importsGraphics, - setRichText:
- (BOOL)isRulerVisible
YES
if
the receiver's enclosing scroll view shows its ruler, NO
otherwise.See Also: - toggleRuler:
- (BOOL)isSelectable
YES
if
the receiver allows the user to select text, NO
if
it doesn't.See Also: - isEditable, - setSelectable:
- (BOOL)isVerticallyResizable
YES
if
the receiver automatically changes its height to accommodate the
height of its text, NO
if it doesn't.See Also: - isHorizontallyResizable, - setVerticallyResizable:
- (NSSize)maxSize
See Also: - minSize, - setMaxSize:
- (NSSize)minSize
See Also: - maxSize, - setMinSize:
- (void)paste:(id)sender
See Also: - copy:, - cut:, - pasteFont:, - pasteRuler:
- (void)pasteFont:(id)sender
See Also: - copyFont:, - pasteRuler:
- (void)pasteRuler:(id)sender
See Also: - copyFont:, - pasteRuler:
- (BOOL)readRTFDFromFile:(NSString
*)path
YES
if
successful and NO
if not. path should
be the path for an .rtf
file
or an .rtfd
file wrapper,
not for the RTF file within an .rtfd
file
wrapperSee Also: - writeRTFDToFile:atomically:
- (void)replaceCharactersInRange:(NSRange)aRange
withString:(NSString *)aString
See Also: - replaceCharactersInRange:withRTF:, - replaceCharactersInRange:withRTFD:
- (void)replaceCharactersInRange:(NSRange)aRange
withRTF:(NSData *)rtfData
See Also: - replaceCharactersInRange:withRTFD:, - replaceCharactersInRange:withString:
- (void)replaceCharactersInRange:(NSRange)aRange
withRTFD:(NSData *)rtfdData
See Also: - replaceCharactersInRange:withRTF:, - replaceCharactersInRange:withString:
- (NSData *)RTFDFromRange:(NSRange)aRange
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
.
See Also: - RTFFromRange:
public NSData RTFFromRange(NSRange aRange)
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
.
See Also: - RTFDFromRange:
- (void)scrollRangeToVisible:(NSRange)aRange
- (void)selectAll:(id)sender
- (NSRange)selectedRange
See Also: - setSelectedRange:
- (void)setAlignment:(NSTextAlignment)mode
Text using NSNaturalTextAlignment
is
actually displayed using one of the other alignments, depending
on the natural alignment of the text's script.
See Also: - alignment, - alignLeft:, - alignCenter:, - alignRight:
- (void)setBackgroundColor:(NSColor
*)aColor
See Also: - setDrawsBackground:, - backgroundColor
- (void)setDelegate:(id)anObject
See Also: - delegate
- (void)setDrawsBackground:(BOOL)flag
YES
,
the receiver fills its background with the background color; if flag is NO
,
it doesn't.See Also: - setBackgroundColor:, - drawsBackground
- (void)setEditable:(BOOL)flag
YES
,
the receiver allows the user to edit text and attributes; if flag is NO
,
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.See Also: - setSelectable:, - isEditable
- (void)setFieldEditor:(BOOL)flag
YES
,
it does; if flag is NO
,
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.See Also: - isFieldEditor
- (void)setFont:(NSFont
*)aFont
See Also: - setFont:range:, - font
- (void)setFont:(NSFont
*)aFont
range:(NSRange)aRange
See Also: - setFont:, - font
- (void)setHorizontallyResizable:(BOOL)flag
YES
it
does; if flag is NO
it
doesn't.See Also: - setVerticallyResizable:, - isHorizontallyResizable
- (void)setImportsGraphics:(BOOL)flag
YES
,
it does; if flag is NO
,
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.See Also: - setRichText:, - importsGraphics
- (void)setMaxSize:(NSSize)aSize
See Also: - setMinSize:, - maxSize
- (void)setMinSize:(NSSize)aSize
See Also: - setMaxSize:, - minSize
- (void)setRichText:(BOOL)flag
YES
it
does; if flag is NO
it
doesn't. If flag is NO
,
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.See Also: - isRichText, - setImportsGraphics:
- (void)setSelectable:(BOOL)flag
YES
,
the receiver allows the user to select text; if flag is NO
,
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.See Also: - setEditable:, - isSelectable
- (void)setSelectedRange:(NSRange)aRange
See Also: - selectedRange
- (void)setString:(NSString
*)aString
- (void)setTextColor:(NSColor
*)aColor
nil
.See Also: - setTextColor:range:, - textColor
- (void)setTextColor:(NSColor
*)aColor
range:(NSRange)aRange
nil
.
This method applies only to rich text objects.See Also: - setTextColor:, - textColor
- (void)setUsesFontPanel:(BOOL)flag
YES
,
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 NO
the
receiver doesn't do any of this. By default, an NSText object
uses the Font Panel and menu.See Also: - usesFontPanel
- (void)setVerticallyResizable:(BOOL)flag
YES
it
does; if flag is NO
it
doesn't.See Also: - setHorizontallyResizable:, - isVerticallyResizable
- (void)showGuessPanel:(id)sender
See Also: - checkSpelling:
- (void)sizeToFit
See Also: - isHorizontallyResizable, - isVerticallyResizable
- (NSString *)string
See Also: - setString:
- (void)subscript:(id)sender
See Also: - subscript:, - unscript:, - lowerBaseline: (NSTextView)
- (void)superscript:(id)sender
See Also: - subscript:, - unscript:, - raiseBaseline: (NSTextView)
- (NSColor *)textColor
See Also: - setTextColor:, - setTextColor:range:
- (void)toggleRuler:(id)sender
- (void)underline:(id)sender
- (void)unscript:(id)sender
See Also: - subscript:, - superscript:, - raiseBaseline: (NSTextView), - lowerBaseline: (NSTextView)
- (BOOL)usesFontPanel
YES
if
the receiver uses the Font Panel, NO
otherwise.See Also: - setUsesFontPanel:
- (BOOL)writeRTFDToFile:(NSString
*)path
atomically:(BOOL)atomicFlag
YES
on success
and NO
on failure. If atomicFlag is YES
,
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.See Also: - RTFFromRange:, - RTFDFromRange:, - readRTFDFromFile:
- (void)textDidBeginEditing:(NSNotification
*)aNotification
- (void)textDidChange:(NSNotification
*)aNotification
- (void)textDidEndEditing:(NSNotification
*)aNotification
- (BOOL)textShouldBeginEditing:(NSText
*)aTextObject
YES
,
the text object proceeds to make changes. If the delegate returns NO
,
the text object abandons the editing operation. This method is invoked
whenever aTextObject attempts to
become first responder.See Also: - makeFirstResponder: (NSWindow), - becomeFirstResponder (NSResponder)
- (BOOL)textShouldEndEditing:(NSText
*)aTextObject
YES
,
the text object proceeds to finish editing and resign first responder
status. If the delegate returns NO
,
the text object selects all of its text and remains the first responder.See Also: - resignFirstResponder (NSResponder)