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

Text



Inherits From: View : Responder : Object
Conforms To: NXChangeSpelling
NXIgnoreMisspelledWords
NXReadOnlyTextStream
NXSelectText
Declared In: appkit/Text.h



Class Description

The Text class defines an object that manages text. 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 an NXBrowser.  Your application inherits these uses of the Text class when it incorporates any of these objects into its interface. It can also create Text objects for its own purposes.

The Text 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.  A Text 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.
Write text to, or read it from, an NXStream as either RTF or plain ASCII data.
Display graphic images within its text.
Communicate with other applications through the Services menu.
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 Text objects.
Let the user check the spelling of words in its text.
Let the user control the format of paragraphs by manipulating a ruler.

Interface Builder gives you access to Text objects in several different configurations, such as those found in the TextField, Form, and ScrollView objects in the Palettes window.  These classes configure a Text object for a specific purpose. Additionally, all TextFields, Forms, Buttons 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, use a Text object directly.



Plain and Rich Text Objects

When you create a Text 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 Text instances by sending the Text class object a setDefaultFont: message.  Once a Text object is created, you can alter its global settings using methods such as setFont:, setLineHeight:, setTextGray:, and setAlignment:.  For convenience, such a Text object will be called a plain Text object.

To allow multiple values for these attributes, you must send the Text object a setMonoFont:NO message.  A Text object that allows multiple fonts also allows multiple paragraph formats, line heights, and so on.  For convenience, such a Text object will be called a rich Text object.

A rich Text object can use RTF (Rich Text Format) as an interchange format.  Not all RTF control words are supported:  On input, a Text 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 a Text object recognizes.

Control Word Read Write
\ansi yes (see note below)
\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

Note:  A Text object writes 8-bit characters in the NEXTSTEP encoding, which differs somewhat from the ANSI character set.  See the appendix "Keyboard Event Information" for more details.

In a Text object, each sequence of characters having the same attributes is called a run.  (See the NXRun structure at the end of this class specification for details.)  A plain Text object has only one run for the entire text.  A rich Text object can have multiple runs.  Methods such as setSelFont:, setSelProp:to:, setSelGray:, and alignSelCenter: let you programmatically modify the attributes of the selected sequence of characters in a rich Text object.  As discussed below, the user can set these attributes by using the Font panel and the ruler.

Text 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 Text Object's Delegate

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

textWillResize:
textDidResize:oldBounds:invalid:
textWillChange:
textDidChange:
textWillEnd:
textDidEnd:endChar:
textDidGetKeys:isEmpty:
textWillSetSel:toFont:
textWillConvert:fromFont:toFont:
textWillStartReadingRichText:
textWillFinishReadingRichText:
textWillWrite:paperSize:
textDidRead:paperSize:

So, for example, if the delegate implements the textWillChange: method, it will receive notification upon the user's first attempt to alter the text.  Moreover, depending on the method's return value, the delegate can either allow or prohibit changes to the text.  (See the section titled "Methods Implemented by the Delegate" for more information.)  The delegate can be any object you choose, and one delegate can be used to control multiple Text objects.



Adding Graphics to the Text

A rich Text object allows graphic to be embedded in the text.  Each graphic is treated as a single 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 Cell--to the text.  This object will manage the graphic image by drawing it when appropriate.  Although Cell subclasses are commonly used, the only requirement is that the embedded object responds to these messages (see the section titled "Methods Implemented by an Embedded Graphic Object" for more information):

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

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

A Text object displays a graphic in its text by sending the managing object a drawSelf:inView: message.  To record the graphic to a file or to the pasteboard, the Text object sends the managing object a writeRichText:forView: 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, a Text object must know which class to associate with particular RTF control words.  You associate a control word with a class object by sending the Text class object a registerDirective:forClass: message.  Thereafter, whenever a Text 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 a Text object. The Text object automatically creates an object to manage the display of the image.  This feature requires a rich Text object that has been configured to receive dragged images (see setGraphicsImportEnabled:).

Images that have been imported in this way can be written as RTFD documents, the file format that Edit uses for text that contains images.  (Programmatic creation of RTFD documents is not supported in this release.)  RTFD documents use a file package, or directory, to store the components of the document (the "D" stands for "directory").  (See saveRTFDTo:removeBackup:errorHandler: and openRTFDFrom:.)  The file package has the name of the document plus a ".rtfd" extension.  It always contains a file called TXT.rtf for the text of the document, and one or more TIFF or EPS files for the images.  A Text object can serialize the information in an RTFD document to a stream (see writeRTFDTo:) and deserialize it from a stream (see readRTFDFrom:).



Cooperating with Other Objects and Services

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

If a Text object is a subview of a ScrollView, it can cooperate with the ScrollView to display and update a ruler that displays formatting information.  The ScrollView retiles its subviews to make room for the ruler, and the Text 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, a Text object can make use of facilities outside the scope of its own application.  By default, a Text object registers with the services system that it can send and receive RTF and plain ASCII data.  If the application containing the Text object has a Services menu, a menu item is added for each service provider that can accept or return these formats.  To prevent Text objects from registering for services, send the Text class object an excludeFromServicesMenu:YES message before any Text objects are created.



Instance Variables

const NXFSM *breakTable;

const NXFSM *clickTable;

const unsigned char *preSelSmartTable;

const unsigned char *postSelSmartTable;

const unsigned char *charCategoryTable;

char delegateMethods;

NXCharFilterFunc charFilterFunc;

NXTextFilterFunc textFilterFunc;

NXTextFunc scanFunc;

NXTextFunc drawFunc;

id delegate;

int tag;

DPSTimedEntry cursorTE;

NXTextBlock *firstTextBlock;

NXTextBlock *lastTextBlock;

NXRunArray *theRuns;

NXRun typingRun;

NXBreakArray *theBreaks;

int growLine;

int textLength;

NXCoord maxY;

NXCoord maxX;

NXRect bodyRect;

NXCoord borderWidth;

char clickCount;

NXSelPt sp0;

NXSelPt spN;

NXSelPt anchorL;

NXSelPt anchorR;

float backgroundGray;

float textGray;

float selectionGray;

NXSize maxSize;

NXSize minSize;

struct _tFlags {
unsigned int  changeState:1;
unsigned int  charWrap:1;
unsigned int  haveDown:1;
unsigned int  anchorIs0:1;
unsigned int  horizResizable:1;
unsigned int  vertResizable:1;
unsigned int  overstrikeDiacriticals:1;
unsigned int  monoFont:1;
unsigned int  disableFontPanel:1;
unsigned int  inClipView:1;

} tFlags;

NXStream *textStream;


breakTable A pointer to the finite-state machine table that specifies word and line breaks.
clickTable A pointer to the finite-state machine table that defines word boundaries for double-click selection.
preSelSmartTable A pointer to the table that specifies which characters on the left end of a selection are treated as equivalent to a space.
postSelSmartTable A pointer to the table that specifies which characters at the right end of a selection are treated as equivalent to a space.
charCategoryTable A pointer to the table that maps ASCII characters to character classes.  Entries are premultiplied by the size of a finite-state machine table entry.
delegateMethods A record of the notification methods that the delegate implements.
charFilterFunc The function that checks each character as it's typed into the text.
textFilterFunc The function that checks the text that's being added to the Text object.
scanFunc The function that calculates the line of text.
drawFunc The function that draws the line of text.
delegate The object that's notified when the Text object is modified.
tag The integer that the delegate uses to identify the Text object.
cursorTE The timed-entry number for the vertical bar that marks the insertion point.
firstTextBlock A pointer to the first record in a linked list of text blocks.
lastTextBlock A pointer to the last record in a linked list of text blocks.
theRuns A pointer to the array of format runs.  By default, theRuns points to a single run of the default font.
typingRun The format run to use for the next characters entered.
theBreaks A pointer to the array of line breaks.
growLine The line containing the end of the growing selection.
textLength The number of characters in the Text object.
maxY The bottom of the last line of text.  maxY is measured relative to the origin of the bodyRect.
maxX The widest line of text.  maxX is accurate only after the calcLine method is applied.
bodyRect The rectangle the Text object draws text in.
borderWidth Reserved for future use.
clickCount The number of clicks that created the selection.
sp0 The starting position of the selection.
spN The ending position of the selection.
anchorL The left anchor position.
anchorR The right anchor position.
backgroundGray The background gray value of the text.
textGray The gray value of the text.
selectionGray The gray value of the selection.
maxSize The maximum size of the frame rectangle.
minSize The minimum size of the frame rectangle.
tFlags.changeState True if any changes have been made to the text since the Text object became the first responder.
tFlags.charWrap True if the Text object wraps words whose length exceeds the line length on a character basis.  False if such words are truncated at the end of the line.
tFlags.haveDown True if the left mouse button (or either button if their functions haven't been differentiated) is down.
tFlags.anchorIs0 True if the anchor's position is at sp0.
tFlags.horizResizable True if the Text object's width can grow or shrink.
tFlags.vertResizable True if the Text object's height can grow or shrink.
tFlags.overstrikeDiacriticals Reserved for future use.
tFlags.monoFont True if the Text object uses one font for all its text.
tFlags.disableFontPanel True if the Text object doesn't update the Font panel automatically.
tFlags.inClipView True if the Text object is the subview of a ClipView.
textStream The stream for reading and writing text.



Adopted Protocols

NXChangeSpelling changeSpelling:
NXIgnoreMisspelledWords spellDocumentTag
NXReadOnlyTextStream openTextStream
seekToCharacterAt:relativeTo:
readCharacters:count:
currentCharacterOffset
isAtEOTS
closeTextStream
NXSelectText selectCharactersFrom:to:
selectionCharacterCount
readCharactersFromSelection:count:
makeSelectionVisible



Method Types

Initializing the class object + setDefaultFont:
+ getDefaultFont
+ excludeFromServicesMenu:
+ registerDirective:forClass:
+ initialize
Initializing a new Text object initFrame:
initFrame:text:alignment:
Freeing a Text object free
Modifying the frame rectangle setMaxSize:
getMaxSize:
setMinSize:
getMinSize:
setVertResizable:
isVertResizable
setHorizResizable:
isHorizResizable
sizeTo::
sizeToFit
resizeText::
moveTo::
Laying out the text setMarginLeft:right:top:bottom:
getMarginLeft:right:top:bottom:
getMinWidth:minHeight:maxWidth:maxHeight:
setAlignment:
alignment
alignSelLeft:
alignSelCenter:
alignSelRight:
setSelProp:to:
changeTabStopAt:to:
calcLine
setCharWrap:
charWrap
setNoWrap
setParaStyle:
defaultParaStyle
calcParagraphStyle::
setLineHeight:
lineHeight
setDescentLine:
descentLine
Reporting line and position lineFromPosition:
positionFromLine:
offsetFromPosition:
positionFromOffset:
Setting, reading, and writing the text
setText:
readText:
startReadingRichText
readRichText:
readRichText:atPosition:
readRTFDFrom:
finishReadingRichText
openRTFDFrom:
saveRTFDTo:removeBackup:errorHandler:
writeText:
writeRichText:
writeRichText:from:to:
writeRTFDSelectionTo:
writeRTFDTo:
stream
firstTextBlock
getParagraph:start:end:rect:
getSubstring:start:length:
byteLength
charLength
textLength
Setting editability setEditable:
isEditable
Allowing multiple fonts and paragraph styles
setMonoFont:
isMonoFont
Editing the text copy:
copyFont:
copyRuler:
paste:
pasteFont:
pasteRuler:
cut:
delete:
clear:
selectAll:
selectText:
Managing the selection subscript:
superscript:
unscript:
underline:
showCaret
hideCaret
setSelectable:
isSelectable
selectError
selectNull
setSel::
getSel::
replaceSel:
replaceSel:length:
replaceSel:length:runs:
replaceSelWithRichText:
replaceSelWithRTFD:
scrollSelToVisible
Setting the font setFontPanelEnabled:
isFontPanelEnabled
changeFont:
setFont:
font
setFont:paraStyle:
setSelFont:
setSelFontFamily:
setSelFontSize:
setSelFontStyle:
setSelFont:paraStyle:
Checking spelling checkSpelling:
showGuessPanel:
Managing the ruler toggleRuler:
isRulerVisible
Finding text findText:ignoreCase:backwards:wrap:
Modifying graphic attributes setBackgroundGray:
backgroundGray
setBackgroundColor:
backgroundColor
setSelGray:
selGray
runGray:
setSelColor:
selColor
runColor:
setTextGray:
textGray
setTextColor:
textColor
Reusing a Text object renewFont:text:frame:tag:
renewFont:size:style:text:frame:tag:
renewRuns:text:frame:tag:
windowChanged:
Displaying drawSelf::
setRetainedWhileDrawing:
isRetainedWhileDrawing
Assigning a tag setTag:
tag
Handling event messages acceptsFirstResponder
becomeFirstResponder
resignFirstResponder
becomeKeyWindow
resignKeyWindow
mouseDown:
keyDown:
moveCaret:
Handling graphics within the text
+ registerDirective:forClass:
replaceSelWithCell:
setLocation:ofCell:
getLocation:ofCell:
setGraphicsImportEnabled:
isGraphicsImportEnabled
Using the Services menu + excludeFromServicesMenu:
validRequestorForSendType:andReturnType:
readSelectionFromPasteboard:
writeSelectionToPasteboard:types:
Setting tables and functions setCharFilter:
charFilter
setTextFilter:
textFilter
setBreakTable:
breakTable
setPreSelSmartTable:
preSelSmartTable
setPostSelSmartTable:
postSelSmartTable
setCharCategoryTable:
charCategoryTable
setClickTable:
clickTable
setScanFunc:
scanFunc
setDrawFunc:
drawFunc
Printing adjustPageHeightNew:top:bottom:limit:
Archiving read:
write:
Assigning a delegate setDelegate:
delegate



Class Methods

excludeFromServicesMenu:
+ excludeFromServicesMenu:(BOOL)flag

Controls whether Text objects will communicate with interapplication services through the Services menu.  By default, as each new Text instance is initialized, it registers with the Application object that it's capable of sending and receiving the pasteboard types identified by NXAsciiPboardType and NXRTFPboardType.  If you want to prevent Text objects in your application from registering for services that can receive and send these types, send the Text class object an excludeFromServicesMenu:YES message.  If, for example, your application displays text but doesn't have editable text fields, you might use this method.

Send an excludeFromServicesMenu: message early in the execution of your application, either before sending the Application object a run message or in the Application delegate's appWillInit: method.  Returns self.

See also:  validRequestorForSendType:andReturnType:, registerServicesMenuSendTypes:andReturnTypes: (Application)



getDefaultFont
+ getDefaultFont

Returns the Font object that corresponds to the Text object's default.  Unless you've changed the default font by sending a setDefaultFont: message, or taken advantage of the NXFont parameter using defaults, getDefaultFont returns a Font object for a 12-point Helvetica font with a flipped font matrix.

See also:  + setDefaultFont:, setFont:



initialize
+ initialize

Initializes the class object.  The initialize message is sent for you before the class object receives any other message; you never send an initialize message directly.  Returns self.

See also:  + initialize (Object)



registerDirective:forClass:
+ registerDirective:(const char *)directive forClass:class

Creates an association in the Text class object between the RTF control word directive and class, a class object.  Thereafter, when a Text 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 a Text object is writing RTF data to a stream and encounters an object of the class class, the Text object sends the object a writeRichText:forView: message to let it record its representation in the RTF text.  Thus, this method is instrumental in enabling a Text object to read, display, and write an image within a text stream.

An object of the class 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 Graphic Object" for more information on these methods.

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

See also:  replaceSelWithCell:



setDefaultFont:
+ setDefaultFont:anObject

Sets the default font for the Text class object.  The argument passed to this method is the id of the Font object for the desired font.  Since a Text object uses a flipped coordinate system, make sure the Font object you specify uses a matrix that flips the y-axis of the characters.  Returns anObject.

See also:  + getDefaultFont, setLineHeight:, + newFont:size: (Font)



Instance Methods

acceptsFirstResponder
(BOOL)acceptsFirstResponder

Assuming the text is selectable, returns YES to let the Text object become the first responder; otherwise, returns NO. acceptsFirstResponder messages are sent for you; you never send them yourself.

See also:  setSelectable:, setDelegate:, resignFirstResponder



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.



alignment
(int)alignment

Returns a value indicating the default alignment of the text.  The returned value is equal to one of these constants:

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.

See also:  setAlignment:



alignSelCenter:
alignSelCenter:sender

Sets the paragraph style of one or more paragraphs so that text is centered between the left and right margins.  For a plain Text object, all paragraphs are affected.  For a rich Text object, only those paragraphs marked by the selection are affected.  The sending object passes its id as part of the alignSelCenter: message.  The text is rewrapped and redrawn.  Returns self.

See also:  alignSelLeft:, alignSelRight:, setSelProp:to:, setMonoFont:



alignSelLeft:
alignSelLeft:sender

Sets the paragraph style of one or more paragraphs so that text is aligned to the left margin.  For a plain Text object, all paragraphs are affected.  For a rich Text object, only those paragraphs marked by the selection are affected.  The sending object passes its id as part of the alignSelLeft: message.  The text is rewrapped and redrawn.  Returns self.

See also:  alignSelCenter:, alignSelRight:, setSelProp:to:, setMonoFont:



alignSelRight:
alignSelRight:sender

Sets the paragraph style of one or more paragraphs so that text is aligned to the right margin.  For a plain Text object, all paragraphs are affected.  For a rich Text object, only those paragraphs marked by the selection are affected.  The sending object passes its id as part of the alignSelRight: message.  The text is rewrapped and redrawn.  Returns self.

See also:  alignSelCenter:, alignSelLeft:, setSelProp:to:, setMonoFont:



backgroundColor
(NXColor)backgroundColor

Returns the color used to draw the text's background on color displays.

See also:  setBackgroundGray:, backgroundGray:, setBackgroundColor:, setTextGray:, textGray, setTextColor:, textColor, setSelGray:, selGray, setSelColor:



backgroundGray
(float)backgroundGray

Returns the gray value used to draw the text's background on monochrome displays.

See also:  setBackgroundGray:, setBackgroundColor:, backgroundColor, setTextGray:, textGray, setTextColor:, textColor, setSelGray:, selGray, setSelColor:



becomeFirstResponder
becomeFirstResponder

Lets the Text object know that it's becoming the first responder.  By default, the Text object always accepts becoming first responder.  becomeFirstResponder messages are sent for you; you never send them yourself.  Returns self.

See also:  setDelegate:, acceptsFirstResponder, selectError



becomeKeyWindow
becomeKeyWindow

Activates the caret if it exists.  becomeKeyWindow messages are sent by an application's Window object, which, upon receiving a mouse-down event, sends a becomeKeyWindow message to the first responder.  You should never directly send this message to a Text object.  Returns self.

See also:  showCaret, hideCaret, becomeKeyWindow (Window)



breakTable
(const NXFSM *)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:



byteLength
(int)byteLength

Returns the number of bytes used by the characters in the receiving Text object.  The number doesn't include the null terminator (`\0') that getSubstring:start:length: returns if you ask for all the text in a Text object.

In a standard Text object, the number of bytes is equal to the number of characters (thus, this method would return the same value as charLength or textLength).  Subclasses of Text that use more than one byte per character should override this method to return the number of bytes used to store the text.

See also:  charLength, textLength, getSubstring:start:length:



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: readText:
read: renewFont:size:style:text:frame:tag:
renewFont:text:frame:tag: setFont:
renewRuns:text:frame:tag: setParaStyle:
setFont:paraStyle: setText:

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:  readText:, renewRuns:text:frame:tag:



calcParagraphStyle::
(void *)calcParagraphStyle:fontId :(int)alignment

Recalculates the default paragraph style given the Font's fontId and alignment.  The Text object sends this message for you after its font has been changed; you will rarely need to send a calcParagraphStyle:: message directly.  Returns a pointer to an NXTextStyle structure that describes the default style.

See also:  defaultParaStyle



changeFont:
changeFont:sender

Changes the font of the selection for a rich Text object.  It changes the font for the entire Text object for a plain Text object. sender must respond to the convertFont: message.

If the Text object's delegate implements the method, it receives a textWillConvert:fromFont:toFont: notification message for each text run that's about to be converted.

See also:  setFontPanelEnabled:



changeTabStopAt:to:
changeTabStopAt:(NXCoord)oldX to:(NXCoord)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:  setMonoFont:, 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
(NXCharFilterFunc)charFilter

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

See also:  setCharFilter:



charLength
(int)charLength

Returns the number of characters in a Text object.  The length doesn't include the null terminator (`\0') that getSubstring:start:length: returns if you ask for all the text in a Text object.  The charLength and textLength methods are identical; the related method byteLength returns the length of the text in bytes, which, depending on the number of bytes used to store a character, may return a larger value.

See also:  byteLength, textLength, getSubstring:start:length:



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:



checkSpelling:
checkSpelling:sender

Searches for a misspelled word in the text of the receiving Text object.  The search starts at the current selection and continues until it reaches a word suspected of being misspelled or the end of the text.  If a word isn't recognized by the spelling server or listed in the user's local dictionary in ~/.NeXT/LocalDictionary, it's highlighted.  A showGuessPanel: message will then display the Guess panel and allow the user to make a correction or add the word to the local dictionary.  Returns self.

See also:  showGuessPanel:



clear:
clear:sender

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

See also:  delete:



clickTable
(const NXFSM *)clickTable

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

See also:  setClickTable:



copy:
copy:sender

Copies the selected text from the Text object to the selection pasteboard.  The selection remains unchanged.  The pasteboard receives the text and its corresponding run information.  The pasteboard types used are NXAsciiPboardType and NXRTFPboardType.

The sender passes its id as part of the copy: message.  Returns self.

See also:  cut:, paste:, delete:, copyFont:, pasteFont:, copyRuler:, pasteRuler:



copyFont:
copyFont:sender

Copies font information for the selected text to the font pasteboard.  If the selection spans more than one font, the information copied is that of the first font in the selection.  The selection remains unchanged.  The pasteboard type used is NXFontPboardType.

The sender passes its id as the argument of the copyFont: message.  Returns self.

See also:  pasteFont:, copyRuler:, pasteRuler:, copy:, cut:, paste:, delete:



copyRuler:
copyRuler:sender

Copies ruler information for the paragraph containing the selection to the ruler pasteboard.  The selection expands to paragraph boundaries.

The ruler controls a paragraph's text alignment, tab settings, and indentation.  If the selection spans more than one paragraph, the information copied is that of the first paragraph in the selection.  The pasteboard type used is NXRulerPboardType.

Once copied to the pasteboard, ruler information can be pasted into another object or application that's able to paste RTF data into its document.

The sender passes its id as the argument of the copyRuler: message.  Returns self.

See also:  pasteRuler:, copyFont:, pasteFont:, copy:, cut:, paste:, delete:



cut:
cut:sender

Copies the selected text to the pasteboard and then deletes it from the Text object.  The pasteboard receives the text and its corresponding font information.

If the Text object's delegate implements the method, it receives a textDidGetKeys:isEmpty: message immediately after the cut operation.  If this is the first change since the Text object became the first responder (and the delegate implements the method), a textDidChange: message is also sent to the delegate.

The sender passes its id as part of the cut: message.  Returns self.

See also:  copy:, paste:, delete:, textDidGetKeys:isEmpty:, textDidChange:



defaultParaStyle
(void *)defaultParaStyle

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 setParaStyle:, setAlignment:, setLineHeight:, and setDescentLine:.

See also:  setParaStyle:, setAlignment:, setLineHeight:, setDescentLine:



delegate
delegate

Returns the Text object's delegate.

See also:  setDelegate:



delete:
delete:sender

Deletes the selection without adding it to the pasteboard.  The sender passes its id as part of the delete: message.

If the Text object's delegate implements the method, it receives a textDidGetKeys:isEmpty: message immediately after the delete operation.  If this is the first change since the Text object became the first responder (and the delegate implements the method), a textDidChange: message is also sent to the delegate.

The delete: method replaces clear:.  Returns self.

See also:  cut:, copy:, paste:, textDidGetKeys:isEmpty:, textDidChange:



descentLine
(NXCoord)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
(NXTextFunc)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:



drawSelf::
drawSelf:(const NXRect *)rects :(int)rectCount

Draws the Text object.  You never send a drawSelf:: message directly, although you may want to override this method to change the way a Text object draws itself.  Returns self.

See also:  drawSelf:: (View)



findText:ignoreCase:backwards:wrap:
(BOOL)findText:(const char *)string
ignoreCase:(BOOL)ignoreCaseflag
backwards:(BOOL)backwardsflag
wrap:(BOOL)wrapflag

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
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
(NXTextBlock *)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.

See also:  getSubstring:start:length:, stream



font
font

Returns the Font object for a plain Text object.  For rich Text objects, the Font object for the first text run is returned.

See also:  setFont:



free
free

Releases the storage for a Text object.

See also:  free (View)



getLocation:ofCell:
getLocation:(NXPoint *)origin ofCell:cell

Places the x and y coordinates of cell in the NXPoint structure specified by origin.  The coordinates are in the Text object's coordinate system.  cell is a Cell object that's displayed as part of the text.

Returns nil if the Cell object isn't part of the text; otherwise, returns self.

See also:  replaceSelWithCell:, setLocation:ofCell:, calcCellSize: (Cell)



getLocation:ofView:

Unimplemented.



getMarginLeft:right:top:bottom:
getMarginLeft:(NXCoord *)leftMargin
right:(NXCoord *)rightMargin
top:(NXCoord *)topMargin
bottom:(NXCoord *)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:



getMaxSize:
getMaxSize:(NXSize *)theSize

Copies the maximum size of the Text object into the structure referred to by theSize. Returns self.

See also:  setMaxSize:, getMinSize:



getMinSize:
getMinSize:(NXSize *)theSize

Copies the minimum size of the Text object into the structure referred to by theSize.  Returns self.

See also:  setMinSize:, getMaxSize:



getMinWidth:minHeight:maxWidth:maxHeight:
getMinWidth:(NXCoord *)width
minHeight:(NXCoord *)height
maxWidth:(NXCoord)widthMax
maxHeight:(NXCoord)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.

See also:  sizeToFit



getParagraph:start:end:rect:
getParagraph:(int)prNumber
start:(int *)startPos
end:(int *)endPos
rect:(NXRect *)paragraphRect

Copies the positions of the first and last characters of the specified paragraph to the addresses startPos and endPos.  It also copies the paragraph's bounding rectangle into the structure referred to by paragraphRect.  A paragraph ends in a Return character; the first paragraph is paragraph 0, the second is paragraph 1, and so on.  Returns self.

See also:  getSubstring:start:length:, firstTextBlock



getSel::
getSel:(NXSelPt *)start :(NXSelPt *)end

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

See also:  setSel::



getSubstring:start:length:
(int)getSubstring:(char *)buf
start:(int)startPos
length:(int)numChars

Copies a substring of the text to a specified memory location.  The substring is specified by startPos and numCharsstartPos is the position of the first character of the substring; numChars is the number of characters to be copied.  buf is the starting address of the memory location for the substring.  getSubstring:start:length: returns the number of characters actually copied.  This number may be less than numChars if the last character position is less than startPos + numChars.  Returns 1 if startPos is beyond the end of the text.

getSubstring:start:length: appends a null terminator (`\0') to the substring only if the requested substring includes the end of the Text object's text.

See also:  textLength, getSel::



hideCaret
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



initFrame:
initFrame:(const NXRect *)frameRect

Initializes a new Text object.  This method invokes the initFrame:text:alignment: method with the size and location specified by frameRect.  Text alignment is set to NX_LEFTALIGNED.  Returns self.

See also:  initFrame:text:alignment:



initFrame:text:alignment:
initFrame:(const NXRect *)frameRect
text:(const char *)theText
alignment:(int)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:  initFrame:



isEditable
(BOOL)isEditable

Returns YES if the text can be edited, NO if not.  The default value is YES.

See also:  isSelectable, setDelegate:



isFontPanelEnabled
(BOOL)isFontPanelEnabled

Returns YES if the Text object will respond to the Font panel, NO if not.  The default value is YES.

See also:  setFontPanelEnabled:



isGraphicsImportEnabled
(BOOL)isGraphicsImportEnabled

Returns YES if the Text object will import TIFF and EPS images dragged into it by the user.  The default value is NO.

See also:  setGraphicsImportEnabled:



isHorizResizable
(BOOL)isHorizResizable

Returns YES if the text can automatically change size horizontally, NO if not.  The default value is NO.

See also:  setVertResizable:, isVertResizable, setHorizResizable:



isMonoFont
(BOOL)isMonoFont

Returns YES if the Text object permits only one font and paragraph style for its text, NO if not.  The default value is YES.

See also:  setMonoFont:



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:, drawSelf::



isRulerVisible
(BOOL)isRulerVisible

Returns YES if the ruler is visible in the Text object's superview, a ScrollView; otherwise, returns NO.

See also:  toggleRuler:



isSelectable
(BOOL)isSelectable

Returns YES if the text can be selected, NO if not.  The default value is YES.

See also:  isEditable, setDelegate:



isVertResizable
(BOOL)isVertResizable

Returns YES if the text can automatically change size vertically, NO if not.  The default value is NO.

See also:  setVertResizable:, setHorizResizable:, isHorizResizable



keyDown:
keyDown:(NXEvent *)theEvent

Analyzes key-down events received by the Text object.  keyDown: first uses the Text object's character filter function to determine whether the event should be interpreted as a command to move the cursor or as a command to end the Text object's status as the first responder.  If the latter, the Text object's delegate is given an opportunity to prevent the change.

If the event represents a character that should be added to the text, the Text object sets up a modal event loop to process it along with other key-down events as they're received.  The text is redrawn, and then keyDown: notifies the delegate that the text has changed.  This message is sent by the system in response to keyboard events.  You never send this message, though you may want to override it.

See also:  setCharFilter:, setDelegate:, getNextEvent:waitFor: (Application)



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:, stream



lineHeight
(NXCoord)lineHeight

Returns the default line height for the Text object.

See also:  setLineHeight:



mouseDown:
mouseDown:(NXEvent *)theEvent

Responds to mouse-down events.  When a Text object that allows selection receives a mouseDown: message, it tracks mouse-dragged events and responds by adjusting the selection and autoscrolling, if necessary.  You never send this message, though you may want to override it.

See also:  setEditable:, setDelegate:, getNextEvent:waitFor: (Application)



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



moveTo::
moveTo:(NXCoord)x :(NXCoord)y

Moves the origin of the Text object's frame rectangle to (x, y) in its superview's coordinates.  Returns self.

See also:  moveTo:: (View)



offsetFromPosition:
(int)offsetFromPosition:(int)charPosition

Returns the byte offset corresponding to the character position charPosition in the Text object's text.  In the standard software release, where each character is represented by a byte, a character's position and its byte offset are identical.

See also:  positionFromOffset:, positionFromLine:, lineFromPosition:



openRTFDFrom:
(NXRTFDError)openRTFDFrom:(const char *)path

Opens the RTFD file package specified by path.  The last element in the path must be the name of the RTFD directory--for example, "/tmp/MyFile.rtfd"--not the name of the RTF document within the directory.  On success, the Text object's contents are replaced with the text and images found in the file package, and the new contents are displayed.

See also:  readRTFDFrom:, replaceSelWithRTFD:, writeRTFDSelectionTo:, writeRTFDTo:



paste:
paste:sender

Places the contents of the selection pasteboard into the Text object at the position of the current selection.  If the selection is zero-width, the text is inserted at the caret.  If the selection has positive width, the selection is replaced by the contents of the pasteboard.  In either case, the text is rewrapped and redrawn.

Before the paste operation, a textDidChange: message is sent to the delegate, assuming that this is the first change since the Text object became the first responder and that the delegate implements the method.  After the paste operation, the delegate receives a textDidGetKeys:isEmpty: message, if it implements the method.

sender is the id of the sending object.  paste: returns nil if the pasteboard can provide neither NXAsciiPboardType nor NXRTFPboardType format types; otherwise, returns self.

See also:  copy:, cut:, delete:, copyFont:, copyRuler:, pasteFont:, pasteRuler:, textDidGetKeys:isEmpty:, textDidChange:



pasteFont:
pasteFont:sender

Takes font information from the font pasteboard and applies it to the current selection.  If the selection is zero-width, only those characters subsequently entered at the insertion point are affected.

pasteFont: works only with rich Text objects (see setMonoFont:).  Attempting to paste a font into a plain Text object generates a system beep without altering any fonts.

Before the paste operation, a textDidChange: message is sent to the delegate, assuming that this is the first change since the Text object became the first responder and that the delegate implements the method.  After the paste operation, the delegate receives a textDidGetKeys:isEmpty: message, if it implements the method.

sender is the id of the sending object.  After the font is pasted, the text is rewrapped and redrawn.  pasteFont: returns nil if the pasteboard has no data of the type NXFontPboardType; otherwise, returns self.

See also:  copyFont:, copyRuler:, pasteRuler:, copy:, cut:, delete:, paste:, setMonoFont:, textDidGetKeys:isEmpty:, textDidChange:



pasteRuler:
pasteRuler:sender

Takes ruler information from the ruler pasteboard and applies it to the paragraph or paragraphs marked by the current selection. The ruler controls a paragraph's text alignment, tab settings, and indentation.

pasteRuler: works only with rich Text objects (see setMonoFont:).  Attempting to paste a ruler into a plain Text object generates a system beep without altering any ruler settings.

Before the paste operation, a textDidChange: message is sent to the delegate, assuming that this is the first change since the Text object became the first responder and that the delegate implements the method.  After the paste operation, the delegate receives a textDidGetKeys:isEmpty: message, if it implements the method.

sender is the id of the sending object.  After the ruler is pasted, the text is rewrapped and redrawn.  If the ruler is visible, it's also updated.  pasteRuler: returns nil if the pasteboard has no data of the type NXRulerPboardType; otherwise, returns self.

See also:  copyRuler:, copyFont:, pasteFont:, copy:, cut:, delete:, paste:, setMonoFont:- textDidGetKeys:isEmpty:, - textDidChange:



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:, stream



positionFromOffset:
(int)positionFromOffset:(int)offset

Returns the character position corresponding to a byte offset into the Text object's text.  The character position is determined by counting characters from the beginning of the Text object, with the first character designated as 0.  In the standard software release, where each character is represented by a byte, a character's position and its byte offset are identical.

See also:  offsetFromPosition:, positionFromLine:, lineFromPosition:



postSelSmartTable
(const unsigned char *)postSelSmartTable

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



preSelSmartTable
(const unsigned char *)preSelSmartTable

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

See also:  setPreSelSmartTable:, setPostSelSmartTable:, postSelSmartTable



read:
read:(NXTypedStream *)stream

Reads the Text object in from the typed stream stream.  A read: message is sent in response to archiving; you never send this message directly.  Returns self.



readRichText:
readRichText:(NXStream *)stream

Reads RTF text from stream into the Text object and formats the text accordingly.  The Text object is resized to be large enough for all the text to be visible.  Returns self.

See also:  writeRichText:



readRichText:atPosition:
readRichText:(NXStream *)stream atPosition:(int)position

Reads RTF text from stream into the Text object's text at position and formats the text accordingly.  You never send this message, but may want to override it to read special RTF directives while the Text object is reading RTF data.  Returns self.



readRTFDFrom:
readRTFDFrom:(NXStream *)stream

Reads the RTFD data contained in stream.  The Text object's contents are replaced with the text and images found in the stream, and the new contents are displayed.  Returns self if the data is successfully read from the stream; otherwise, returns nil.

See also:  openRTFDFrom:, replaceSelWithRTFD:, writeRTFDSelectionTo:, writeRTFDTo:



readSelectionFromPasteboard:
readSelectionFromPasteboard: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:, validRequestorForSendType:andReturnTypes:



readText:
readText:(NXStream *)stream

Reads new text into the Text object from stream.  All previous text is deleted.  The Text object wraps and redraws the new text if autodisplay is enabled.  This method doesn't affect the object's frame or bounds rectangle.  To resize the text rectangle to make the text entirely visible, use the sizeToFit method.  Returns self.  This method raises an NX_textBadRead exception if an error occurs while reading from stream.

See also:  setSel::, setText:, readRichText:, sizeToFit



renewFont:size:style:text:frame:tag:
renewFont:(const char *)newFontName
size:(float)newFontSize
style:(int)newFontStyle
text:(const char *)newText
frame:(const NXRect *)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:, setText:



renewFont:text:frame:tag:
renewFont:newFontId
text:(const char *)newText
frame:(const NXRect *)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.

See also:  setText:



renewRuns:text:frame:tag:
renewRuns:(NXRunArray *)newRuns
text:(const char *)newText
frame:(const NXRect *)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.

See also:  setText:



replaceSel:
replaceSel:(const char *)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:
replaceSel:(const char *)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:
replaceSel:(const char *)aString
length:(int)length
runs:(NXRunArray *)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 replaceSelWithRichText:.

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

See also:  replaceSel:, replaceSelWithRichText:



replaceSelWithCell:
replaceSelWithCell:cell

Replaces the current selection with the image provided by cell.  This method works only with rich Text objects.  (See setMonoFont:.)

The image is treated like a single character.  Its height and width are determined by sending the Cell a calcCellSize: 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:  setMonoFont:, calcCellSize: (Cell), drawSelf:inView: (Cell)



replaceSelWithRichText:
replaceSelWithRichText:(NXStream *)stream

Replaces the current selection with RTF data from stream, assuming the Text object accepts rich text (see setMonoFont:).  A replaceSelWithRichText: message is sent in response to pasting RTF data from the pasteboard.

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

See also:  replaceSel:, replaceSel:length:runs:, replaceSelWithRTFD:



replaceSelWithRTFD:
replaceSelWithRTFD:(NXStream *)stream

Replaces the current selection with RTFD data from stream, assuming the Text object accepts rich text (see setMonoFont:). A replaceSelWithRTFD: message is sent in response to pasting RTFD data from the pasteboard.

After replacing the selection, this method rewraps and redisplays the text.  On error replaceSelWithRTFD: returns nil; otherwise, returns self.

See also:  replaceSel:, replaceSel:length:runs:, replaceSelWithRichText:



replaceSelWithView:

Unimplemented.



resignFirstResponder
resignFirstResponder

Asks the Text object's delegate for permission before letting the Text object cease being the first responder.  If the delegate's textWillEnd: method returns a nonzero value, the Text object remains the first responder, the entire text becomes the selection, and this method returns nil.  Otherwise, resignFirstResponder returns self.

resignFirstResponder messages are sent for you; you never send them yourself.

See also:  setDelegate:, acceptsFirstResponder, selectError



resignKeyWindow
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.

See also:  becomeKeyWindow



resizeText::
resizeText:(const NXRect *)oldBounds :(const NXRect *)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:
(NXColor)runColor:(NXRun *)run

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

See also:  runGray:



runGray:
(float)runGray:(NXRun *)run

Returns the gray value for the specified text run.  By definition, a run can have no more than one gray value.

See also:  runColor:



saveRTFDTo:removeBackup:errorHandler:
(NXRTFDError)saveRTFDTo:(const char *)path
removeBackup:(BOOL)flag
errorHandler:handler

Saves the contents (text and images) of the Text object to the file package specified by path, for example, /text/Document.rtfd. The text and images are saved in separate files within the file package, with the text file being named TXT.rtf.

The save operation proceeds in several steps:  First, the document in memory is saved to a temporary file package (using the above example, /text/Document.rtfd#).  Second, the earlier version of the document--if one exists--is renamed as the backup (/text/Document.rtfd becomes /text/Document.rtfd~).  Then, the temporary file package is renamed (/text/Document.rtfd# becomes /text/Document.rtfd).  Finally, if flag is YES, the backup is deleted.

handler is an error handling object that implements the attemptOverwrite: method (see the NXRTFDErrorHandler protocol specification for details).  If the user doesn't have search permission for a component of path, an attemptOverwrite: message is sent to the error handler.  If the error handler returns YES, the Text object will attempt to write the file; otherwise, the save operation is aborted.

This method returns a value indicating its success or the reason for its failure:

Return Values

NX_RTFDErrorNone
NX_RTFDErrorSaveAborted,
NX_RTFDErrorUnableToWriteFile,
NX_RTFDErrorUnableToCloseFile,
NX_RTFDErrorUnableToCreatePackage,
NX_RTFDErrorUnableToCreateBackup,
NX_RTFDErrorUnableToDeleteBackup,
NX_RTFDErrorUnableToDeleteTemp,
NX_RTFDErrorUnableToDeleteOriginal,
NX_RTFDErrorFileDoesntExist,
NX_RTFDErrorUnableToReadFile,
NX_RTFDErrorInsufficientAccess,
NX_RTFDErrorMalformedRTFD

See also:  openRTFDFrom:, readRTFDFrom:, writeRTFDTo:



scanFunc
(NXTextFunc)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
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
(NXColor)selColor

Returns the color of the selected text.

See also:  setSelColor:, setSelGray:, setBackgroundGray:, backgroundGray, setTextGray:, textGray



selectAll:
selectAll:sender

Attempts to make a Text object the first responder and, if successful, selects all of its text.  This method is identical to selectText:.  Returns self.

See also:  selectError, selectText:, setSel::



selectError
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 setSel::.  Returns self.

See also:  setSel::, setDelegate:, selectAll:



selectNull
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:  setSel::, selectError, selectAll:, getSel::



selectText:
selectText: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:  selectAll:, setSel::



selGray
(float)selGray

Returns the gray value of the selected text.

See also:  setSelGray:, setBackgroundGray:, backgroundGray, setTextGray:, textGray



setAlignment:
setAlignment:(int)mode

Sets the default alignment for the text.  mode can have these values (NX_LEFTALIGNED is the default):

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.

setAlignment: doesn't rewrap or redraw the text.  Send a calcLine message if you want the text rewrapped and redrawn after you reset the alignment.  Returns self.

See also:  alignment, calcLine, alignSelLeft:, alignSelCenter:, alignSelRight:



setBackgroundColor:
setBackgroundColor:(NXColor)color

Sets color as the background color for the Text object.  color is an NXColor structure as defined in appkit/color.h.  If the Text object's window and screen allow it, this color is displayed the next time the text is redrawn; if not, the background gray is displayed instead.  A setBackgroundColor: message doesn't cause the text to be redrawn.  Returns self.

See also:  setBackgroundGray:, backgroundGray:, backgroundColor, setTextGray:, textGray, setTextColor:, textColor, setSelGray:, selGray, setSelColor:



setBackgroundGray:
setBackgroundGray:(float)value

Sets the gray value for the background of the text when the Text object is displayed on a monochrome device.  value should lie in the range from 0.0 (indicating black) to 1.0 (indicating white).  To specify one of the four pure shades of gray, use one of these constants:

Constant Shade
NX_WHITE White
NX_LTGRAY Light gray
NX_DKGRAY Dark gray
NX_BLACK Black

A setBackgroundGray: message doesn't cause the text to be redrawn.  Returns self.

See also:  backgroundGray:, setBackgroundColor:, backgroundColor, setTextGray:, textGray, setTextColor:, textColor, setSelGray:, selGray, setSelColor:



setBreakTable:
setBreakTable:(const NXFSM *)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:
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:
setCharFilter:(NXCharFilterFunc)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:
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:
setClickTable:(const NXFSM *)aTable

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

See also:  clickTable



setDelegate:
setDelegate:anObject

Sets the Text object's delegate.  In response to user input, the Text object can send the delegate any of several notification messages.  See the introduction to this class specification for more information.  Returns self.

See also:  delegate, acceptsFirstResponder, resignFirstResponder



setDescentLine:
setDescentLine:(NXCoord)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:
setDrawFunc:(NXTextFunc)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:



setEditable:
setEditable:(BOOL)flag

Sets whether the text can be edited.  If flag is YES, the text is editable; if NO, the text is read-only.  By default, text is editable.

Use setEditable: if you don't expect the text's edit status to change.  If your application needs to change the text's edit status repeatedly, have the text's delegate implement the appropriate notification methods (see setDelegate:).  Returns self.

See also:  isEditable, setDelegate:



setFont:
setFont:fontObj

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

See also:  setFont:paraStyle:, setSelFont:



setFont:paraStyle:
setFont:fontObj paraStyle:(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:  setFont:, setSelFont:, setParaStyle:



setFontPanelEnabled:
setFontPanelEnabled:(BOOL)flag

This sets whether the Text object will respond to the changeFont: message issued by the Font panel.  If enabled, the Text object will allow the user to change the font of the selection for a rich Text object.  For a plain Text object, the font for the entire text is changed.  If enabled, the Text object also updates the Font panel's font selection information.  Returns self.

See also:  isFontPanelEnabled



setGraphicsImportEnabled:
setGraphicsImportEnabled:(BOOL)flag

Sets whether the Text object will import TIFF and EPS images dragged into it by the user.  By default, Text objects refuse to import such images.

See also:  isGraphicsImportEnabled



setHorizResizable:
setHorizResizable:(BOOL)flag

Sets whether the text can change size horizontally.  If flag is YES, the Text object's frame rectangle can change in the horizontal dimension in response to additions or deletions of text; if NO, it can't.  By default, the Text object can't change size. Returns self.

See also:  setVertResizable:, isVertResizable, isHorizResizable



setLineHeight:
setLineHeight:(NXCoord)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:
setLocation:(NXPoint *)origin ofCell: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:  getLocation:ofCell:, replaceSelWithCell:



setMarginLeft:right:top:bottom:
setMarginLeft:(NXCoord)leftMargin
right:(NXCoord)rightMargin
top:(NXCoord)topMargin
bottom:(NXCoord)bottomMargin

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

See also:  getMarginLeft:right:top:bottom:



setMaxSize:
setMaxSize:(const NXSize *)newMaxSize

Sets the maximum size of a Text object.  This maximum size is ignored if the Text object can't be resized.  The default maximum size is {0.0, 0.0}.  Returns self.

See also:  getMaxSize:, setMinSize:



setMinSize:
setMinSize:(const NXSize *)newMinSize

Sets the minimum size of the receiving Text object.  This size is ignored if the Text object can't be resized.  The default minimum size is {0.0, 0.0}.  Returns self.

See also:  getMinSize:, setMaxSize:



setMonoFont:
setMonoFont:(BOOL)flag

Sets whether the receiving Text object uses one font and paragraph style for the entire text.  By default, a Text object allows only one font and paragraph style.  Messages to set the font, line height, text alignment, and so on affect the entire text of such Text objects.  Text pasted into such Text objects assume their current font and alignment characteristics.  A Text object in this state is called a plain Text object.

By sending a setMonoFont:NO message, multiple fonts and paragraph styles can be displayed in a Text object.  Thereafter, font changes affect only the selected text, and paragraph style changes affect only the paragraph or paragraphs marked by the selection.  The font and alignment characteristics of pasted text are maintained.  A Text object in this state is called a rich Text object.  Returns self.

See also:  isMonoFont, alignSelLeft:, setSelProp:to:, setFontPanelEnabled:



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



setParaStyle:
setParaStyle:(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:, setFont:paraStyle:, setSelFont:



setPostSelSmartTable:
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:
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:
setRetainedWhileDrawing:(BOOL)flag

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¦:: 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, drawSelf::



setScanFunc:
setScanFunc:(NXTextFunc)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:



setSel::
setSel:(int)start :(int)end

Makes the Text object the first responder and then selects and highlights a portion of the text.  start is the first character position of the selection; end is the last character position of the selection.  To create an empty selection, start must equal end.  Use setSel:: to select a portion of the text programmatically.  Returns self.

See also:  selectAll:, selectError, selectNull, getSel::



setSelColor:
setSelColor:(NXColor)color

Sets the text color of the selected text, assuming the Text object allows more than one paragraph style and font (see setMonoFont:).  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.

See also:  setBackgroundGray:, backgroundGray:, setBackgroundColor:, backgroundColor, setTextGray:, textGray, setTextColor:, textColor, setSelGray:, selGray



setSelectable:
setSelectable:(BOOL)flag

Sets whether the text can be selected.  By default, text is selectable.  Returns self.

See also:  isSelectable, setEditable:



setSelFont:
setSelFont:fontId

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

See also:  setSelFontSize:, setSelFontStyle:, setFont:



setSelFont:paraStyle:
setSelFont:fontID paraStyle:(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:
setSelFontFamily:(const char *)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:
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:, setFont:



setSelFontStyle:
setSelFontStyle:(NXFontTraitMask)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:, setFont:



setSelGray:
setSelGray:(float)value

Sets the gray value of the selected text, assuming the Text object allows more than one paragraph style and font (see setMonoFont:).  Otherwise, setSelGray: sets the gray value for the entire text.  value should lie in the range 0.0 (indicating black) to 1.0 (indicating white).  To specify one of the four pure shades of gray, use one of these constants:

Constant Shade
NX_WHITE White
NX_LTGRAY Light gray
NX_DKGRAY Dark gray
NX_BLACK Black

After the gray value is set, the text is redisplayed.  Returns self.

See also:  setBackgroundGray:, backgroundGray:, setBackgroundColor:, backgroundColor, setTextGray:, textGray, setTextColor:, textColor, selGray, setSelColor:



setSelProp:to:
setSelProp:(NXParagraphProp)prop to:(NXCoord)val

Sets the paragraph style for one or more paragraphs.  For a plain Text object, all paragraphs are affected.  For a rich Text object, only those paragraphs marked by the selection are affected.  prop determines which property is modified, and val provides additional information needed for some properties.  These constants are defined for prop:

Constant Property Affected
NX_LEFTALIGN Text alignment.  Aligns the text to the left margin.  val is ignored.
NX_RIGHTALIGN Text alignment.  Aligns the text to the right margin.  val is ignored.
NX_CENTERALIGN Text alignment.  Centers the text between the left and right margins.  val is ignored.
NX_JUSTALIGN Not yet implemented.
NX_FIRSTINDENT Indentation of the first line.  val specifies the number of units (in the receiver's coordinate system) along the x axis to indent.
NX_INDENT Indentation of lines other than the first line.  val specifies the number of units (in the receiver's coordinate system) along the x axis to indent.
NX_ADDTAB Tab placement.  val specifies the position on the x axis (in the receiver's coordinate system) to add the new tab.
NX_REMOVETAB Tab placement.  val identifies the tab to be removed by specifying its position on the x axis (in the receiver's coordinate system).
NX_LEFTMARGIN Left margin width.  val gives the new width as a number of units in the receiver's coordinate system.
NX_RIGHTMARGIN Right margin width.  val gives the new width as a number of units in the receiver's coordinate system.

setSelProp:to: sets the left and right margins by performing the setMarginLeft:right: top:bottom: method.  For all other properties, it performs the setFont:parastyle: method.  After the paragraph property is set, the text is rewrapped and redrawn. Returns self.

See also:  alignSelCenter:, alignSelLeft:, alignSelRight:, setMonoFont:



setTag:
setTag:(int)anInt

Sets the Text object's tag value to anInt.  Returns self.

See also:  tag, findViewWithTag:



setText:
setText:(const char *)aString

Replaces the current text with the text referred to by aString.  The Text object then wraps and redraws the text, if autodisplay is enabled.  This method doesn't affect the object's frame or bounds rectangle.  To resize the text rectangle to make the text entirely visible, use the sizeToFit method.  Returns self.

See also:  setSel::, readText:, readRichText:, sizeToFit



setTextColor:
setTextColor:(NXColor)color

Sets color as the display color for the entire text.  color is an NXColor structure as defined in the header file appkit/color.h. Unlike the background color/gray, if the text color is set, it's used on all displays, whether monochrome or color.  setTextColor: doesn't redraw the text.  Returns self.

To set the color of selected text, use setSelColor:.

See also:  setBackgroundGray:, backgroundGray:, setBackgroundColor:, backgroundColor, setTextGray:, textGray, textColor, setSelGray:, selGray, setSelColor:



setTextFilter:
setTextFilter:(NXTextFilterFunc)aFunc

Sets the text filter function, the function that analyzes text the user enters.

The text filter function is called with the following arguments:

NXTextFunc myTextFilter(id self, unsigned char *insertText,
int *insertLength, int position);

This function may change the contents of the text to be inserted.  The pointer to the new text is returned, and the new length is written into the insertLength integer pointer.  The position is where the new text is to be inserted.

This filter is different from the character filter in that you're given where the text is to be inserted and the new text that will be inserted.  This enables you to write a filter to do auto-indent, or a filter to allow only properly formatted floating point numbers. The character filter doesn't give enough context to determine exactly what the state of the Text object is before and after the edit.  Returns self.

See also:  textFilter



setTextGray:
setTextGray:(float)value

Sets the display color for the entire text as a gray value.  value should lie in the range 0.0 (indicating black) to 1.0 (indicating white).  To specify one of the four pure shades of gray, use one of these constants:

Constant Shade
NX_WHITE White
NX_LTGRAY Light gray
NX_DKGRAY Dark gray
NX_BLACK Black

A setTextGray: message doesn't cause the text to be redrawn.  Returns self.

See also:  setBackgroundGray:, backgroundGray:, setBackgroundColor:, backgroundColor, textGray, setTextColor:, textColor, setSelGray:, selGray, setSelColor:



setVertResizable:
setVertResizable:(BOOL)flag

Sets whether the text can change size vertically.  If flag is YES, the Text object's frame rectangle can change in the vertical dimension in response to additions or deletions of text; if NO, it can't.  By default, a Text object can't change size.  Returns self.

See also:  isVertResizable, setHorizResizable:, isHorizResizable



showCaret
showCaret

Displays the caret.  The Text object sends itself showCaret messages whenever it needs to redisplay the caret; you rarely need to send a showCaret message directly.  Occasions when the showCaret message is sent include whenever a Text object receives becomeKeyWindow, paste:, or delete: messages.  A showCaret message redisplays the caret only if the selection is zero-width.  If the Text object is not in a window, or the window is not the key window, or the Text object is not editable, this method has no effect.  Returns self.

See also:  hideCaret



showGuessPanel:
showGuessPanel:sender

Displays a panel that offers suggested alternate spellings for a word that's suspected of being misspelled.  The user can either accept one of the alternates, added the word to a local dictionary in ~/.NeXT/LocalDictionary, or skip the word.

A word becomes a candidate for the Guess panel's actions by being selected as the result of the Text object's receiving a checkSpelling: message.  Returns self.

See also:  checkSpelling:



sizeTo::
sizeTo:(NXCoord)width :(NXCoord)height

Sets the Text object's frame rectangle to the specified width and height in its superview's coordinates.  This method doesn't rewrap the text; to do that, send a calcLine message.  Returns self.

See also:  sizeTo:: (View)



sizeToFit
sizeToFit

Modifies the frame rectangle to completely display the text.  This is often used with Text objects in a ScrollView.  The setHorizResizable: and setVertResizable: methods determine whether the Text object will resize horizontally or vertically (by default, it won't change size in either dimension).  After receiving a calcLine message, a Text that is the document view of a ScrollView sends itself a sizeToFit message.  See calcLine for the methods that send calcLine messages.  Returns self.

See also:  setHorizResizable:, setVertResizable:



startReadingRichText
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.



stream
(NXStream *)stream

Returns a pointer to a read-only stream that allows you to read the contents of the Text object.  The returned stream is convenient for parsing the contents of the Text object or for implementing text searching within a text editor.  The stream is valid until the Text object is edited.  You shouldn't keep a copy of the stream (or free the stream) after you finish using it.  When you need the stream again, send another stream message to get a valid one.

Note:  The returned stream is not a memory stream and so can't be used as an argument to functions such as NXSaveToFile(). Use methods such as writeRichText: or writeRTFDTo: to create a memory stream that can be saved directly to a file.

See also:  getSubstring:start:length:, firstTextBlock



subscript:
subscript:sender

Subscripts the selection.  The text is then rewrapped and redrawn.  The text is subscripted by 40% of the selection's font height. Returns self.

See also:  superscript:, unscript:



superscript:
superscript:sender

Superscripts the selection.  The text is then rewrapped and redrawn.  The text is superscripted by 40% of the selection's font height.  Returns self.

See also:  subscript:, unscript:



tag
(int)tag

Returns the Text object's tag.

See also:  setTag:, findViewWithTag:



textColor
(NXColor)textColor

Returns an NXColor structure that denotes the color used for drawing text.

See also:  setTextColor:



textFilter
(NXTextFilterFunc)textFilter

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

See also:  setTextFilter:



textGray
(float)textGray

Returns the gray value used to draw the text.

See also:  setTextGray:



textLength
(int)textLength

Returns the number of characters in a Text object.  The length doesn't include the null terminator (`\0') that getSubstring:start:length: returns if you ask for all the text in a Text object.

The textLength and charLength methods are identical; the related method byteLength returns the length of the text in bytes, which, depending on the number of bytes used to store a character, may return a larger value.

See also:  byteLength, charLength, getSubstring:start:length:



toggleRuler:
toggleRuler:sender

Controls the display of the ruler.  This method has effect only if the receiving Text object is a rich Text object (see setMonoFont:) and is a subview of a ScrollView.  toggleRuler: causes the ScrollView to display a ruler if one isn't already present, or to remove the ruler if one is.  When the ruler is displayed, its settings reflect the paragraph style of the paragraph containing the selection.

sender is the id of the sending object.  Returns nil if the receiver isn't a subview of a ScrollView instance; otherwise, returns self.

See also:  isRulerVisible:, copyRuler:, pasteRuler:, setMonoFont:



underline:
underline:sender

Toggles the underline attribute of text.  This method has effect only if the receiving Text object can display multiple fonts and paragraph styles (see setMonoFont:).

underline: adds an underline to the selected text if one doesn't already exist or removes the underline if it does.  If the selection is zero-width, underline: affects the underline attribute of text that's subsequently entered at the insertion point.

sender is the id of the sending object.  Returns self.

See also:  setMonoFont:, superscript:, subscript:



unscript:
unscript:sender

Removes the subscript or superscript property of the current selection.  The text is then rewrapped and redrawn.  Returns self.

See also:  subscript:, superscript:



validRequestorForSendType:andReturnType:
validRequestorForSendType:(NXAtom)sendType
andReturnType:(NXAtom)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:andReturnType: 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: andReturnType: 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:andReturnType: in the Responder class specification for more information.

See also:  + excludeFromServicesMenu:, registerServicesMenuSendTypes:andReturnTypes: (Application), readSelectionFromPasteboard:, writeSelectionToPasteboard:, validRequestorForSendType:andReturnType: (Responder)



windowChanged:
windowChanged:newWindow

Notifies the receiving Text object of a change in the identity of its Window.  Generally, the change is the result of the Text object (or one of its superviews) being removed from the Window's view hierarchy.  This method ensures that the caret is hidden whenever the window changes.  Returns self.

See also:  windowChanged: (View)



write:
write:(NXTypedStream *)stream

Writes the Text object to the typed stream stream.  A write: message is sent in response to archiving; you never send this message directly.  Returns self.



writeRichText:
writeRichText:(NXStream *)stream

Writes the contents of the Text object as RTF data to stream.  The margins, fonts, superscripting/subscripting, text color, and text are written out in this format.  Returns self.

See also:  writeText:, readText:



writeRichText:from:to:
writeRichText:(NXStream *)stream
from:(int)start
to:(int)end

Writes a portion of the text starting at position start to position end in RTF to stream.  Returns self.

See also:  writeText:, readText:



writeRTFDSelectionTo:
writeRTFDSelectionTo:(NXStream *)stream

Writes the Text object's selection to stream.  If the selection consists of text and images from files in an RTFD directory, this data is serialized into the stream.  Returns self.

See also:  openRTFDFrom:, readRTFDFrom:, replaceSelWithRTFD:, writeRTFDTo:



writeRTFDTo:
writeRTFDTo:(NXStream *)stream

Writes the Text object's contents to stream.  If the Text object is storing RTFD data (that is, text and images) this data is serialized into the stream.  The counterpart method, readRTFDFrom:, can restore the Text object's contents from such serialized data.  Returns self.

See also:  openRTFDFrom:, readRTFDFrom:, replaceSelWithRTFD:, writeRTFDSelectionTo:



writeSelectionToPasteboard:types:
(BOOL)writeSelectionToPasteboard:pboard
types:(NXAtom *)types

Writes the current selection to the supplied Pasteboard object, pboardtypes 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:andReturnType:



writeText:
writeText:(NXStream *)stream

Writes the entire text to stream.  If you want to write only the selected text to a stream, use getSel:: (to determine the extent of the selection), getSubstring:start:length: (to retrieve the text within the selected region), and then NXWrite() to write the text to the stream.  Returns self.

See also:  writeRichText:, readText:, getSubstring:start:length:



Methods Implemented by the Delegate

textDidChange:
textDidChange:sender

Responds to a message sent to the delegate after the first change to the text since the Text object became the first responder. The delegate receives a textWillChange: message immediately before receiving a textDidChange: message.



textDidEnd:endChar:
textDidEnd:sender endChar:(unsigned short)whyEnd

Responds to a message informing the delegate that the Text object has relinquished first responder status.  whyEnd is the movement character (for example, Tab or Return) that caused the Text object to cease being the first responder and is represented by constants such as NX_TAB and NX_RETURN.  (See "Types and Constants" for a complete list of these constants.)  The delegate can use this information to decide which other object should become the first responder.



textDidGetKeys:isEmpty:
textDidGetKeys:sender isEmpty:(BOOL)flag

Responds to a message sent to the delegate after each change to the text.  flag indicates whether the Text object contains any text after the change.



textDidRead:paperSize:
textDidRead:sender paperSize:(NXSize *)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:paperSize:



textDidResize:oldBounds:invalid:
textDidResize:sender
oldBounds:(const NXRect *)oldBounds
invalid:(NXRect *)invalidRect

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.



textWillChange:
(BOOL)textWillChange:sender

Responds to a message sent upon the first user input since the Text object became the first responder.  The delegate's textWillChange: method can prevent the text from being changed by returning YES.  If the delegate allows the change, it immediately receives a textDidChange: message after the change is made.  If the delegate doesn't implement this method, the change is allowed by default.



textWillConvert:fromFont:toFont:
textWillConvert:sender
fromFont:from
toFont: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.



textWillEnd:
(BOOL)textWillEnd:sender

Responds to a message informing the delegate that the Text object is about to relinquish first responder status.  The delegate's textWillEnd: method can prevent the change by returning YES.  If the delegate prevents the change, the entire text becomes selected.  If the delegate doesn't implement this method, the change is allowed by default.



textWillFinishReadingRichText:
textWillFinishReadingRichText:sender

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:
textWillResize:sender

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:
textWillSetSel:sender toFont: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:
textWillStartReadingRichText:sender

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:paperSize:
textWillWrite:sender paperSize:(NXSize *)paperSize

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 Graphic Object

calcCellSize:
calcCellSize:(NXSize *)theSize

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:  calcCellSize: (Cell)



drawSelf:inView:
drawSelf:(const NXRect *)rect inView:view

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 Cell class specification for one implementation of this method.

See also:  drawSelf:inView: (Cell)



highlight:inView:lit:
highlight:(const NXRect *)rect
inView:view
lit:(BOOL)flag

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:inView:lit: (Cell)



readRichText:forView:
readRichText:(NXStream *)stream forView: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:  writeRichText:forView:, registerDirective:forClass:



trackMouse:inRect:ofView:
(BOOL)trackMouse:(NXEvent *)theEvent
inRect:(const NXRect *)rect
ofView:view

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)



writeRichText:forView:
writeRichText:(NXStream *)stream forView: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: