[TOC] [Prev] [Next] [Bottom]

NSCStringText

Inherits From:
NSText : NSView : NSResponder : NSObject

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

Declared In:
AppKit/NSCStringText.h

Class Description

Note: This class is being deprecated in favor of a new set of text classes. The documentation provided here is for developers who need to modify older applications. If you are writing a new application that uses text-editing services, see the NSText class. The NSCStringText class declares the programmatic interface to objects that manage text using eight-bit character encodings. The encoding is the same as the default C string encoding provided by defaultCStringEncoding in the NSString class.

The NSCStringText 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 NSCStringText object can (among other things):

NSCStringText can deal only with eight-bit characters. Therefore, it is not able to deal with Unicode character sets, and NSCStringText can't be fully internationalized.

Plain and Rich NSCStringText Objects

When you create an NSCStringText object directly, by default it allows only one font, line height, text color, and paragraph format for the entire text. You can set the default font used by new NSCStringText instances by sending the NSCStringText class object a setDefaultFont: message. Once an NSCStringText object is created, you can alter its global settings using methods such as setFont:paragraphStyle: and setLineHeight:. For convenience, such an NSCStringText object will be called a plain NSCStringText object.

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

A rich NSCStringText object can use RTF (Rich Text Format) as an interchange format. Not all RTF control words are supported: On input, an NSCStringText object ignores any control word it doesn't recognize; some of those it can read and interpret it doesn't write out. Refer to the class description of NSText for a list of the RTF control words that an NSCStringText object recognizes.

Note: An NSCStringText object writes eight-bit characters in the default C string encoding, which differs somewhat from the ANSI character set.

In an NSCStringText object, each sequence of characters having the same attributes is called a run. A plain NSCStringText object has only one run for the entire text. A rich NSCStringText object can have multiple runs. Methods such as setSelFont: and setSelColor: let you programmatically modify the attributes of the selected sequence of characters in a rich NSCStringText object. As discussed below, the user can set these attributes using the Font panel and the ruler.

NSCStringText objects are designed to work closely with various objects and services. 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, ruler, and Services menu-take no effort other than deciding whether the service should be enabled or disabled. The following sections discuss these interrelationships.

Notifying the NSCStringText Object's Delegate

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

textWillResize:
textDidResize:oldBounds:
textWillSetSel:toFont:
textWillConvert:fromFont:toFont:
textWillStartReadingRichText:
textWillFinishReadingRichText:
textWillWrite:
textDidRead:paperSize:

So, for example, if the delegate implements the textWillConvert:fromFont:toFont: method, it will receive notification upon the user's first attempt to change the font of 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 NSCStringText objects.

Adding Graphics to the Text

A rich NSCStringText 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. The programmatic approach is discussed first.

In the programmatic approach, you add an object-generally a subclass of NSCell-to the text. This object manages the graphic image by drawing it when appropriate. Although NSCell subclasses are commonly used, the only requirement is that the embedded object responds to these messages-see "Methods Implemented by an Embedded Graphic Object" for more information:

highlight:withFrame:inView:
drawWithFrame:inView:
trackMouse:inRect:ofView:untilMouseUp:
cellSize:
readRichText:forView:
richTextforView:

You place the graphic object in the text by sending the NSCStringText object a replaceSelWithCell: message.

An NSCStringText object displays a graphic in its text by sending the managing object a drawWithFrame:inView: message. To record the graphic to a file or to the pasteboard, the NSCStringText object sends the managing object a richTextforView: message. The object must then write an RTF control word along with any data (such as the path of a TIFF file containing its image data) it might need to recreate its image. To reestablish the text containing the graphic image from RTF data, an NSCStringText object must know which class to associate with particular RTF control words. You associate a control word with a class object by sending the NSCStringText class object a registerDirective:forClass: message. Thereafter, whenever an NSCStringText object finds the registered control word in the RTF data being read from a file or the pasteboard, it will create a new instance of the class and send the object a readRichText:forView: message.

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 NSCStringText object. The NSCStringText object automatically creates a graphic object to manage the display of the image. This feature requires a rich NSCStringText object that has been configured to receive dragged images-see the setImportsGraphics: method of the NSText class.

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 NSCStringText object can transfer information in an RTFD document to a file and read it from a file-see the writeRTFDToFile:atomically: and readRTFDFromFile: methods in the NSText methods.

Cooperating with Other Objects and Services

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

If an NSCStringText 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 NSCStringText 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.

By means of the Services menu, an NSCStringText object can make use of facilities outside the scope of its own application. By default, an NSCStringText object registers with the services system that it can send and receive RTF and plain ASCII data. If the application containing the NSCStringText object has a Services menu, a menu item is added for each service provider that can accept or return these formats. To prevent NSCStringText objects from registering for services, send the NSCStringText class object an excludeFromServicesMenu:YES message before any NSCStringText objects are created.

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


Method Types

<<Forthcoming>>

Class Methods

defaultFont

+ (NSFont *)defaultFont

Returns the NSCSTrintText class's default font. Unless you've changed the default font by sending a setDefaultFont: message, or taken advantage of the NSFont parameter using defaults , defaultFont returns an NSFont object for 12-point Helvetica with a flipped matrix.

See also: - setFont:paragraphStyle:, + setDefaultFont:


excludeFromServicesMenu:

+ excludeFromServicesMenu:(BOOL)flag

Controls whether NSCStringText objects communicate with interapplication services through the Services menu. If flag is YES, they do; if flag is NO, they don't.

By default, as each new NSCStringText instance is initialized, it registers with the NSApplication object that it's capable of sending and receiving the pasteboard types identified by NSAsciiPboardType and NSRTFPboardType . You might use this method, for example, if your application displays text but doesn't have editable text fields. Send an excludeFromServicesMenu: message early in the execution of your application, either before sending the NSApplication object a run message or in the NSApplication delegate's applicationWillInitialize: method .

See also: - validRequestorForSendType:returnType:, - registerServicesMenuSendTypes: returnTypes: (NSApplication)


registerDirective:forClass:

+ registerDirective:(NSString *)directive forClass:class

Creates an association in the NSCStringText class between the RTF control word directive and class, a class object. Thereafter, when an NSCStringText instance encounters directive while reading a stream of RTF text, it creates a new class instance. The new instance is sent a readRichText:forView: message to let it read its image data from the RTF text. Conversely, when an NSCStringText object is writing RTF data to a stream and encounters an object of the class class, the NSCStringText object sends the object a richTextForView: message to let it record its representation in the RTF text. Thus, this method is instrumental in enabling an NSCStringText object to read, display, and write an image within a text stream.

class must implement these methods:

highlight:inView:lit:
drawSelf:inView:
trackMouse:inRect:ofView:
calcCellSize:
readRichText:forView:
writeRichText:forView:

See the section titled "Methods Implemented by an Embedded Cell" for more information on these methods.

Returns nil if directive or class has already been registered; otherwise, returns self.

See also: - replaceSelWithCell:


setDefaultFont:

+ (void)setDefaultFont:(NSFont *)aFont

Sets the default font for the NSCStringText class object to aFont. Since an NSCStringText object uses a flipped coordinate system, make sure that aFont is also flipped.

See also: - setLineHeight:, + fontWithName:size: (NSFont), + defaultFont


Instance Methods

adjustPageHeightNew:top:bottom:limit:

- (void)adjustPageHeightNew:(float *)newBottom
top:(float)oldTop
bottom:(float)oldBottom
limit:(float)bottomLimit

During automatic pagination, this method is performed to help lay a grid of pages over the top-level view being printed. newBottom is passed in undefined and must be set by this method. oldTop and oldBottom are the current values for the horizontal strip being created. bottomLimit is the topmost value newBottom can be set to. If this limit is broken, the new value is ignored. By default, this method tries to prevent the view from being cut in two. All parameters are in the view's own coordinate system. Returns self.

See also: - adjustPageHeightNew:top:bottom:limit: (NSView)


adjustPageHeightNew:top:bottom:limit:

- adjustPageHeightNew:(float *)newBottom
top:(float)oldTop
bottom:(float)oldBottom
limit:(float)bottomLimit

During automatic pagination, this method is performed to help lay a grid of pages over the top-level view being printed. newBottom is passed in undefined and must be set by this method. oldTop and oldBottom are the current values for the horizontal strip being created. bottomLimit is the topmost value newBottom can be set to. If this limit is broken, the new value is ignored. By default, this method tries to prevent the view from being cut in two. All parameters are in the view's own coordinate system. Returns self.


breakTable

- (const NSFSM *)breakTable

Returns a pointer to the break table, the finite-state machine table that the Text object uses to determine word boundaries.

See also: - setBreakTable:


calcLine

- (int)calcLine

Calculates the array of line breaks for the text. The text will then be redrawn if autodisplay is set.

This message should be sent after the Text object's frame is changed. These methods send a calcLine message as part of their implementation:

- initFrame:text:alignment: - setFont:paragraphStyle:
- read: - renewFont:size:style:text:frame:tag:
- renewFont:text:frame:tag: - setParagraphStyle:
- renewRuns:text:frame:tag:

In addition, if a vertically resizable Text object is the document view of a ScrollView, and the ScrollView is resized, the Text object receives a calcLine message. Has no significant return value.

See also: - renewRuns:text:frame:tag:


changeTabStopAt:to:

- (BOOL)changeTabStopAt:(float)oldX to:(float)newX

Moves the tab stop from the receiving Text object's x coordinate oldX to the coordinate newX. For a plain Text object, all paragraphs are affected. For a rich Text object, only those paragraphs marked by the selection are affected. The text is rewrapped and redrawn. Returns self.

See also: - setSelProp:to:


charCategoryTable

- (const unsigned char *)charCategoryTable

Returns a pointer to the character category table, the table that maps ASCII characters to character categories.

See also: - setCharCategoryTable:


charFilter

- (NSCharFilterFunc)charFilter

Returns the character filter function, the function that analyzes each character the user enters. By default, this function is NXEditorFilter().

See also: - setCharFilter:


charWrap

- (BOOL)charWrap

Returns a flag indicating how words whose length exceeds the line length should be treated. If YES, long words are wrapped on a character basis. If NO, long words are truncated at the boundary of the bodyRect.

See also: - setCharWrap:


clear:

- (void)clear:(id)sender

Provided for backward compatibility. Use the delete: method instead.


clickTable

- (const NSFSM *)clickTable

Returns a pointer to the click table, the finite-state machine table that defines word boundaries for double-click selection.

See also: - setClickTable:


cStringTextInternalState

- (NSCStringTextInternalState *)cStringTextInternalState

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


defaultParagraphStyle

- (void *)defaultParagraphStyle

Returns by reference the default paragraph style for the text. The pointer that's returned refers to an NXTextStyle structure. The fields of this structure contain default paragraph indentation, alignment, line height, descent line, and tab information. The Text object's default values for these attributes can be altered using methods such as setParagraphStyle:, setLineHeight:, and setDescentLine:.

See also: - setParagraphStyle:, - setLineHeight:, - setDescentLine:


descentLine

- (float)descentLine

Returns the default descent line for the Text object. The descent line is the distance from the bottom of a line of text to the base line of the text.

See also: - setDescentLine:


drawFunc

- (NSTextFunc)drawFunc

Returns the draw function, the function that's called to draw each line of text. NXDrawALine() is the default draw function.

See also: - setDrawFunc:, - setScanFunc:


findText:ignoreCase:backwards:wrap:

- (BOOL)findText:(NSString *)textPattern
ignoreCase:(BOOL)ignoreCase
backwards:(BOOL)backwards
wrap:(BOOL)wrap

Searches for string in the text, starting at the insertion point. If ignoreCaseflag is YES, the search is case-insensitive. If backwardsflag is NO, the search proceeds forward through the text. If wrapflag is YES, upon reaching the end of the text, the search loops back to the start. If the string is found, it's highlighted and-if the Text object is the document view of a ScrollView-the selection is scrolled into view. Returns YES, if string is found, NO otherwise.

This method searches for the literal string; regular expression substitutions and wildcard characters aren't supported.


finishReadingRichText

- (void)finishReadingRichText

Notifies the Text object that it has finished reading RTF data. The Text object responds by sending its delegate a textWillFinishReadingRichText: message, assuming there is a delegate and it responds to this message. The delegate can then perform any required cleanup. Alternatively, a subclass of Text could put these cleanup routines in its own implementation of this method. Returns self.


firstTextBlock

- (NSTextBlock *)firstTextBlock

Returns a pointer to the first text block. You can traverse this head of the linked list of text blocks to read the contents of the Text object. In most cases, however, it's better to use the getSubstring:start:length: method to get a substring of the text or the stream method to get read-only access to the entire contents of the Text object.


getMarginLeft:right:top:bottom:

- (void)getMarginLeft:(float *)leftMargin
right:(float *)rightMargin
top:(float *)topMargin
bottom:(float *)bottomMargin

Calculates the dimensions of the Text object's margins and returns by reference these values in its four arguments. Returns self.

See also: - setMarginLeft:right:top:bottom:


getMinWidth:minHeight:maxWidth:maxHeight:

- (void)getMinWidth:(float *)width
minHeight:(float *)height
maxWidth:(float)widthMax
maxHeight:(float)heightMax

Calculates the minimum width and height needed to contain the text. Given a maximum width and height (widthMax and heightMax), this method copies the minimum width and height to the addresses pointed to by the width and height arguments. This method doesn't rewrap the text. To get the absolute minimum dimensions of the text, send a getMinWidth:minHeight:maxWidth:maxHeight: message only after sending a calcLine message.

The values derived by this method are accurate only if the Text object hasn't been scaled. Returns self.


getSelectionStart:end:

- (void)getSelectionStart:(NSSelPt *)start end:(NSSelPt *)end

Copies the starting and ending character positions of the selection into the addresses referred to by start and end. start points to the beginning of the selection; end points to the end of the selection. Returns self.

See also: - setSelectionStart:end:


hideCaret

- (void)hideCaret

Removes the caret from the text. The Text object sends itself hideCaret messages whenever the display of the caret would be inappropriate; you rarely need to send a hideCaret message directly. Occasions when the hideCaret message is sent include whenever the Text object receives a resignKeyWindow, mouseDown:, or keyDown: message. Returns self.

See also: - showCaret


initWithFrame:text:alignment:

- (id)initWithFrame:(NSRect)frameRect
text:(NSString *)theText
alignment:(NSTextAlignment)mode

Initializes a new Text object. This is the designated initializer for Text objects: If you subclass Text, your subclass's designated initializer must maintain the initializer chain by sending a message to super to invoke this method. See the introduction to the class specifications for more information.

The three arguments specify the Text object's frame rectangle, its text, and the alignment of the text. The frameRect argument specifies the Text object's location and size in its superview's coordinates. A Text object's superview must be a flipped view that's neither scaled nor rotated. The second argument, theText, is a null-terminated array of characters. The mode argument determines how the text is drawn with respect to the bodyRect:

Constant Alignment
NX_LEFTALIGNED Flush to left edge of the bodyRect.
NX_RIGHTALIGNED Flush to right edge of the bodyRect.
NX_CENTERED Each line centered between left and right edges of the bodyRect.
NX_JUSTIFIED Flush to left and right edges of the bodyRect; justified. Not yet implemented.

The Text object returned by this method uses the class object's default font (see setDefaultFont:) and uses NXEditorFilter() as its character filter. It wraps words whose length exceeds the line length. It sets its View properties to draw in its superview, to be flipped, and to be transparent. For more efficient editing, you can send a setOpaque: message to make the Text object opaque.

Text editing is designed to work in buffered windows only. In a nonretained or retained window, editing text in a Text object causes flickering. (However, to get better drawing performance without causing flickering during editing, see setRetainedWhileDrawing:).

Returns self.

See also: - initWithFrame:text:alignment:


isRetainedWhileDrawing

- (BOOL)isRetainedWhileDrawing

Returns YES if the Text object automatically changes its window's buffering type from buffered to retained whenever it redraws itself, NO if not.

See also: - setRetainedWhileDrawing:


lineFromPosition:

- (int)lineFromPosition:(int)position

Returns the line number that contains the character at position. To get more information about the contents of the Text object, use the stream returned by the stream method to read the contents of the Text object.

See also: - positionFromLine:


lineHeight

- (float)lineHeight

Returns the default line height for the Text object.

See also: - setLineHeight:


locationOfCell:

- (NSPoint)locationOfCell:(NSCell *)cell

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


moveCaret:

- (void)moveCaret:(unsigned short)theKey

Moves the caret either left, right, up, or down if theKey is NX_LEFT, NX_RIGHT, NX_UP, or NX_DOWN. If theKey isn't one of these four values, the caret doesn't move. Returns self.

See also: - keyDown: (NSResponder)


paragraphRect:start:end:

- (NSRect)paragraphRect:(int)prNumber
start:(int *)startPos
end:(int *)endPos

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


paragraphStyleForFont:alignment:

- (void *)paragraphStyleForFont:(NSFont *)fontId alignment:(int)alignment

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


positionFromLine:

- (int)positionFromLine:(int)line

Returns the character position of the line numbered line. Each line is terminated by a Return character, and the first line in a Text object is line 1. To find the length of a line, you can send the positionFromLine: message with two successive lines, and use the difference of the two to get the line length. To get more information about the contents of the Text object, use the stream returned by the stream method to read the contents of the Text object.

See also: - lineFromPosition:


postSelSmartTable

- (const unsigned char *)postSelSmartTable

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


preSelSmartTable

- (const unsigned char *)preSelSmartTable

Returns a pointer to the table that specifies which characters on the right end of a selection are treated as equivalent to a space character.

See also: - setPostSelSmartTable:, - setPreSelSmartTable:, - preSelSmartTable


readSelectionFromPasteboard:

- (BOOL)readSelectionFromPasteboard:(NSPasteboard *)pboard

Replaces the current selection with data from the supplied Pasteboard object, pboard. When the user chooses a command in the Services menu, a writeSelectionToPasteboard:types: message is sent to the first responder. This message is followed by a readSelectionFromPasteboard: message, if the command requires the requesting application to replace its selection with data from the service provider.

See also: - writeSelectionToPasteboard:types: (NSApplication), - validRequestorForSendType: returnType:


renewFont:size:style:text:frame:tag:

- (void)renewFont:(NSString *)newFontName
size:(float)newFontSize
style:(int)newFontStyle
text:(NSString *)newText
frame:(NSRect)newFrame
tag:(int)newTag

Resets a Text object so that it can be reused to draw or edit another piece of text. If newText is NULL, the new text is the same as the previous text. newTag sets the Text object's tag. A font object is created with newFontName, newFontSize, and newFontStyle. This method is a convenient cover for the renewRuns:text:frame:tag: method. Returns self.

See also: - renewRuns:text:frame:tag:


renewFont:text:frame:tag:

- (void)renewFont:(NSFont *)newFontId
text:(NSString *)newText
frame:(NSRect)newFrame
tag:(int)newTag

Resets a Text object so that it can be reused to draw or edit another piece of text. If newText is NULL, the new text is the same as the previous text. newTag sets a Text object's tag. This method is a convenient cover for the renewRuns:text:frame:tag: method. Returns self.


renewRuns:text:frame:tag:

- (void)renewRuns:(NSRunArray *)newRuns
text:(NSString *)newText
frame:(NSRect)newFrame
tag:(int)newTag

Resets a Text object so that it can be reused to draw or edit another piece of text. If newRuns is NULL, the new text uses the same runs as the previous text. If newText is NULL, the new text is the same as the previous text. newTag sets a Text object's tag. Returns self.


replaceSel:

- (void)replaceSel:(NSString *)aString

Replaces the current selection with text from aString, a null-terminated character string, and then rewraps and redisplays the text. Returns self.

See also: - replaceSel:length:


replaceSel:length:

- (void)replaceSel:(NSString *)aString length:(int)length

Replaces the current selection with length characters of text from aString, and then rewraps and redisplays the text. Returns self.

See also: - replaceSel:


replaceSel:length:runs:

- (void)replaceSel:(NSString *)aString
length:(int)length
runs:(NSRunArray *)insertRuns

Replaces the current selection with length characters of text from aString, using insertRuns to describe the run changes. Another way to replace the selection with multiple-run text is with replaceSelWithCell:.

After replacing the selection, this method rewraps and redisplays the text. Returns self.

See also: - replaceSel:, - replaceSelWithCell:


replaceSelWithCell:

- (void)replaceSelWithCell:(NSCell *)cell

Replaces the current selection with the image provided by cell. This method works only with rich Text objects.

The image is treated like a single character. Its height and width are determined by sending the NSCell a cellSize: message. The height determines the line height of the line containing the image, and the width sets the character placement in the line. The image is drawn by sending the Cell a drawSelf:inView: message.

After receiving a replaceSelWithCell: message, a Text object rewraps and redisplays its contents. Returns self.

See also: - cellSize (NSCell)


resignKeyWindow

- (void)resignKeyWindow

Deactivates the caret when the Text object's window ceases to be the key window. A Window, before it ceases to be the application's key window, sends this message to its first responder. You should never directly send this message to a Text object. Returns self.


resizeTextWithOldBounds:maxRect:

- (void)resizeTextWithOldBounds:(NSRect)oldBounds maxRect:(NSRect)maxRect

Causes the superview to redraw exposed portions of itself after the Text object's frame has changed in response to editing. You never send a resizeText:: message directly, but you might override it. oldBounds can differ from bounds in origin.x and size.width and size.height. Returns self.


runColor:

- (NSColor *)runColor:(NSRun *)run

Returns the color of the specified text run. By definition, a run can have no more than one color.


scanFunc

- (NSTextFunc)scanFunc

Returns the scan function, the function that calculates the contents of each line of text given the line width, font size, text alignment, and other factors. NXScanALine() is the default scan function.

See also: - setScanFunc:, - setDrawFunc:


scrollSelToVisible

- (void)scrollSelToVisible

Scrolls the text so that the selection is visible. This method works by invoking the scrollRectToVisible: method, which Text inherits from View. Returns self.


selColor

- (NSColor *)selColor

Returns the color of the selected text.

See also: - setSelColor:


selectError

- (void)selectError

Makes the entire text the selection and highlights it. The Text object applies this method if the delegate requires the Text object to maintain its status as the first responder. You rarely need to send a selectError message directly, although you may want to override it. To highlight a portion of the text, use setSelectionStart:end:. Returns self.

See also: - setSelectionStart:end:


selectNull

- (void)selectNull

Removes the selection and makes the highlighting (or caret, if the selection is zero-length) disappear. The Text object's delegate isn't notified of the change. The Text object sends a selectNull message whenever it needs to end the current selection but retain its status as the first responder; you rarely need to override this method or send selectNull messages directly. Returns self.

See also: - setSelectionStart:end:, - selectError, - getSelectionStart:end:


selectText:

- (void)selectText:(id)sender

Attempts to make a Text object the first responder and, if successful, then selects all of its text. This method works by invoking the selectAll: method. Returns self.

See also: - setSelectionStart:end:


setBreakTable:

- (void)setBreakTable:(const NSFSM *)aTable

Sets the break table, the finite-state machine table that the Text object uses to determine word boundaries. Returns self.

See also: - breakTable


setCharCategoryTable:

- (void)setCharCategoryTable:(const unsigned char *)aTable

Sets the character category table, the table that maps ASCII characters to character categories. Returns self.

See also: - charCategoryTable


setCharFilter:

- (void)setCharFilter:(NSCharFilterFunc)aFunc

Sets the character filter function, the function that analyzes each character the user enters. The Text object has two character filter functions: NXFieldFilter() and NXEditorFilter(). NXFieldFilter() interprets Tab and Return characters as commands to end the Text object's status as the first responder. NXEditorFilter(), the default filter function, accepts Tab and Return characters into the text. Returns self.

See also: - charFilter


setCharWrap:

- (void)setCharWrap:(BOOL)flag

Sets how words whose length exceeds the line length should be treated. If YES, long words are wrapped on a character basis. If NO, long words are truncated at the boundary of the bodyRect. Returns self.

See also: - charWrap


setClickTable:

- (void)setClickTable:(const NSFSM *)aTable

Sets the finite-state machine table that defines word boundaries for double-click selection. Returns self.

See also: - clickTable


setDescentLine:

- (void)setDescentLine:(float)value

Sets the default descent line for the text. The descent line is the distance from the bottom of a line of text to the base line of the text. setDescentLine: neither rewraps nor redraws the text. Send a calcLine message if you want the text rewrapped and redrawn after you reset the descent line. Returns self.

See also: - descentLine, - calcLine


setDrawFunc:

- (void)setDrawFunc:(NSTextFunc)aFunc

Sets the draw function, the function that's called to draw each line of text. NXDrawALine() is the default draw function. Returns self.

See also: - drawFunc, - setScanFunc:


setFont:paragraphStyle:

- (void)setFont:(NSFont *)fontObj paragraphStyle:(void *)paraStyle

Sets the font and paragraph style for the entire text. The text is then rewrapped and redrawn. The paragraph style controls such features as tab stops and line indentation. Returns self.

See also: - setSelFont:, - setParagraphStyle:


setLineHeight:

- (void)setLineHeight:(float)value

Sets the default minimum distance between adjacent lines. For a plain Text object, this will be the same for all lines. For rich Text objects, line heights will be increased for lines with larger fonts. Even if very small fonts are used, in no case will adjacent lines be closer than this minimum. setLineHeight: neither rewraps nor redraws the text. Send a calcLine message if you want the text rewrapped and redrawn after you reset the line height. If no line height is set, the default line height will be taken from the default font. Returns self.

See also: - lineHeight, + setDefaultFont:, - calcLine


setLocation:ofCell:

- (void)setLocation:(NSPoint)origin ofCell:(NSCell *)cell

Sets the x and y coordinates for the Cell object specified by cell. The coordinates are contained in the structure referred to by origin and are interpreted as being in the Text object's coordinate system.

This method is provided for programmers who want to write their own scan functions and need a way to position Cell objects found in the text stream. Sending a setLocation:ofCell: message to a Text object that uses the standard scan function will have no effect on the placement of cell. Returns self.

See also: - locationOfCell:, - replaceSelWithCell:


setMarginLeft:right:top:bottom:

- (void)setMarginLeft:(float)leftMargin
right:(float)rightMargin
top:(float)topMargin
bottom:(float)bottomMargin

Adjusts the dimensions of the Text object's margins. Returns self.

See also: - getMarginLeft:right:top:bottom:


setNoWrap

- (void)setNoWrap

Sets the Text object's breakTable and charWrap instance variables so that word wrap is disabled. It also sets the text alignment to NX_LEFTALIGNED. Returns self.

See also: - setCharWrap:


setParagraphStyle:

- (void)setParagraphStyle:(void *)paraStyle

Sets the paragraph style for the entire text. The text is then rewrapped and redrawn. The paragraph style controls features such as tab stops and line indentation. Returns self.

See also: - setFont:paragraphStyle:, - setSelFont:


setPostSelSmartTable:

- (void)setPostSelSmartTable:(const unsigned char *)aTable

Sets postSelSmartTable, the table that specifies which characters on the right end of a selection are treated as equivalent to a space character. Returns self.

See also: - postSelSmartTable, - setPreSelSmartTable:, - preSelSmartTable


setPreSelSmartTable:

- (void)setPreSelSmartTable:(const unsigned char *)aTable

Sets preSelSmartTable, the table that specifies which characters on the left end of a selection are treated as equivalent to a space character. Returns self.

See also: - preSelSmartTable, - setPostSelSmartTable:


setRetainedWhileDrawing:

- (void)setRetainedWhileDrawing:(BOOL)aFlag

Sets whether the Text object automatically changes its window's buffering type from buffered to retained whenever it redraws itself. Drawing directly to the screen improves the Text object's perceived performance, especially if the text contains numerous fonts and formats. Rather than waiting until the entire text is flushed to the screen, the user sees the text being drawn line-by-line.

The window's buffering type changes to retained only while the Text object is redrawing itself-that is, only when the Text object's drawSelf:inView: method is invoked. In other cases, such as when a user is entering text, the window's buffering type is unaffected. This method is designed to work with Text objects that are in buffered windows; don't send a setRetainedWhileDrawing: message to a Text object in a retained or nonretained window. Returns self.

See also: - isRetainedWhileDrawing


setScanFunc:

- (void)setScanFunc:(NSTextFunc)aFunc

Sets the scan function, the function that calculates the contents of each line of text given the line width, font size, type of text alignment, and other factors. NXScanALine() is the default scan function. Returns self.

See also: - scanFunc, - setDrawFunc:


setSelColor:

- (void)setSelColor:(NSColor *)color

Sets the text color of the selected text, assuming the Text object allows more than one paragraph style and font. Otherwise, setSelColor: sets the text color for the entire text. color is an NXColor structure as defined in the header file appkit/color.h. After the text color is set, the text is redisplayed. Returns self.


setSelFont:

- (void)setSelFont:(NSFont *)fontId

Sets the font for the selection. The text is then rewrapped and redrawn. Returns self.

See also: - setSelFontSize:, - setSelFontStyle:


setSelFont:paragraphStyle:

- (void)setSelFont:(NSFont *)fontId paragraphStyle:(void *)paraStyle

Sets the font of the current selection to that specified by fontID. The selection's paragraph style is also changed. If fontId is NULL, no change is made to the selection's font. Returns self.

See also: - setSelFont:, - setSelFontSize:, - setSelFontStyle:


setSelFontFamily:

- (void)setSelFontFamily:(NSString *)fontName

Sets the name of the font for the selection to fontName. The text is then rewrapped and redrawn. Returns self.

See also: - setSelFontSize:, - setSelFontStyle:


setSelFontSize:

- (void)setSelFontSize:(float)size

Sets the size of the font for the selection to size. The text is then rewrapped and redrawn. Returns self.

See also: - setSelFont:, - setSelFontStyle:


setSelFontStyle:

- (void)setSelFontStyle:(NSFontTraitMask)traits

Sets the font style for the selection. The text is then rewrapped and redrawn. The Text object uses the FontManager to change the various traits of the selected font. Returns self.

See also: - setSelFont:, - setSelFontSize:


setSelProp:to:

- (BOOL)setSelProp:(NSParagraphProperty)prop to:(float)val

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


setSelectionStart:end:

- (void)setSelectionStart:(int)start end:(int)end

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


setTag:

- (void)setTag:(int)anInt

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


setTextFilter:

- (void)setTextFilter:(NSTextFilterFunc)aFunc

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


showCaret

- (void)showCaret

Description forthcoming. See related OpenStep file: /NextLibrary/Documentation/OpenStepSpec/ApplicationKit/Classes/NSCStringText.rtf.


startReadingRichText

- (void)startReadingRichText

A startReadingRichText message is sent to the Text object just before it begins reading RTF data. The Text object responds by sending its delegate a textWillStartReadingRichText: message, assuming there is a delegate and it responds to this message. The delegate can then perform any required initialization. Alternatively, a subclass of Text could put these initialization routines in its own implementation of this method. Returns self.


tag

- (int)tag

Returns the Text object's tag.

See also: - setTag:


textFilter

- (NSTextFilterFunc)textFilter

Returns the text filter function, the function that analyzes text the user enters. By default, this function is NULL.

See also: - setTextFilter:


validRequestorForSendType:returnType:

- (id)validRequestorForSendType:(NSString *)sendType returnType:(NSString *)returnType

Responds to a message that the Application object sends to determine which items in the Services menu should be enabled or disabled at any particular time. You never send a validRequestorForSendType:returnType: message directly, but you might override this method in a subclass of Text.

A Text object registers for services during initialization (however, see excludeFromServicesMenu:). Thereafter, whenever the Text object is the first responder, the Application object can send it one or more validRequestorForSendType: returnType: messages during event processing to determine which Services menu items should be enabled. If the Text object can place data of type sendType on the pasteboard and receive data of type returnType back, it should return self; otherwise it should return nil. The Application object checks the return value to determine whether to enable or disable commands in the Services menu.

Since an object can receive one or more of these messages per event, it's important that if you override this method in a subclass of Text, the new implementation include no time-consuming calculations.

See the description of validRequestorForSendType:returnType: in the Responder class specification for more information.

See also: + excludeFromServicesMenu:, - registerServicesMenuSendTypes:returnTypes: (NSApplication), - readSelectionFromPasteboard:, - writeSelectionToPasteboard:types:, - validRequestorForSendType:returnType: (NSResponder)


writeSelectionToPasteboard:types:

- (BOOL)writeSelectionToPasteboard:(NSPasteboard *)pboard types:(NSArray *)types

Writes the current selection to the supplied Pasteboard object, pboard. types lists the data types to be copied to the pasteboard. A return value of NO indicates that the data of the requested types could not be provided.

When the user chooses a command in the Services menu, a writeSelectionToPasteboard:types: message is sent to the first responder. This message is followed by a readSelectionFromPasteboard: message if the command requires the requesting application to replace its selection with data from the service provider.

See also: - readSelectionFromPasteboard:, - validRequestorForSendType:returnType:


Methods Implemented By the Delegate

textDidRead:paperSize:

- (void)textDidRead:(NSCStringText *)textObject paperSize:(NSSize)paperSize

Responds to a message informing the delegate that the Text object will read the paper size for the document.

This message is sent to the delegate after the Text object reads RTF data, allowing the delegate to modify the paper size. paperSize is the dimensions of the paper size specified by the \paperw and \paperh RTF control words.

See also: - textWillWrite:


textDidResize:oldBounds:

- (NSRect)textDidResize:(NSCStringText *)textObject oldBounds:(NSRect)oldBounds

Responds to a message informing the delegate that the Text object has changed its size. oldBounds is the Text object's bounds rectangle before the change. invalidRect is the area of the Text object's superview that should be redrawn if the Text object has become smaller.


textWillConvert:fromFont:toFont:

- (NSFont *)textWillConvert:(NSCStringText *)textObject
fromFont:(NSFont *)from
toFont:(NSFont *)to

Responds to a message giving the delegate the opportunity to alter the font that will be used for the selection. The message is sent whenever the Font panel sends a changeFont: message to the Text object. from is the old font that's currently being changed, to is the font that's to replace from. This method returns the font that's to be used instead of the to font.


textWillFinishReadingRichText:

- (void)textWillFinishReadingRichText:(NSCStringText *)textObject

Responds to a message informing the delegate that the Text object has read RTF data, either from the pasteboard or from a text file.


textWillResize:

- (void)textWillResize:(NSCStringText *)textObject

Responds to a message informing the delegate that the Text object is about to change its size. The delegate's textWillResize: method can specify the maximum dimensions of the Text object by using the setMaxSize: method.

If the delegate doesn't implement this method, the change is allowed by default.


textWillSetSel:toFont:

- (void)textWillSetSel:(NSCStringText *)textObject toFont:(NSFont *)font

Responds to a message giving the delegate the opportunity to change the font that the Text object is about to display in the Font panel. font is the font that's about to be set in the Font panel. This method returns the real font to show in the Font panel.


textWillStartReadingRichText:

- (void)textWillStartReadingRichText:(NSCStringText *)textObject

Responds to a message informing the delegate that the Text object is about to read RTF data, either from the Pasteboard or from a text file.


textWillWrite:

- (NSSize)textWillWrite:(NSCStringText *)textObject

Responds to a message informing the delegate that the Text object will write out the paper size for the document.

As part of its RTF output, the Text object's delegate can write out a paper size for the document. The delegate specifies the paper size by placing the width and height values (in points) in the structure referred to by paperSize. Unless the delegate specifies otherwise, the paper size is assumed to be 612 by 792 points (8 1/2 by 11 inches).

See also: - textDidRead:paperSize:

Methods Implemented by an Embedded Cell

cellSize

- (NSSize)cellSize

Responds to a message from the Text object by providing the graphic object's width and height. The Text object uses this information to adjust character placement and line height to accommodate the display of the graphic object in the text. See the Cell class specification for one implementation of this method.

See also: - cellSize (NSCell)


drawWithFrame:inView:

- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Responds to a message from the Text object by drawing the graphic object within the given rectangle and View. The supplied View is generally the Text object itself. See the NSCell class specification for one implementation of this method.

See also: - drawWithFrame:inView: (NSCell)


highlight:withFrame:inView:

- (void)highlight:(BOOL)flag withFrame:(NSRect)cellFrame inView:(NSView *)controlView

Responds to a message from the Text object by highlighting or unhighlighting the graphic object during mouse tracking. rect is the area within view (generally the Text object itself) to be highlighted. If flag is YES, this method should draw the graphic object in its highlighted state; if NO, it should draw the graphic object in its normal state. See the Cell class specification for one implementation of this method.

See also: - highlight:withFrame:inView: (NSCell)


readRichText:forView:

- (void)readRichText:(NSString *)string forView:(NSView *)view

Responds to a message sent by the Text object when it encounters an RTF control word that's associated with the graphic object's class (see registerDirective:forClass:). The graphic object should read its representation from the RTF data in the supplied stream. The Text object passes its id as the view argument.

This method is the counterpart to writeRichText:forView:. In extracting the image data from the stream, readRichText:forView: must read the exact number of characters that writeRichText:forView: wrote in storing the image data to the stream.

See also: - registerDirective:forClass:


richTextForView:

- (NSString *)richTextForView:(NSView *)view

Responds to a message sent by the Text object when it encounters the graphic object in the text it's writing to stream. The graphic object should write an RTF representation of its image to the supplied stream. The Text object passes its id as the view argument.

See also: - readRichText:forView:, - registerDirective:forClass:


trackMouse:inRect:ofView:untilMouseUp:

- (BOOL)trackMouse:(NSEvent *)theEvent
inRect:(NSRect)cellFrame
ofView:(NSView *)controlView
untilMouseUp:(BOOL)flag

Responds to a message from the Text object by tracking the mouse while it's within the specified rectangle of the supplied View. theEvent is a pointer to the mouse-down event that caused the Text object to send this message. rect is the area within view (generally the Text object) where the mouse will be tracked. See the Cell class specification for one implementation of this method.

See also: - trackMouse:inRect:ofView: (Cell)



[TOC] [Prev] [Next] [Bottom]

Copyright © 1997, Apple Computer, Inc. All rights reserved.