Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSText

Inherits From:	NSView : NSResponder : NSObject

Conforms To:	NSChangeSpelling, NSIgnoreMisspelledWords
NSCoding (NSResponder)
NSObject (NSObject)

Declared In:	AppKit/NSTextView.h

Class Description

The NSText class declares the programmatic interface to objects that manage text. NSText objects are used by the Application Kit wherever text appears in interface objects: An NSText 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 inherits these uses of the NSText class when it incorporates any of these objects into its interface. Your application can also create NSText objects for its own purposes.

The NSText class is unlike most other classes in the Application Kit in its complexity and range of features. One of its design goals is to provide a comprehensive set of text-handling features so that you'll rarely need to create a subclass. An NSText object can (among other things):

·	Control the color of its text and background.

·	Control the font and layout characteristics of its text.

·	Control whether text is editable.

·	Wrap text on a word or character basis.

·	Display graphic images within its text.

·	Write text to or read text from files in the form of RTFDÐRich Text Format files that contain TIFF or EPS images.

·	Let another object, the delegate, dynamically control its properties.

·	Let the user copy and paste text within and between applications.

·	Let the user copy and paste font and format information between NSText objects.

·	Let the user check the spelling of words in its text.

·	Let the user control the format of paragraphs by manipulating a ruler.

Graphical user-interface building tools (such as Interface Builder) may give you access to NSText objects in several different configurations, such as those found in the NSTextField, NSForm, and NSScrollView objects. These classes configure an NSText object for their own specific purposes. Additionally, all NSTextFields, NSForms, NSButtons within the same windowÐin short, all objects that access an NSText object through associated CellsÐshare the same NSText 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 NSText objects yourself. If one of these classes doesn't provide enough flexibility for your purposes, you can create NSText objects programatically.

Plain and Rich NSText Objects

When you create an NSText object directly, by default it allows only one font, line height, text color, and paragraph format for the entire text. Once an NSText object is created, you can alter its global settings using methods such as setFont: and setTextColor:. For convenience, such an NSText object will be called a plain NSText object.

To allow multiple values for attributes such as font and color, you must send the NSText object a setRichText:YES message. An NSText object that allows multiple fonts also allows multiple paragraph formats, line heights, and so on. For convenience, such an NSText object will be called a rich NSText object.

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. These are the RTF control words that an NSText object recognizes.

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

NSText objects are designed to 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, spelling checker, or rulerÐtake no effort other than deciding whether the service should be enabled or disabled. The following sections discuss these interrelationships.

Notifying the NSText Object's Delegate

Many of an NSText object's actions can be controlled through an associated object, the NSText object's delegate. If it implements any of the following methods, the delegate receives the corresponding message at the appropriate time:

textDidBeginEditing:
textDidChange:
textDidEndEditing:
textShouldBeginEditing:
textShouldEndEditing:

So, for example, if the delegate implements the textDidBeginEditing: method, it will receive notification upon the user's first attempt to change the text. Moreover, depending on the method's return value, the delegate can either allow or prohibit changes to the text. See ªMethods Implemented by the Delegateº. The delegate can be any object you choose, and one delegate can control multiple NSText objects.

Adding Graphics to the Text

A rich NSText object allows graphics 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 ªcharacter.º Graphics are embedded in the text in either of two ways: programmatically or directly through user actions. In the programmatic approach, graphic objects are added using the replaceRange:WithRTFD: method.

An alternate means of adding an image to the text is for the user to drag an EPS or TIFF file icon directly into an NSText object. The NSText object automatically creates a graphic object to manage the display of the image. This feature requires a rich NSText object that has been configured to receive dragged imagesÐsee the setImportsGraphics: method. 

Images that have been imported in this way can be written as RTFD documents. Programmatic creation of RTFD documents is not supported in this version of OpenStep. 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 a ª.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. An NSText object can transfer information in an RTFD document to a file and read it from a fileÐsee the writeRTFDToFile:atomically: and readRTFDFromFile: methods.

Cooperating with Other Objects and Services

NSText objects are designed to work with the Application Kit's font conversion system. By default, an NSText object keeps the Font panel updated with the font of the current selection. It also changes the font of the selection (for a rich NSText object) or of the entire text (for a default NSText object) to reflect the user's choices in the Font panel or menu. To disconnect an NSText object from this service, send it a setUsesFontPanel:NO message.

If an NSText object is a subview of an NSScrollView, it can cooperate with the NSScrollView to display and update a ruler that displays formatting information. The NSScrollView retiles its subviews to make room for the ruler, and the NSText object updates the ruler with the format information of the paragraph containing the selection. The toggleRuler: method controls the display of this ruler. Users can modify paragraph formats by manipulating the components of the ruler.

Coordinates and sizes mentioned in the method descriptions below are in PostScript unitsÐ1/72 of an inch.

Getting and Setting Contents 

- (void)replaceRange:(NSRange)range	Replaces the characters within the specified range of
withRTF:(NSData *)rtfData		text with the RTF data rtfData.

- (void)replaceRange:(NSRange)range	Replaces the characters within the specified range of
withRTFD:(NSData *)rtfdData		text with the RTFD data rtfdData.

- (NSData *)RTFDFromRange:(NSRange)range	Extracts the specified range of RTFD text from the NSText object and returns an data object initialized with that text.

- (NSData *)RTFFromRange:(NSRange)range	Extracts the specified range of RTF text from the NSText object and returns a data object initialized with that text. This data is formatted according to the RTF file format.

- (void)setText:(NSString *)string	Sets the contents of the NSText object to be string. 

- (void)setText:(NSString *)string	Replaces the characters in the specified range of text in the 
range:(NSRange)range		NSText object to be string.

- (NSString *)text	Returns the contents of the NSText object as a immutable string object.

Managing Global Characteristics

- (NSTextAlignment)alignment	Returns how text in the NSText object is aligned between the margins.

- (BOOL)drawsBackground	Returns whether the NSText object draws its own background.

- (BOOL)importsGraphics	Returns whether the NSText object can accept images.

- (BOOL)isEditable	Returns whether users can edit the NSText object.

- (BOOL)isRichText	Returns whether the text in the NSText object is RTF.

- (BOOL)isSelectable	Returns whether users can select text in the NSText object.

- (void)setAlignment:(NSTextAlignment)mode	Sets how the text in the NSText object is aligned between the margins.

- (void)setDrawsBackground:(BOOL)flag	Sets whether the NSText object draws its own background.

- (void)setEditable:(BOOL)flag	Sets whether users can edit text in the NSText object.

- (void)setImportsGraphics:(BOOL)flag	Sets whether the NSText object can accept images.

- (void)setRichText:(BOOL)flag	Sets whether the text in the NSText object allows for multiple values of attributes, such as color and font (i.e. RTF).

- (void)setSelectable:(BOOL)flag	Sets whether users can select text in the NSText object.

Managing Font and Color

- (NSColor *)backgroundColor	Returns the background color for the NSText object.

- (void)changeFont:(id)sender	Initiates a font-change session.

- (NSFont *)font	Returns the default NSFont object for the NSText object.

- (void)setBackgroundColor:(NSColor *)color	Sets the background color for the NSText object.

- (void)setColor:(NSColor *)color	Sets the color for the specified range of text in the
ofRange:(NSRange)range		NSText object to color.

- (void)setFont:(NSFont *)obj	Sets the default NSFont object for the NSText object.

- (void)setFont:(NSFont *)font	Sets the font for the specified range of text in the 
ofRange:(NSRange)range		NSText object to font.

- (void)setTextColor:(NSColor *)color	Sets the textual color for the NSText object.

- (void)setUsesFontPanel:(BOOL)flag	Sets whether the NSText object uses the font panel.

- (NSColor *)textColor	Returns the textual color for the NSText object.

- (BOOL)usesFontPanel	Returns whether the NSText object uses the font panel

Managing the Selection

- (NSRange)selectedRange	Returns the range of the selected text in the NSText object.

- (void)setSelectedRange:(NSRange)range	Sets the range of selected text in the NSText object.

Sizing the Frame Rectangle

- (BOOL)isHorizontallyResizable	Returns whether the frame width can change.

- (BOOL)isVerticallyResizable	Returns whether the frame height can change.

- (NSSize)maxSize	Gets the maximum size of the NSTextView's frame.

- (NSSize)minSize	Gets the minimum size of the NSTextView's frame.

- (void)setHorizontallyResizable:(BOOL)flag	Sets whether the frame's width can change.

- (void)setMaxSize:(NSSize)newMaxSize	Sets the maximum size of the NSText object to newMaxSize.

- (void)setMinSize:(NSSize)newMinSize	Sets the minimum size of the NSText object to newMinSize.

- (void)setVerticallyResizable:(BOOL)flag	Sets whether the frame's height can change.

- (void)sizeToFit	Resizes the frame to fit just around the text.

Responding to Editing Commands

- (void)alignCenter:(id)sender	Centers the selected text between the margins.

- (void)alignLeft:(id)sender	Aligns selected text to the left margin.

- (void)alignRight:(id)sender	Aligns selected text the right margin.

- (void)copy:(id)sender	Copies the selected text to the pasteboard.

- (void)copyFont:(id)sender	Copies the selected text's font to the pasteboard.

- (void)copyRuler:(id)sender	Copies the selected text's ruler to the pasteboard.

- (void)cut:(id)sender	Deletes the selected text and copies it to the pasteboard. 

- (void)delete:(id)sender	Deletes the selected text. This method posts the notification NSTextDidChangeNotification with the receiving object to the default notification center and may post the NSTextDidBeginEditing notification as well. (NSTextDidEndEditingNotification gets posted when the first responder changes.)

- (void)paste:(id)sender	Replaces the selected text with the contents of the pasteboard. This method posts the notification NSTextDidChangeNotification with the receiving object to the default notification center and may post the NSTextDidBeginEditing notification as well.

- (void)pasteFont:(id)sender	Replaces the selection's font with the pasteboard contents. This method posts the NSTextDidChangeNotification notification with the receiving object to the default notification center and may post the NSTextDidBeginEditing notification as well.

- (void)pasteRuler:(id)sender	Replaces the selection's ruler with the pasteboard contents.

- (void)selectAll:(id)sender	Selects all text in the NSText object.

- (void)subscript:(id)sender	Subscripts the current selection.

- (void)superscript:(id)sender	Superscripts the current selection.

- (void)underline:(id)sender	Underlines the selected text.

- (void)unscript:(id)sender	Removes superscript or subscript in the current selection.

Managing the Ruler

- (BOOL)isRulerVisible	Returns whether the ruler is visible.

- (void)toggleRuler:(id)sender	Displays the ruler if it's not visible, and removes it if it is visible.

Spelling

- (void)checkSpelling:(id)sender	Initiates a spell-checking session.

- (void)showGuessPanel:(id)sender	Displays the spell-checker's Show Guess panel.

Scrolling

- (void)scrollRangeToVisible:(NSRange)range	Scrolls the NSText object so that the range of text is visible.

Reading and Writing RTFD Files

- (BOOL)readRTFDFromFile:(NSString *)path	Reads RTFD data from the file package specified by path and initializes an NSText object with it; returns whether the operation succeeded.

- (BOOL)writeRTFDToFile:(NSString *)path	Writes RTFD data from the receiving NSText object
atomically:(BOOL)flag		to the file package specified by path. flag determines whether writing occurs atomically. Returns whether the operation succeeded.

Managing the Field Editor

- (BOOL)isFieldEditor	Returns whether the receiving NSText object gives up First Responder status on tab, carriage return, etc.

- (void)setFieldEditor:(BOOL)flag	Sets whether the receiving NSText object is to be used as a field editor. flag indicates whether to end on carriage return, tab, or other terminating character.

Managing the Delegate

- (id)delegate	Returns the delegate of the NSText object.

- (void)setDelegate:(id)anObject	Makes anObject the NSText object's delegate.

Implemented by the Delegate

- (void)textDidBeginEditing:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSTextDidBeginEditingNotification. If the delegate implements this method, it's automatically registered to receive this notification.

- (void)textDidChange:(NSNotification *)aNotification	
	Sent by the default notification center to the delegate; aNotification is always NSTextDidChangeNotification. If the delegate implements this method, it's automatically registered to receive this notification.

- (void)textDidEndEditing:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSTextDidEndEditingNotification. If the delegate implements this method, it's automatically registered to receive this notification.

- (BOOL)textShouldBeginEditing:(NSText *)textObject	 
	Sent directly by textObject to the delegate. Informs delegate of an impending textual change. YES means go ahead and make the change.

- (BOOL)textShouldEndEditing:(NSText *)textObject	
	Sent directly by textObject to the delegate. Warns delegate of the impending loss of First Responder status. YES means go ahead and change status.