Inherits from: NSView : NSResponder : NSObject
Implements: NSChangeSpelling NSIgnoreMisspelledWords
Package: com.apple.yellow.application
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. |
The NSText class declares the most general programmatic interface to objects that manage text. Mac OS X 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, depending on the platform. 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 true
to
permit the change, or false
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 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 |
LeftTextAlignment |
<<Description Forthcoming>> |
RightTextAlignment |
<<Description Forthcoming>> |
CenterTextAlignment |
<<Description Forthcoming>> |
JustifiedTextAlignment |
<<Description Forthcoming>> |
NaturalTextAlignment |
Use the natural alignment of the text's script |
These constants specify the movement between fields. They
are used by NSTextDidEndEditingNotification.
Constants | Description |
IllegalTextMovement |
<<Description Forthcoming>> |
ReturnTextMovement |
<<Description Forthcoming>> |
TabTextMovement |
<<Description Forthcoming>> |
BacktabTextMovement |
<<Description Forthcoming>> |
LeftTextMovement |
<<Description Forthcoming>> |
RightTextMovement |
<<Description Forthcoming>> |
UpTextMovement |
<<Description Forthcoming>> |
DownTextMovement |
<<Description Forthcoming>> |
These constants specify several commonly-used Unicode characters.
Constants | Description |
ParagraphSeparatorCharacter |
<<Description Forthcoming>> |
LineSeparatorCharacter |
<<Description Forthcoming>> |
TabCharacter |
<<Description Forthcoming>> |
FormFeedCharacter |
<<Description Forthcoming>> |
NewlineCharacter |
<<Description Forthcoming>> |
CarriageReturnCharacter |
<<Description Forthcoming>> |
EnterCharacter |
<<Description Forthcoming>> |
BackspaceCharacter |
<<Description Forthcoming>> |
DeleteCharacter |
- NSChangeSpelling
- - changeSpelling:
- NSIgnoreMisspelledWords
- - ignoreSpelling:
- Creating instances
- initWithFrame:
- 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
- replaceCharactersInRangeWithRTF
- replaceCharactersInRangeWithRTFD
- replaceCharactersInRange
- setString
- Action methods for editing
- selectAll
- copy
- cut
- paste
- copyFont
- pasteFont
- copyRuler
- pasteRuler
- delete
- Changing the font
- changeFont
- setFont
- setFontInRange
- font
- Setting text alignment
- setAlignment
- alignCenter
- alignLeft
- alignRight
- alignment
- Setting text color
- setTextColor
- setTextColorInRange
- textColor
- Setting super- and subscripting
- superscript
- subscript
- unscript
- Underlining text
- underline
- Reading and writing RTF
- readRTFDFromFile
- writeRTFDToFile
- RTFDFromRange
- RTFFromRange
- Checking spelling
- checkSpelling
- showGuessPanel
- Constraining size
- setMaxSize
- maxSize
- setMinSize
- minSize
- setVerticallyResizable
- isVerticallyResizable
- setHorizontallyResizable
- isHorizontallyResizable
- sizeToFit
- Scrolling
- scrollRangeToVisible
- Setting the delegate
- setDelegate
- delegate
public NSText(NSRect frameRect)
public void alignCenter(Object sender)
See Also: alignLeft, alignRight, alignment, setAlignment
public void alignLeft(Object sender)
See Also: alignCenter, alignRight, alignment, setAlignment
public void alignRight(Object sender)
See Also: alignLeft, alignCenter, alignment, setAlignment
public int alignment()
LeftTextAlignment
RightTextAlignment
CenterTextAlignment
JustifiedTextAlignment
NaturalTextAlignment
Text
using NaturalTextAlignment
is actually
displayed using one of the other alignements, depending on the natural
alignment of the text's script.
public NSColor backgroundColor()
See Also: drawsBackground, setBackgroundColor
public void changeSpelling(Object sender)
public void changeFont(Object sender)
This method changes the font by sending convertFont: messages to sender (which is presumed to be an NSFontManager or similarly capable object) and applying each NSFont returned to the appropriate text. If a rich text object's selection contains multiple fonts, convertFont: is invoked for each contiguous range of characters that share a font. See the NSFontManager class specification for more information on font conversion.
See Also: usesFontPanel
public void checkSpelling(Object sender)
See Also: showGuessPanel
public void copy(Object sender)
NSPasteboard.StringPboardType
for
plain text, and a rich text object also uses NSPasteboard.RTFPboardType
.See Also: copyFont, copyRuler, cut, paste
public void copyFont(Object sender)
See Also: copy, copyRuler, cut, paste
public void copyRuler(Object sender)
NSPasteboard.RulerPboardType
,
and expands the selection to paragraph boundaries.See Also: copy, copyFont, cut, paste
public void cut(Object sender)
NSPasteboard.StringPboardType
for
plain text, and a rich text object also uses NSPasteboard.RTFPboardType
.See Also: delete, copy, copyFont, copyRuler, paste
public Object delegate()
null
if it has none.See Also: setDelegate
public void delete(Object sender)
See Also: cut
public boolean drawsBackground()
true
if
the receiver draws its background, false
if
it doesn't.See Also: backgroundColor, setDrawsBackground
public NSFont font()
See Also: setFont, setFontInRange
public void ignoreSpelling(Object sender)
public boolean importsGraphics()
true
if
the receiver allows the user to import files by dragging, false
if
it doesn't. A text object that accepts dragged
files is also a rich text object.See Also: isRichText, setImportsGraphics
- (id)initWithFrame:(NSRect)frameRect
public boolean isEditable()
true
if
the receiver allows the user to edit text, false
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
public boolean isFieldEditor()
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. See the NSWindow
class specification for more information on field editors. By default,
NSText objects don't behave as field editors.See Also: setFieldEditor
public boolean isHorizontallyResizable()
true
if
the receiver automatically changes its width to accommodate the
width of its text, false
if it doesn't.See Also: isVerticallyResizable, setHorizontallyResizable
public boolean isRichText()
true
if
the receiver allows the user to apply attributes to specific ranges of
the text, false
if it doesn't.See Also: importsGraphics, setRichText
public boolean isRulerVisible()
true
if
the receiver's enclosing scroll view shows its ruler, false
otherwise.See Also: toggleRuler
public boolean isSelectable()
true
if
the receiver allows the user to select text, false
if
it doesn't.See Also: isEditable, setSelectable
public boolean isVerticallyResizable()
true
if
the receiver automatically changes its height to accommodate the
height of its text, false
if it doesn't.See Also: isHorizontallyResizable, setVerticallyResizable
public NSSize maxSize()
See Also: minSize, setMaxSize
public NSSize minSize()
See Also: maxSize, setMinSize
public void paste(Object sender)
See Also: copy, cut, pasteFont, pasteRuler
public void pasteFont(Object sender)
See Also: copyFont, pasteRuler
public void pasteRuler(Object sender)
See Also: copyFont, pasteRuler
public boolean readRTFDFromFile(String path)
true
if
successful and false
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
wrapper.See Also: writeRTFDToFile
public void replaceCharactersInRangeWithRTF(NSRange aRange, NSData rtfData)
See Also: replaceCharactersInRangeWithRTFD, replaceCharactersInRange
public void replaceCharactersInRangeWithRTFD(NSRange aRange, NSData rtfdData)
See Also: replaceCharactersInRangeWithRTF, replaceCharactersInRange
public void replaceCharactersInRange(NSRange aRange, String aString)
See Also: replaceCharactersInRangeWithRTF, replaceCharactersInRangeWithRTFD
public 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 NSPasteboard.RTFDPboardType
.
See Also: RTFFromRange
- (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 NSPasteboard.RTFPboardType
.
See Also: RTFDFromRange
public void scrollRangeToVisible(NSRange aRange)
public void selectAll(Object sender)
public NSRange selectedRange()
See Also: setSelectedRange
public void setAlignment(int mode)
NSPasteboard.LeftTextAlignment
NSPasteboard.RightTextAlignment
NSPasteboard.CenterTextAlignment
NSPasteboard.JustifiedTextAlignment
NSPasteboard.NaturalTextAlignment
Text
using NSPasteboard.NaturalTextAlignment
is
actually displayed using one of the other alignements, depending
on the natural alignment of the text's script.
See Also: alignment, alignLeft, alignCenter, alignRight
public void setBackgroundColor(NSColor aColor)
See Also: setDrawsBackground, backgroundColor
public void setDelegate(Object anObject)
See Also: delegate
public void setDrawsBackground(boolean flag)
true
,
the receiver fills its background with the background color; if flag is false
,
it doesn't.See Also: setBackgroundColor, drawsBackground
public void setEditable(boolean flag)
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.See Also: setSelectable, isEditable
public void setFieldEditor(boolean flag)
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.See Also: isFieldEditor
public void setFont(NSFont aFont)
See Also: setFontInRange, font
public void setFontInRange(NSFont aFont, NSRange aRange)
public void setHorizontallyResizable(boolean flag)
true
it
does; if flag is false
it
doesn't.See Also: setVerticallyResizable, isHorizontallyResizable
public void setImportsGraphics(boolean flag)
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.See Also: setRichText, importsGraphics
public void setMaxSize(NSSize aSize)
See Also: setMinSize, maxSize
public void setMinSize(NSSize aSize)
See Also: setMaxSize, minSize
public void setRichText(boolean flag)
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.See Also: isRichText, setImportsGraphics
public void setSelectable(boolean flag)
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.See Also: setEditable, isSelectable
public void setSelectedRange(NSRange aRange)
See Also: selectedRange
public void setString(String aString)
public void setTextColor(NSColor aColor)
null
.See Also: setTextColorInRange, textColor
public void setTextColorInRange(NSColor aColor, NSRange aRange)
null
.
This method applies only to rich text objects.See Also: setTextColor, textColor
public void setUsesFontPanel(boolean flag)
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 this. By default, an NSText object uses
the Font Panel and menu.See Also: usesFontPanel
public void setVerticallyResizable(boolean flag)
true
it
does; if flag is false
it
doesn't.See Also: setHorizontallyResizable, isVerticallyResizable
public void showGuessPanel(Object sender)
See Also: checkSpelling
public void sizeToFit()
See Also: isHorizontallyResizable, isVerticallyResizable
public String string()
See Also: setString
public void subscript(Object sender)
See Also: subscript, unscript, - lowerBaseline: (NSTextView)
public void superscript(Object sender)
See Also: subscript, unscript, - raiseBaseline: (NSTextView)
public NSColor textColor()
See Also: setTextColor, setTextColorInRange
public void toggleRuler(Object sender)
public void underline(Object sender)
public void unscript(Object sender)
See Also: subscript, superscript, - raiseBaseline: (NSTextView) - lowerBaseline: (NSTextView)
public boolean usesFontPanel()
true
if
the receiver uses the Font Panel, false
otherwise.See Also: setUsesFontPanel
public boolean writeRTFDToFile(String path, boolean atomicFlag)
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.See Also: RTFFromRange, RTFDFromRange, readRTFDFromFile
public abstract void textDidBeginEditing(NSNotification aNotification)
public abstract void textDidChange(NSNotification aNotification)
public abstract void textDidEndEditing(NSNotification aNotification)
public abstract boolean textShouldBeginEditing(NSText aTextObject)
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.See Also: - makeFirstResponder: (NSWindow) - becomeFirstResponder (NSResponder)
public abstract boolean textShouldEndEditing(NSText aTextObject)
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.See Also: - resignFirstResponder (NSResponder)
Posted when an NSText object begins any operation that changes characters or formatting attributes.
The notification contains a notification object but no userInfo dictionary. The notification object is the notifying NSText object.
Posted after an NSText object performs any operation that changes characters or formatting attributes.
The notification contains a notification object but no userInfo dictionary. The notification object is the notifying NSText object.
<< Forthcoming. >>