ftp.nice.ch/peanuts/GeneralData/Documents/openstep/OpenStepSpec_rtf.tar.gz#/OpenStepSpec_rtf/ApplicationKit/Classes/NSCStringText.rtf

This is NSCStringText.rtf in view mode; [Download] [Up]

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


NSCStringText 

Inherits From:tab NSText : NSView : NSResponder : NSObject 

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

Declared In:tab AppKit/NSCStringText.h 


Class Description


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. NSCStringText can be used in situations where backwards compatibility with the detailed interfaces of the NEXTSTEP Text object is important. Applications that can use the interface of NSText should do so.

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):

·tab Control the color of its text and background.

·tab Control the font and layout characteristics of its text.

·tab Control whether text is editable.

·tab Wrap text on a word or character basis.

·tab Write text to, or read it from, a file, as either RTF or plain ASCII data.

·tab Display graphic images within its text.

·tab Communicate with other applications through the Services menu.

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

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

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

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

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

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:, setLineHeight:, setTextGray:, and setAlignment:. 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 (this method is actually implemented by NSTextÐthe superclass).

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.


Initializing a New NSCStringText Object 


- (id)initWithFrame:(NSRect)frameRecttab Returns a new NSCStringText object at frameRect 
text:(NSString *)theTexttab tab initialized with the contents of theText and with mode 
alignment:(NSTextAlignment)modetab  tab alignment.

Modifying the Frame Rectangle 


- (void)resizeTextWithOldBounds:(NSRect)oldBounds 
maxRect:(NSRect)maxRecttab Used by the NSCStringText object to resize and redisplay itself. 

Laying Out the Text 


- (int)calcLinetab Calculates line breaks. 

- (BOOL)changeTabStopAt:(float)oldXtab  Resets the position of the specified tab stop.
to:(float)newX 

- (BOOL)charWraptab Returns whether extra long words are wrapped. 

- (void *)defaultParagraphStyletab Returns the default paragraph style. 

- (float)descentLinetab Returns distance from base line to bottom of line. 

- (void)getMarginLeft:(float *)leftMargintab  Gets by reference the dimensions of margins around the 
right:(float *)rightMargintab  tab text.
top:(float *)topMargintab  
bottom:(float *)bottomMargintab  

- (void)getMinWidth:(float *)widthtab Given the widthMax and heightMax, calculates the
minHeight:(float *)heighttab tab minimum area needed to display the text and returns
maxWidth:(float)widthMaxtab tab width and height by reference.
maxHeight:(float)heightMaxtab tab  

- (float)lineHeighttab Returns height of a line of text. 

- (void *)paragraphStyleForFont:(NSFont *)fontIdtab Recalculates the paragraph style based on new font fontId 
alignment:(int)alignmenttab  and alignment.

- (void)setCharWrap:(BOOL)flagtab Sets whether extra long words are wrapped. 

- (void)setDescentLine:(float)valuetab Sets the distance from the base line to the bottom of line to value.

- (void)setLineHeight:(float)valuetab Sets the height of a line of text to value. 

- (void)setMarginLeft:(float)leftMargintab Adjusts the margins around the text. 
right:(float)rightMargintab  
top:(float)topMargintab  
bottom:(float)bottomMargin

- (void)setNoWraptab Disables word wrap. 

- (void)setParagraphStyle:(void *)paraStyletab Sets the default paragraph style for the entire text. 

- (BOOL)setSelProp:(NSParagraphProperty)property
to:(float)valuetab Sets a paragraph property for one or more selected
tab tab paragraphs to value.

Reporting Line and Position 


- (int)lineFromPosition:(int)positiontab Converts character position to line number. 

- (int)positionFromLine:(int)linetab Converts line number to character position. 

Reading and Writing Text 


- (void)finishReadingRichTexttab Sent after the NSCStringText object reads RTF data. 

- (NSTextBlock *)firstTextBlocktab Returns a pointer to the first text block in the NSCStringText object. 

- (NSRect)paragraphRect:(int)paraNumbertab Returns the location and size of a paragraph identified by
start:(int *)startPostab  tab paraNumber; also returns the starting and ending 
end:(int *)endPostab  tab character positions by reference.

- (void)startReadingRichTexttab Sent before the NSCStringText object begins reading RTF data.

Editing Text 


- (void)clear:(id)sendertab Deletes the selected text. 

- (void)hideCarettab Removes the caret from the text display. 

- (void)showCarettab Displays the previously hidden caret in the text display. 

Managing the Selection 


- (void)getSelectionStart:(NSSelPt *)starttab Gets information (by reference) relating to the starting and
end:(NSSelPt *)endtab  tab ending character positions of the selection.

- (void)replaceSel:(NSString *)aStringtab Replaces the selection with aString. 

- (void)replaceSel:(NSString *)aStringtab Replaces the selection with length bytes of aString.
length:(int)lengthtab  

- (void)replaceSel:(NSString *)aStringtab Replaces the selection with length bytes of aString.
length:(int)lengthtab  tab insertRuns is a pointer to the current run in the run
runs:(NSRunArray *)insertRunstab  tab array.

- (void)scrollSelToVisibletab Brings the selection within the frame rectangle. 

- (void)selectErrortab Selects all the text. 

- (void)selectNulltab Deselects the current selection. 

- (void)setSelectionStart:(int)starttab Selects text from characters start through end. 
end:(int)end

- (void)selectText:(id)sendertab Makes the receiver the first responder and selects all text. 

Setting the Font 


+ (NSFont *)defaultFonttab Returns the default NSFont object for NSCStringText objects.

+ (void)setDefaultFont:(NSFont *)anObjecttab Makes anObject the default NSFont object for NSCStringText objects. 

- (void)setFont:(NSFont *)fontObjtab Sets the NSFont object and paragraph style for all text.
paragraphStyle:(void *)paragraphStyletab  

- (void)setSelFont:(NSFont *)fontObjtab Sets the NSFont object for the selection.

- (void)setSelFont:(NSFont *)fontObjtab Sets the NSFont object and paragraph style for the
paragraphStyle:(void *)paragraphStyletab  tab selection. 

- (void)setSelFontFamily:(NSString *)fontNametab Sets the font family for the selection. 

- (void)setSelFontSize:(float)sizetab Sets the font size for the selection. 

- (void)setSelFontStyle:(NSFontTraitMask)traitstab Sets the font style for the selection. 

Finding Text 


- (BOOL)findText:(NSString *)textPatterntab Searches for textPattern in the text, starting at the insertion
ignoreCase:(BOOL)ignoreCasetab tab point. ignoreCase instructs the search to disregard case;
backwards:(BOOL)backwardstab tab  backwards means search backwards; wrap means that
wrap:(BOOL)wraptab tab  when the search reaches the beginning or end of the text (depending on the direction), it should continue by wrapping to the end or beginning of the text.

Modifying Graphic Attributes 


- (NSColor *)runColor:(NSRun *)runtab Returns the color of the specified text run. 

- (NSColor *)selColortab Returns the color of the selected text. 

- (void)setSelColor:(NSColor *)colortab Sets the color of the selected text. 

Reusing an NSCStringText Object 


- (void)renewFont:(NSFont *)newFontObjtab Resets the NSCStringText object to draw different text 
text:(NSString *)newTexttab tab newText in font newFontId within frame newFrame. 
frame:(NSRect)newFrame
tag:(int)newTagtab  

- (void)renewFont:(NSString *)newFontNametab Resets the NSCStringText object to draw different text 
size:(float)newFontSizetab tab newText in the font identified by newFontName, 
style:(int)newFontStyletab tab newFontSize, and newFontStyle. Drawing occurs within 
text:(NSString *)newTexttab tab frame newFrame.
frame:(NSRect)newFrame
tag:(int)newTagtab  

- (void)renewRuns:(NSRunArray *)newRunstab Resets the NSCStringText object to draw different text 
text:(NSString *)newTexttab tab newText in newFrame.
frame:(NSRect)newFrame
tag:(int)newTagtab  

Setting Window Attributes 


- (BOOL)isRetainedWhileDrawingtab Returns whether a retained window is used for drawing. 

- (void)setRetainedWhileDrawing:(BOOL)flagtab Allows use of a retained window when drawing. 

Assigning a Tag 


- (void)setTag:(int)anInttab Makes anInt the NSCStringText object's tag. 

- (int)tagtab Returns the NSCStringText object's tag. 

Handling Event Messages 


- (void)becomeKeyWindowtab Activates the caret if selection has width of 0. 

- (void)moveCaret:(unsigned short)theKeytab Moves the caret in response to arrow keys. 

- (void)resignKeyWindowtab Deactivates the caret. 

Displaying Graphics within the Text 


+ registerDirective:(NSString *)directivetab Associates an RTF control word (directive) with class
forClass:classtab tab (usually NSCell and subclasses); objects of this class are encoded through RTF control words in NSCStringText objects. 

- (NSPoint)locationOfCell:(NSCell *)celltab Returns the location of cell. 

- (void)replaceSelWithCell:(NSCell *)celltab Replaces the selection with cell object cell. 

- (void)setLocation:(NSPoint)origintab Sets the origin point of cell. 
ofCell:(NSCell *)cell

Using the Services Menu and the Pasteboard


+ excludeFromServicesMenu:(BOOL)flagtab Controls whether NSCStringText objects can register for services. 

- (BOOL)readSelectionFromPasteboard:(NSPasteboard *)pboard
tab Replaces the selection with data from pasteboard pboard. 

- (id)validRequestorForSendType:(NSString *)sendType 
returnType:(NSString *)returnTypetab Determines which Service menu items are enabled. 

- (BOOL)writeSelectionToPasteboard:(NSPasteboard *)pboard 
types:(NSArray *)typestab Copies the selection to pasteboard pboard.

Setting Tables and Functions 


- (const NSFSM *)breakTabletab Returns the table defining word boundaries. 

- (const unsigned char *)charCategoryTabletab Returns the table defining character categories. 

- (NSCharFilterFunc)charFiltertab Returns the current character filter function. 

- (const NSFSM *)clickTabletab Returns the table defining double-click selection. 

- (NSTextFunc)drawFunctab Returns the current draw function. 

- (const unsigned char *)postSelSmartTabletab Returns cut and paste table for right word boundary. 

- (const unsigned char *)preSelSmartTabletab Returns cut and paste table for left word boundary. 

- (NSTextFunc)scanFunctab Returns the current scan function. 

- (void)setBreakTable:(const NSFSM *)aTabletab Sets the table defining word boundaries. 

- (void)setCharCategoryTable:(const unsigned char *)aTable
tab Sets the table defining character categories used in the word wrap or click tables.

- (void)setCharFilter:(NSCharFilterFunc)aFunction
tab Makes aFunction the character filter function. 

- (void)setClickTable:(const NSFSM *)aTabletab Sets the table defining double-click selection. 

- (void)setDrawFunc:(NSTextFunc)aFunctiontab Makes aFunction the function that draws the text. 

- (void)setPostSelSmartTable:(const unsigned char *)aTable
tab Sets the cut and paste table for right word boundary. 

- (void)setPreSelSmartTable:(const unsigned char *)aTable
tab Sets the cut and paste table for left word boundary. 

- (void)setScanFunc:(NSTextFunc)aFunctiontab Makes aFunction the scan function. 

- (void)setTextFilter:(NSTextFilterFunc)aFunctiontab Makes aFunction the text filter function. 

- (NSTextFilterFunc)textFiltertab Returns the current text filter function. 

Printing 


- (void)adjustPageHeightNew:(float *)newBottomtab Assists with automatic pagination of text. 
top:(float)oldToptab  
bottom:(float)oldBottomtab  
limit:(float)bottomLimit

Implemented by an Embedded Graphic Object 


- (NSSize)cellSizetab Embedded cell returns its size.

- (void)drawWithFrame:(NSRect)cellFrametab Embedded object draws itself, including frame, within
inView:(NSView *)controlViewtab  tab cellFrame in controlView. 

- (void)highlight:(BOOL)flagtab Embedded object highlights or unhighlights itself with
withFrame:(NSRect)cellFrametab  cellFrame of controlView, depending on the value of
inView:(NSView *)controlViewtab  flag.

- (void)readRichText:(NSString *)stringObjecttab  Embedded object reads its RTF representation from
forView:(NSView *)viewtab  tab stringObject and initializes itself.

- (NSString *)richTextForView:(NSView *)viewtab Embedded object stores its RTF representation within view as a string object and returns it.

- (BOOL)trackMouse:(NSEvent *)theEventtab  Embedded object implements this method to track mouse
inRect:(NSRect)cellFrametab  tab movement within tracking rectangle (cellFrame) and to
ofView:(NSView *)controlViewtab  tab detect mouse-up event (untilMouseUp).
untilMouseUp:(BOOL)untilMouseUptab  

Implemented by the Delegate 


- (void)textDidRead:(NSCStringText *)textObjecttab Lets the delegate review paper size.
paperSize:(NSSize)paperSizetab  

- (NSRect)textDidResize:(NSCStringText *)textObject
oldBounds:(NSRect)oldBoundstab  Reports size change to delegate.

- (NSFont *)textWillConvert:(NSCStringText *)textObject
fromFont:(NSFont *)fonttab  Lets delegate intercede in selection's font change. 
toFont:(NSFont *)font

- (void)textWillFinishReadingRichText:(NSCStringText *)textObject
tab Informs delegate that the NSCStringText object finished reading RTF data. 

- (void)textWillResize:(NSCStringText *)textObject
tab Informs delegate of impending size change. 

- (void)textWillSetSel:(NSCStringText *)textObject
toFont:(NSFont *)fonttab Lets delegate intercede in the updating of the Font panel. 

- (void)textWillStartReadingRichText:(NSCStringText *)textObject
tab Informs delegate that NSCStringText object will read RTF data. 

- (NSSize)textWillWrite:(NSCStringText *)textObject
tab Lets the delegate specify paper size. 

Compatibility Methods


- (NSCStringTextInternalState *)cStringTextInternalState
tab Returns a structure that represents the instance variables of the NSCStringText object. The structure is defined in appkit/NSCStringText.h, and in the ªTypes and Constantsº section of the Application Kit documentation. Note that this method is provided for applications that really must depend on changing the values of an NSCStringText object's instance variables. 

These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.