ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSTextView

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guides

Class at a Glance

NSTextView is the front-end component of the Application Kit’s text system. It displays and manipulates text laid out in an area defined by an NSTextContainer and adds many features to those defined by its superclass, NSText. Many of the methods that you’ll use most frequently are declared by the superclass; see the NSText class specification for details.

Creation

Instances of this class can be created using Interface Builder or using one of its constructors.

Commonly Used Methods

The methods most commonly used with NSTextView objects are declared in NSText, the superclass. These methods provide access to the other major components of the text system:

textStorage

Returns the associated NSTextStorage object.

textContainer

Returns the associated NSTextContainer object.

layoutManager

Returns the associated NSLayoutManager object.

Overview

NSTextView is the front-end class to the Application Kit’s text-handling system. It draws the text managed by the back-end components and handles user events to select and modify its text. NSTextView is the principal means to obtain a text object that caters to almost all needs for displaying and managing text at the user interface level. While NSTextView is a subclass of NSText—which declares the most general Cocoa interface to the text system—NSTextView adds major features beyond the capabilities of NSText.

NSTextView communicates with its delegate through methods declared both by NSTextView and by its superclass, NSText. See the NSText class specification for those other delegate methods. Note that all delegation messages come from the first text view.

Interfaces Implemented

NSTextInput

Tasks

Constructors

Registering Services Information

Accessing Related Text System Objects

Setting Graphics Attributes

Controlling Display

Inserting Text

Setting Behavioral Attributes

Using the Ruler

Managing the Selection

Managing the Pasteboard

Setting Text Attributes

Other Action Methods

Undo Support

Methods That Subclasses Should Use or Override

Changing First Responder Status

Working with the Spelling Checker

NSRulerView Client Methods

Assigning a Delegate

Dragging

Speech Support

Working with Panels

Text Completion

Clicking cells and links

Selecting

Dragging cells

Editing text and attributes

Obtaining undo manager

Performing commands

Working with pasteboards

Working with tool tips

Text completion

Constructors

NSTextView

Creates an NSTextView with a zero-sized frame rectangle.

public NSTextView()

Creates an NSTextView object with frameRect as its frame rectangle.

public NSTextView(NSRect frameRect)

Discussion

This method creates the entire collection of objects associated with an NSTextView—its NSTextContainer, NSLayoutManager, and NSTextStorage—and invokes the following constructor that takes a frameRect and aTextContainer.

This method creates the text web in such a manner that the NSTextView object is the principal owner of the objects in the web.

Creates an NSTextView object with frameRect as its frame rectangle and aTextContainer as its text container.

public NSTextView(NSRect frameRect, NSTextContainer aTextContainer)

Discussion

Unlike the constructor that takes only a frameRect, which builds up an entire group of text-handling objects, you use this constructor after you’ve created the other components of the text-handling system—an NSTextStorage object, an NSLayoutManager object, and an NSTextContainer object. Assembling the components in this fashion means that the NSTextStorage, not the NSTextView, is the principal owner of the component objects.

Static Methods

registerForServices

Registers send and return types for the Services facility.

public static void registerForServices()

Discussion

This method is invoked automatically when the first instance of an NSTextView is created; you should never need to invoke it directly.

Subclassing NSTextView is necessary to add support for new service types (in addition to actually supporting writing or reading the types, of course). Override "registerForServices" to call super and then register your own new types.

Instance Methods

acceptableDragTypes

Returns the data types that the receiver accepts as the destination view of a dragging operation.

public NSArray acceptableDragTypes()

Discussion

These types are automatically registered as necessary by the NSTextView. Subclasses should override this method as necessary to add their own types to those returned by NSTextView’s implementation. They must then also override the appropriate methods of the “NSDraggingDestination” interface to support import of those types. See that interface’s specification for more information.

See Also

alignJustified

This action method applies full justification to selected paragraphs (or all text, if the receiver is a plain text object).

public void alignJustified(Object sender)

See Also

allowsDocumentBackgroundColorChange

Returns true if the receiver allows the its background color to change, otherwise false.

public boolean allowsDocumentBackgroundColorChange()

Discussion

This corresponds to the background color of the entirety of the text view, not just to a selected range of text.

Availability
See Also

allowsUndo

Returns true if the receiver allows undo, otherwise false.

public boolean allowsUndo()

See Also

attributedSubstringWithRange

Returns attributed string at theRange.

public NSAttributedString attributedSubstringWithRange(NSRange theRange)

Discussion

This allows input mangers to query any range in backing store.

backgroundColor

public NSColor backgroundColor()

Discussion

Returns the receiver’s background color.

See Also

becomeFirstResponder

Informs the receiver that it’s becoming the first responder.

public boolean becomeFirstResponder()

Discussion

If the previous first responder was not an NSTextView on the same NSLayoutManager as the receiving NSTextView, this method draws the selection and updates the insertion point if necessary. Returns true.

Use NSWindow’s makeFirstResponder, not this method, to make an NSTextView the first responder. Never invoke this method directly.

See Also

breakUndoCoalescing

public void breakUndoCoalescing()

Discussion

Informs the receiver that it should begin coalescing sucessive typing operations in a new undo grouping. Typically this is invoked when saving the receiver’s contents.

Availability

changeAttributes

This action method changes the attributes of the current selection.

public void changeAttributes(Object sender)

Discussion

This method changes the attributes by invoking convertAttributes on sender and applying the returned attributes to the appropriate text. See the “NSFontManager” class reference for more information on attribute conversion.

Availability

changeColor

Invoked by the NSColorPanel sender to set the color of the selected text.

public void changeColor(Object sender)

Discussion

NSTextView’s implementation queries sender for the color by sending it a color message.

changeDocumentBackgroundColor

public void changeDocumentBackgroundColor(Object sender)

Discussion

Invoked by the NSColorPanel sender to set the background color of the selected text. NSTextView’s implementation queries sender by sending it a color message.

This will only set the background color if allowsDocumentBackgroundColorChange returns true.

Availability
See Also

characterIndexForPoint

Returns the index for the character that is nearest to thePoint.

public int characterIndexForPoint(NSPoint thePoint)

Discussion

thePoint is in the screen coordinate system.

cleanUpAfterDragOperation

Releases the drag information still existing after the dragging session has completed.

public void cleanUpAfterDragOperation()

Discussion

Subclasses may override this method to clean up any additional data structures used for dragging. In your overridden method, be sure to invoke the super’s implementation of this method.

clickedOnLinkAtIndex

Notifies the delegate that the user clicked a link at the specified charIndex.

public void clickedOnLinkAtIndex(Object link, int charIndex)

Discussion

The delegate may take any appropriate actions to handle the click in its textViewClickedOnLinkAtIndex method.

See Also

conversationIdentifier

Returns a number used to identify the receiver’s input management session to the input server.

public int conversationIdentifier()

defaultParagraphStyle

Returns the receiver’s default paragraph style.

public NSParagraphStyle defaultParagraphStyle()

Availability
See Also

delegate

Returns the delegate used by the receiver (and by all other NSTextViews sharing the receiver’s NSLayoutManager), or null if there is none.

public Object delegate()

See Also

didChangeText

Invoked automatically at the end of a series of changes, this method posts aTextDidChangeNotification to the default notification center, which also results in the delegate receiving an NSText delegate textDidChange message.

public void didChangeText()

Discussion

Subclasses implementing methods that change their text should invoke this method at the end of those methods. See the “Class Description” for more information.

See Also

doCommandBySelector

Attempts to invoke aSelector or pass the message up the responder chain.

public void doCommandBySelector(NSSelector aSelector)

Discussion

This method is invoked by an input manager in response to an interpretKeyEvents message.

See Also

dragOperationForDraggingInfo

Returns the type of drag operation that should be performed if the image were released now.

public int dragOperationForDraggingInfo(NSDraggingInfo dragInfo, String type)

Discussion

type is the pasteboard type that will be read from the dragging pasteboard, and dragInfo is an object the Application Kit creates that holds information about the dragging session. The returned value should be one of the following:

Option

Meaning

NSDraggingInfo.DragOperationCopy

The data represented by the image will be copied.

NSDraggingInfo.DragOperationLink

The data will be shared.

NSDraggingInfo.DragOperationGeneric

The operation will be defined by the destination.

NSDraggingInfo.DragOperationPrivate

The operation is negotiated privately between the source and the destination.

If none of the operations is appropriate, this method should return NSDraggingInfo.DragOperationNone.

This method is called repeatedly from draggingEntered and draggingUpdated as the user drags the image.

See Also

drawInsertionPointInRect

public void drawInsertionPointInRect(NSRect aRect, NSColor aColor, boolean flag)

Discussion

If flag is true, draws the insertion point in aRect using aColor. If flag is false, this method erases the insertion point. The focus must be locked on the receiver when this method is invoked.

See Also

drawsBackground

Returns true if the receiver draws its background, false if it doesn’t.

public boolean drawsBackground()

See Also

drawViewBackgroundInRect

Called when the text view intends to draw its background

public void drawViewBackgroundInRect(NSRect rect)

Discussion

. Subclasses can override this method to perform additional drawing behind the text of an NSTextView.

Availability

firstRectForCharacterRange

public NSRect firstRectForCharacterRange(NSRange theRange)

Discussion

Returns the first frame of rectangles for theRange in the screen coordinate system.

hasMarkedText

Returns true if the receiver has text that’s still being interpreted by the input manager, false if it doesn’t.

public boolean hasMarkedText()

importsGraphics

Returns true if the text views sharing the receiver’s NSLayoutManager allow the user to import files by dragging, false if they don’t.

public boolean importsGraphics()

Discussion

A text view that accepts dragged files is also a rich text view.

See Also

insertCompletion

public void insertCompletion(String word, NSRange charRange, int movement, boolean flag)

Discussion

Called with flag set to false as the user moves through the potential text completions, then with flag set to true when a completion is definitively selected or cancelled and the original value is reinserted.

The default implementation inserts the selected completion into the text at the appropriate location. movement takes its values from the movement codes defined in the NSText “Constants” section, and allows subclassers to distinguish between cancelling completion and selection by arrow keys, by return, by tab, or by other means such as clicking.

Availability

insertionPointColor

Returns the color used to draw the insertion point.

public NSColor insertionPointColor()

See Also

insertText

Inserts aString into the receiver’s text at the insertion point if there is one, otherwise replacing the selection.

public void insertText(Object aString)

Discussion

The inserted text is assigned the current typing attributes.

This method is the means by which text typed by the user enters an NSTextView. See the NSInputManager class and “NSTextInput” interface specifications for more information.

This method is the entry point for inserting text typed by the user and is generally not suitable for other purposes. Programmatic modification of the text is best done by operating on the NSTextStorage. Because this method pertains to the actions of the user, the text view must be editable for the insertion to work.

See Also

invalidateTextContainerOrigin

Informs the receiver that it needs to recalculate the origin of its text container, usually because it’s been resized or the contents of the text container have changed.

public void invalidateTextContainerOrigin()

Discussion

This method is invoked automatically; you should never need to invoke it directly.

See Also

isContinuousSpellCheckingEnabled

Returns true if the object has continuous spell checking enabled, otherwise false.

public boolean isContinuousSpellCheckingEnabled()

See Also

isEditable

Returns true if the text views sharing the receiver’s NSLayoutManager allow the user to edit text, false if they don’t.

public boolean isEditable()

Discussion

If a text view is editable, it’s also selectable.

See Also

isFieldEditor

Returns true if the text views sharing the receiver’s NSLayoutManager interpret Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder; false if they accept them as text input.

public boolean isFieldEditor()

Discussion

See the NSWindow class specification for more information on field editors. By default, NSTextViews don’t behave as field editors.

See Also

isRichText

Returns true if the text views sharing the receiver’s NSLayoutManager allow the user to apply attributes to specific ranges of the text, false if they don’t.

public boolean isRichText()

See Also

isRulerVisible

Returns true if the scroll view enclosing the text views sharing the receiver’s NSLayoutManager shows its ruler, false otherwise.

public boolean isRulerVisible()

See Also

isSelectable

Returns true if the text views sharing the receiver’s NSLayoutManager allow the user to select text, false if they don’t.

public boolean isSelectable()

See Also

layoutManager

Returns the NSLayoutManager that lays out text for the receiver’s text container, or null if there’s no such object (which is the case when a text view isn’t linked into a group of text objects).

public NSLayoutManager layoutManager()

See Also

linkTextAttributes

Returns the attributes corresponding to the onscreen generation of link text.

public native NSDictionary linkTextAttributes()

Discussion

In applications created prior to Mac OS X v10.3, the default value is an empty dictionary. In applications created with Mac OS X v10.3 or greater, the default attributes specify blue text with an underline.

Availability
See Also

loosenKerning

This action method increases the space between glyphs in the receiver’s selection, or in all text if the receiver is a plain text view.

public void loosenKerning(Object sender)

Discussion

Kerning values are determined by the point size of the fonts in the selection.

See Also

lowerBaseline

This action method lowers the baseline offset of selected text by 1 point, or of all text if the receiver is a plain text view.

public void lowerBaseline(Object sender)

Discussion

As such, this method defines a more primitive operation than subscripting.

See Also

markedRange

Returns the range of marked text.

public NSRange markedRange()

Discussion

If there’s no marked text, returns a range whose location is NSArray.NotFound.

See Also

markedTextAttributes

Returns the attributes used to draw marked text.

public NSDictionary markedTextAttributes()

See Also

orderFrontLinkPanel

Brings forward a panel allowing the user to manipulate links in the text view.

public void orderFrontLinkPanel(Object sender)

Availability

orderFrontListPanel

Brings forward a panel allowing the user to manipulate text lists in the text view.

public void orderFrontListPanel(Object sender)

Availability

orderFrontSpacingPanel

Brings forward a panel allowing the user to manipulate text line heights, interline spacing, and paragraph spacing, in the text view.

public void orderFrontSpacingPanel(Object sender)

Availability

orderFrontTablePanel

Brings forward a panel allowing the user to manipulate text tables in the text view.

public void orderFrontTablePanel(Object sender)

Availability

outline

Adds the outline attribute to the selected text attributes if absent; removes the attribute if not.

public void outline(Object sender)

Discussion

Uses NSStrokeWidthAttributeName with a default value of 3.0.

Availability

pasteAsPlainText

This action method inserts the contents of the pasteboard into the receiver’s text as plain text, in the manner of insertText.

public void pasteAsPlainText(Object sender)

See Also

pasteAsRichText

This action method inserts the contents of the pasteboard into the receiver’s text as rich text, maintaining its attributes.

public void pasteAsRichText(Object sender)

Discussion

The text is inserted at the insertion point if there is one, otherwise replacing the selection.

See Also

performFindPanelAction

This is the generic action method for the find menu and find panel, and can be overridden to provide a custom find panel

public void performFindPanelAction(Object sender)

Discussion

. The actual operation is determined by the tag of the sender, corresponding to the list of tags in “Constants.”

Availability

preferredPasteboardTypeFromArray

Returns whatever type on the pasteboard would be most preferred for copying data.

public String preferredPasteboardTypeFromArray(NSArray availableTypes, NSArray allowedTypes)

Discussion

The availableTypes parameter lists the types that are currently available on the pasteboard. If the allowedTypes parameter is not null, then only types in that array may be returned; otherwise, if allowedTypes is null, any of the available pasteboard types may be returned.

You should not need to override this method. You should also not need to invoke it unless you are implementing a new type of pasteboard to handle services other than copy/paste or dragging.

See Also

raiseBaseline

This action method raises the baseline offset of selected text by 1 point, or of all text if the receiver is a plain text view.

public void raiseBaseline(Object sender)

Discussion

As such, this method defines a more primitive operation than superscripting.

See Also

rangeForUserCharacterAttributeChange

Returns the range of characters affected by an action method that changes character (not paragraph) attributes, such as the NSText action method changeFont.

public NSRange rangeForUserCharacterAttributeChange()

Discussion

For rich text this range is typically the range of the selection. For plain text this range is the entire contents of the receiver. In Mac OS X v10.4 and later, returns the first subrange where there is a multiple-range selection.

If the receiver isn’t editable or doesn’t use the Font panel, the range returned has a location of NSArray.NotFound.

See Also

rangeForUserCompletion

Returns the partial range from the most recent beginning of a word up to the insertion point.

public NSRange rangeForUserCompletion()

Discussion

May be overridden by subclassers to alter the range to be completed. Returning (NSRange.NotFound, 0) suppresses completion.

The resulting value from this method is intended to be used for the range argument in the text completion methods.

In Mac OS X version 10.4 and later, if there are multiple selections, this method acts on the first selected subrange.

Availability

rangeForUserParagraphAttributeChange

Returns the range of characters affected by a method that changes paragraph (not character) attributes, such as the NSText action method alignLeft.

public NSRange rangeForUserParagraphAttributeChange()

Discussion

For rich text this range is typically calculated by extending the range of the selection to paragraph boundaries. For plain text this range is the entire contents of the receiver.

If the receiver isn’t editable, the range returned has a location of NSArray.NotFound.

In Mac OS X version 10.4 and later, if there are multiple selections, this method acts on the first selected subrange.

See Also

rangeForUserTextChange

Returns the range of characters affected by a method that changes characters (as opposed to attributes), such as insertText.

public NSRange rangeForUserTextChange()

Discussion

This is typically the range of the selection.

If the receiver isn’t editable or doesn’t use a ruler, the range returned has a location of NSArray.NotFound.

In Mac OS X version 10.4 and later, if there are multiple selections, this method acts on the first selected subrange.

See Also

rangesForUserCharacterAttributeChange

Returns an array containing the ranges of characters affected by an action method that changes character (not paragraph) attributes, such as the NSText action method changeFont.

public NSArray rangesForUserCharacterAttributeChange()

Discussion

For rich text these ranges are typically the ranges of the selections. For plain text the range is the entire contents of the receiver.

Returns null if the receiver isn’t editable or doesn’t use the Font panel.

Availability
See Also

rangesForUserParagraphAttributeChange

Returns an array containing the ranges of characters affected by a method that changes paragraph (not character) attributes, such as the NSText action method alignLeft.

public NSArray rangesForUserParagraphAttributeChange()

Discussion

For rich text these ranges are typically calculated by extending the range of the current selections to paragraph boundaries. For plain text the range is the entire contents of the receiver.

Returns null if the receiver isn’t editable or doesn’t use the Font panel.

Availability
See Also

rangesForUserTextChange

Returns an array containing the ranges of characters affected by a method that changes characters (as opposed to attributes), such as insertText.

public NSArray rangesForUserTextChange()

Discussion

These are typically the ranges of the selections.

Returns null if the receiver isn’t editable or doesn’t use a ruler.

Availability
See Also

readablePasteboardTypes

Returns an array of strings describing the types this text view can read immediately from the pasteboard.

public NSArray readablePasteboardTypes()

Discussion

The strings are ordered by the default preferences.

You can override this method to provide support for new types of data. If you want to add support for the default types, you can invoke the superclass version of this method or add the types directly in your overridden version.

See Also

readSelectionFromPasteboard

Reads the text view’s preferred type of data from the pasteboard specified by the pboard parameter.

public boolean readSelectionFromPasteboard(NSPasteboard pboard)

Discussion

This method invokes the preferredPasteboardTypeFromArray method to determine the text view’s preferred type of data and then reads the data using the readSelectionFromPasteboardOfType method. Returns true if the data was successfully read.

You should not need to override this method. You might need to invoke this method if you are implementing a new type of pasteboard to handle services other than copy/paste or dragging.

See Also

readSelectionFromPasteboardOfType

Reads data of the given type from pboard.

public boolean readSelectionFromPasteboardOfType(NSPasteboard pboard, String type)

Discussion

The new data is placed at the current insertion point, replacing the current selection if one exists. Returns true if the data was successfully read.

You should override this method to read pasteboard types other than the default types. Use the rangeForUserTextChange method to obtain the range of characters (if any) to be replaced by the new data.

See Also

replaceTextContainer

Replaces the NSTextContainer for the group of text system objects containing the receiver with aTextContainer, keeping the association between the receiver and its layout manager intact, unlike setTextContainer.

public void replaceTextContainer(NSTextContainer aTextContainer)

Discussion

Throws InvalidArgumentException if aTextContainer is null.

See Also

resignFirstResponder

Notifies the receiver that it’s been asked to relinquish its status as first responder in its NSWindow.

public boolean resignFirstResponder()

Discussion

If the object that will become the new first responder is an NSTextView attached to the same NSLayoutManager as the receiver, this method returns true with no further action. Otherwise, this method sends a textShouldEndEditing message to its delegate (if any). If the delegate returns false, this method returns false. If the delegate returns true, this method hides the selection highlighting and posts a TextDidEndEditingNotification to the default notification center.

Use NSWindow’s makeFirstResponder, not this method, to make an NSTextView the first responder. Never invoke this method directly.

See Also

rulerViewDidAddMarker

public void rulerViewDidAddMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

This NSRulerView client method modifies the paragraph style of the paragraphs containing the selection to accommodate a new NSTextTab represented by aMarker. It then records the change by invoking didChangeText.

NSTextView checks for permission to make the change in its rulerViewShouldAddMarker method, which invokes shouldChangeTextInRange to send out the proper request and notifications, and only invokes this method if permission is granted.

See Also

rulerViewDidMoveMarker

public void rulerViewDidMoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

This NSRulerView client method modifies the paragraph style of the paragraphs containing the selection to record the new location of the NSTextTab represented by aMarker. It then records the change by invoking didChangeText.

NSTextView checks for permission to make the change in its rulerViewShouldMoveMarker method, which invokes shouldChangeTextInRange to send out the proper request and notifications, and only invokes this method if permission is granted.

See Also

rulerViewDidRemoveMarker

public void rulerViewDidRemoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

This NSRulerView client method modifies the paragraph style of the paragraphs containing the selection—if possible—by removing the NSTextTab represented by aMarker. It then records the change by invoking didChangeText.

NSTextView checks for permission to move or remove a tab stop in its rulerViewShouldMoveMarker method, which invokes shouldChangeTextInRange to send out the proper request and notifications, and only invokes this method if permission is granted.

See Also

rulerViewHandleMouseDown

public void rulerViewHandleMouseDown(NSRulerView aRulerView, NSEvent theEvent)

Discussion

This NSRulerView client method adds a left tab marker to the ruler, but a subclass can override this method to provide other behavior, such as creating guidelines. This method is invoked once with theEvent when the user first clicks the ruler area of aRulerView, as described in the NSRulerView class specification.

rulerViewShouldAddMarker

public boolean rulerViewShouldAddMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

This NSRulerView client method controls whether a new tab stop aMarker can be added. The receiver checks for permission to make the change by invoking shouldChangeTextInRange and returning the return value of that message. If the change is allowed, the receiver is then sent a rulerViewDidAddMarker message.

See Also

rulerViewShouldMoveMarker

public boolean rulerViewShouldMoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

This NSRulerView client method controls whether an existing tab stop aMarker can be moved. The receiver checks for permission to make the change by invoking shouldChangeTextInRange and returning the return value of that message. If the change is allowed, the receiver is then sent a rulerViewDidAddMarker message.

See Also

rulerViewShouldRemoveMarker

public boolean rulerViewShouldRemoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

This NSRulerView client method controls whether an existing tab stop aMarker can be removed. Returns true if aMarker represents an NSTextTab, false otherwise. Because this method can be invoked repeatedly as the user drags a ruler marker, it returns that value immediately. If the change is allows and the user actually removes the marker, the receiver is also sent a rulerViewDidRemoveMarker message.

See Also

rulerViewWillAddMarker

public float rulerViewWillAddMarker(NSRulerView aRulerView, NSRulerMarker aMarker, float location)

Discussion

This NSRulerView client method ensures that the proposed location of aMarker lies within the appropriate bounds for the receiver’s text container, returning the modified location.

See Also

rulerViewWillMoveMarker

public float rulerViewWillMoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker, float location)

Discussion

This NSRulerView client method ensures that the proposed location of aMarker lies within the appropriate bounds for the receiver’s text container, returning the modified location.

See Also

selectedRange

Returns the range of characters selected in the receiver’s layout manager.

public NSRange selectedRange()

See Also

selectedRanges

Returns an array containing the ranges of characters selected in the receiver’s layout manager.

public NSArray selectedRanges()

Discussion

The return value is a non-null, non-empty array of objects responding to the NSValue rangeValue method, and in addition its elements are sorted, non-overlapping, non-contiguous, and (except for the case of a single range) have non-zero-length.

Availability
See Also

selectedTextAttributes

Returns the attributes used to indicate the selection.

public NSDictionary selectedTextAttributes()

Discussion

This attribute is typically just the text background color.

See Also

selectionAffinity

Returns the preferred direction of selection, either SelectionAffinityUpstream or SelectionAffinityDownstream.

public int selectionAffinity()

Discussion

Selection affinity determines whether, for example, the insertion point appears after the last character on a line or before the first character on the following line in cases where text wraps across line boundaries.

selectionGranularity

Returns the current selection granularity, used during mouse tracking to modify the range of the selection.

public int selectionGranularity()

Discussion

This is one of:

See Also

selectionRangeForProposedRange

Adjusts the proposedSelRange if necessary, based on granularity.

public NSRange selectionRangeForProposedRange(NSRange proposedSelRange, int granularity)

Discussion

granularity is one of:

Returns the adjusted range. This method is invoked repeatedly during mouse tracking to modify the range of the selection. Override this method to specialize selection behavior.

See Also

setAlignmentInRange

Sets the alignment of the paragraphs containing characters in aRange to alignment.

public void setAlignmentInRange(int alignment, NSRange aRange)

Discussion

alignment is one of:

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges or shouldChangeTextInRange to include this method in an undoable action.

See Also

setAllowsDocumentBackgroundColorChange

Sets whether or not the receiver allows its background color to change.

public void setAllowsDocumentBackgroundColorChange(boolean flag)

Discussion

flag should be set to true if the receiver allows the change, otherwise false. This corresponds to the background color of the entirety of the text view, not just to a selected range of text.

Availability
See Also

setAllowsUndo

If flag is true enables undo support; otherwise disables it.

public void setAllowsUndo(boolean flag)

See Also

setBackgroundColor

Sets the receiver’s background color to aColor.

public void setBackgroundColor(NSColor aColor)

Discussion

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges or shouldChangeTextInRange to include this method in an undoable action.

See Also

setBaseWritingDirection

Sets the base writing direction of the text in range to writingDirection.

public void setBaseWritingDirection(int writingDirection, NSRange range)

Discussion

Invoke this method to change the base writing direction from left-to-right to right-to-left for languages like Hebrew and Arabic, for example.

This method does not include undo support by default. Clients must invoke shouldChangeTextInRanges or shouldChangeTextInRange to include this method in an undoable action.

Availability

setConstrainedFrameSize

Attempts to set the frame size for the receiver to desiredSize, constrained by the receiver’s existing minimum and maximum sizes and by whether resizing is permitted.

public void setConstrainedFrameSize(NSSize desiredSize)

See Also

setContinuousSpellCheckingEnabled

If flag is true enables continuous spell checking; otherwise disables it.

public void setContinuousSpellCheckingEnabled(boolean flag)

See Also

setDefaultParagraphStyle

Sets the receiver’s default paragraph style.

public void setDefaultParagraphStyle(NSParagraphStyle paragraphStyle)

Availability
See Also

setDelegate

Sets the delegate for all NSTextViews sharing the receiver’s NSLayoutManager to anObject, without retaining it.

public void setDelegate(Object anObject)

See Also

setDrawsBackground

Controls whether the receiver draws its background.

public void setDrawsBackground(boolean flag)

Discussion

If flag is true, the receiver fills its background with the background color; if flag is false, it doesn’t.

See Also

setEditable

Controls whether the text views sharing the receiver’s NSLayoutManager allow the user to edit text.

public void setEditable(boolean flag)

Discussion

If flag is true, they allow the user to edit text and attributes; if flag is false, they don’t. If an NSTextView is made editable, it’s also made selectable. NSTextViews are by default editable.

See Also

setFieldEditor

Controls whether the text views sharing the receiver’s NSLayoutManager interpret Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder.

public void setFieldEditor(boolean flag)

Discussion

If flag is true, they do; if flag is false, they don’t, instead accepting these characters as text input. See the NSWindow class specification for more information on field editors. By default, NSTextViews don’t behave as field editors.

See Also

setImportsGraphics

Controls whether the text views sharing the receiver’s NSLayoutManager allow the user to import files by dragging.

public void setImportsGraphics(boolean flag)

Discussion

If flag is true, they do; if flag is false, they don’t. If an NSTextView is set to accept dragged files, it’s also set for rich text. By default, NSTextViews don’t accept dragged files.

See Also

setInsertionPointColor

Sets the color of the insertion point to aColor.

public void setInsertionPointColor(NSColor aColor)

See Also

setLinkTextAttributes

Sets the attributes corresponding to the onscreen generation of link text.

public void setLinkTextAttributes(NSDictionary attributeDictionary)

Availability
See Also

setMarkedTextAndSelectedRange

Replaces text in aRange within receiver’s text storage with the contents of aString, which the receiver must display distinctively to indicate that it is marked text.

public void setMarkedTextAndSelectedRange(Object aString, NSRange aRange)

Discussion

aString must be either a String or an NSAttributedString, and not null.

See Also

setMarkedTextAttributes

Sets the attributes used to draw marked text to attributes.

public void setMarkedTextAttributes(NSDictionary attributes)

Discussion

Text color, background color, and underline are the only supported attributes for marked text.

See Also

setNeedsDisplay

Marks the receiver as requiring display within aRect.

public void setNeedsDisplay(NSRect aRect, boolean flag)

Discussion

If flag is true, the receiver won’t perform any layout that might be required to complete the display, even if this means that portions of the NSTextView remain empty. If flag is false, the receiver performs at least as much layout as needed to display aRect.

NSTextView overrides the NSView setNeedsDisplay method such that it invokes this method with a flag argument of false.

setRichText

Controls whether the text views sharing the receiver’s NSLayoutManager allow the user to apply attributes to specific ranges of the text.

public void setRichText(boolean flag)

Discussion

If flag is true they do; if flag is false they don’t. If flag is false, they’re also set not to accept dragged files. By default, NSTextViews let the user apply multiple attributes to text, but don’t accept dragged files.

See Also

setRulerVisible

Controls whether the scroll view enclosing text views sharing the receiver’s NSLayoutManager displays the ruler.

public void setRulerVisible(boolean flag)

Discussion

If flag is true it shows the ruler; if flag is false it hides the ruler. By default, the ruler is not visible.

See Also

setSelectable

Controls whether the text views sharing the receiver’s NSLayoutManager allow the user to select text.

public void setSelectable(boolean flag)

Discussion

If flag is true, users are allowed to select text; if flag is false, users are not allowed to select text. If an NSTextView is made not selectable, it’s also made not editable. NSTextViews are by default both editable and selectable.

See Also

setSelectedRange

public void setSelectedRange(NSRange charRange, int affinity, boolean flag)

Discussion

Sets the selection to the characters in charRange, using affinity if needed to determine how to display the selection or insertion point (see the description for selectionAffinity for more information). flag indicates whether this method is being invoked during mouse dragging or after the user releases the mouse button. If flag is true the receiver doesn’t send notifications or remove the marking from its marked text; if flag is false it does as appropriate. This method also resets the selection granularity to SelectByCharacter.

The charRange argument must begin and end on glyph boundaries and not split base glyphs and their nonspacing marks.

public void setSelectedRange(NSRange charRange)

Discussion

Sets the selection to the characters in charRange, resets the selection granularity to SelectByCharacter, and posts an TextViewDidChangeSelectionNotification to the default notification center. Also removes the marking from marked text if the new selection is greater than the marked region.

The charRange argument must begin and end on glyph boundaries and not split base glyphs and their nonspacing marks.

See Also

setSelectedRanges

public void setSelectedRanges(NSArray ranges)

Discussion

Sets the selection to the characters in the ranges array, resets the selection granularity to NSSelectByCharacter, and posts an TextViewDidChangeSelectionNotification to the default notification center. Also removes the marking from marked text if the new selection is greater than the marked region.

The ranges argument must be a non-nil, non-empty array of objects responding to the NSValue rangeValue method. The ranges in the ranges array must begin and end on glyph boundaries and not split base glyphs and their nonspacing marks.

public void setSelectedRanges(NSArray ranges, int affinity, boolean stillSelectingFlag)

Discussion

The method variant with three arguments uses affinity if needed to determine how to display the selection or insertion point (see the description for selectionAffinity for more information). stillSelectingFlag indicates whether this method is being invoked during mouse dragging or after the user releases the mouse button. If stillSelectingFlag is true the receiver doesn’t send notifications or remove the marking from its marked text; if stillSelectingFlag is false it does as appropriate.

Availability
See Also

setSelectedTextAttributes

Sets the attributes used to indicate the selection to attributes.

public void setSelectedTextAttributes(NSDictionary attributes)

Discussion

Text color, background color, and underline are the only supported attributes for selected text.

See Also

setSelectionGranularity

Sets the selection granularity for subsequent extension of a selection to granularity.

public void setSelectionGranularity(int granularity)

Discussion

granularity may be one of:

Selection granularity is used to determine how the selection is modified when the user Shift-clicks or drags the mouse after a double or triple click. For example, if the user selects a word by double-clicking, the selection granularity is set to SelectByWord. Subsequent Shift-clicks then extend the selection by words.

Selection granularity is reset to SelectByCharacter whenever the selection is set. You should always set the selection granularity after setting the selection.

See Also

setSmartInsertDeleteEnabled

Controls whether the receiver inserts or deletes space around selected words so as to preserve proper spacing and punctuation.

public void setSmartInsertDeleteEnabled(boolean flag)

Discussion

If flag is true it does; if flag is false it inserts and deletes exactly what’s selected.

See Also

setTextContainer

Sets the receiver’s text container to aTextContainer.

public void setTextContainer(NSTextContainer aTextContainer)

Discussion

The receiver then uses the layout manager and text storage of aTextContainer. This method is invoked automatically when you create an NSTextView; you should never invoke it directly, but might want to override it. To change the text view for an established group of text system objects, send setTextView to the text container. To replace the text container for a text view and maintain the view’s association with the existing layout manager and text storage, use replaceTextContainer.

See Also

setTextContainerInset

Sets the empty space the receiver leaves around its associated text container to inset.

public void setTextContainerInset(NSSize inset)

Discussion

It is possible to set the text container and view sizes and resizing behavior so that the inset cannot be maintained exactly, although the text system tries to maintain the inset wherever possible. In any case, the textContainerOrigin and size of the text container are authoritative as to the location of the text container within the view.

The text itself can have an additional inset, inside the text container, specified by the setLineFragmentPadding method of NSTextContainer.

See Also

setTypingAttributes

Sets the receiver’s typing attributes to attributes.

public void setTypingAttributes(NSDictionary attributes)

Discussion

Typing attributes are reset automatically whenever the selection changes. If you add any user actions that change text attributes, you should use this method to apply those attributes to a zero-length selection.

See Also

setUsesFindPanel

Specifies whether the receiver allows for a find panel.

public void setUsesFindPanel(boolean flag)

Availability
See Also

setUsesFontPanel

Controls whether the text views sharing the receiver’s NSLayoutManager use the Font panel and Font menu.

public void setUsesFontPanel(boolean flag)

Discussion

If flag is true, they respond to messages from the Font panel and from the Font menu, and update the Font panel with the selection font whenever it changes. If flag is false they disallow character attribute changes. By default, NSTextView objects use the Font panel and menu.

See Also

setUsesRuler

Controls whether the text views sharing the receiver’s NSLayoutManager use an NSRulerView and respond to Format menu commands.

public void setUsesRuler(boolean flag)

Discussion

If flag is true, they respond to NSRulerView client messages and to paragraph-related menu actions, and update the ruler (when visible) as the selection changes with its paragraph and tab attributes. If flag is false, the ruler is hidden, and the text views disallow paragraph attribute changes. By default, NSTextView objects use the ruler.

See Also

shouldChangeTextInRange

Initiates a series of delegate messages (and general notifications) to determine whether modifications can be made to the receiver’s text.

public boolean shouldChangeTextInRange(NSRange affectedCharRange, String replacementString)

Discussion

If characters in the text string are being changed, replacementString contains the characters that will replace the characters in affectedCharRange. If only text attributes are being changed, replacementString is null. This method checks with the delegate as needed using textShouldBeginEditing and textViewShouldChangeTextInRange, returning true to allow the change, and false to prohibit it.

This method must be invoked at the start of any sequence of user-initiated editing changes. If your subclass of NSTextView implements new methods that modify the text, make sure to invoke this method to determine whether the change should be made. If the change is allowed, complete the change by invoking the didChangeText method. If you can’t determine the affected range or replacement string before beginning changes, pass (NSArray.NotFound, 0) and null for these values.

If the receiver is not editable, this method automatically returns false. This result prevents instances in which a text view could be changed by user actions even though it had been set to be noneditable. In Mac OS X version 10.4 and later, if there are multiple selections, this method acts on the first selected subrange.

See Also

shouldChangeTextInRanges

Initiates a series of delegate messages (and general notifications) to determine whether modifications can be made to the receiver’s text.

public boolean shouldChangeTextInRanges(NSArray affectedRanges, NSArray replacementStrings)

Discussion

The replacementStrings array should either be null or else contain one element for each range in affectedRanges. If characters in the text string are being changed, the replacementStrings array contains the characters that replace the characters in affectedRanges. If only text attributes are being changed, replacementStrings is null. This method checks with the delegate as needed using textShouldBeginEditing and textViewShouldChangeTextInRanges, returning true to allow the change, and false to prohibit it.

This method must be invoked at the start of any sequence of user-initiated editing changes. If your subclass of NSTextView implements new methods that modify the text, make sure to invoke this method to determine whether the change should be made. If the change is allowed, complete the change by invoking the didChangeText method. If you can’t determine the affected range or replacement string before beginning changes, pass null for these values.

If the receiver is not editable, this method automatically returns false. This result prevents instances in which a text view could be changed by user actions even though it had been set to be noneditable.

Availability
See Also

shouldDrawInsertionPoint

Returns true if the receiver should draw its insertion point, false if the insertion point can’t or shouldn’t be drawn.

public boolean shouldDrawInsertionPoint()

Discussion

For example, you might not want to draw the insertion point if the receiver’s window isn’t key.)

See Also

smartDeleteRangeForProposedRange

Given proposedCharRange, returns an extended range that includes adjacent whitespace that should be deleted along with the proposed range in order to preserve proper spacing and punctuation of the text surrounding the deletion.

public NSRange smartDeleteRangeForProposedRange(NSRange proposedCharRange)

Discussion

NSTextView uses this method as necessary; you can also use it in implementing your own methods that delete text, typically when the selection granularity is SelectByWord. To do so, invoke this method with the proposed range to delete, then actually delete the range returned. If placing text on the pasteboard, however, you should put only the characters from the proposed range onto the pasteboard.

See Also

smartInsertAfterStringForString

Returns any whitespace that needs to be added after aString to preserve proper spacing and punctuation when aString is inserted into the receiver’s text over charRange.

public String smartInsertAfterStringForString(String aString, NSRange charRange)

Discussion

If aString is null or if smart insertion and deletion are disabled, this method returns null.

When inserting text, insert the following over charRange:

smartInsertBeforeStringForString

Returns any whitespace that needs to be added before aString to preserve proper spacing and punctuation when aString is inserted into the receiver’s text over charRange.

public String smartInsertBeforeStringForString(String aString, NSRange charRange)

Discussion

If aString is null or if smart insertion and deletion are disabled, this method returns null.

When inserting text, insert the following over charRange:

smartInsertDeleteEnabled

Returns true if the receiver inserts or deletes space around selected words so as to preserve proper spacing and punctuation, false if it inserts and deletes exactly what’s selected.

public boolean smartInsertDeleteEnabled()

See Also

spellCheckerDocumentTag

Returns a tag identifying the NSTextView text as a document for the spell checker server.

public int spellCheckerDocumentTag()

Discussion

The document tag is obtained by sending a "uniqueSpellDocumentTag" message to the spell server the first time this method is invoked for a particular group of NSTextViews. See the NSSpellChecker and NSSpellServer class specifications for more information on how this tag is used.

startSpeaking

This action method speaks the selected text, or all text if no selection.

public void startSpeaking(Object sender)

See Also

stopSpeaking

This action method stops the speaking of text.

public void stopSpeaking(Object sender)

See Also

textContainer

Returns the receiver’s text container.

public NSTextContainer textContainer()

See Also

textContainerInset

Returns the empty space the receiver leaves around its text container.

public NSSize textContainerInset()

See Also

textContainerOrigin

Returns the origin of the receiver’s text container, which is calculated from the receiver’s bounds rectangle, container inset, and the container’s used rect.

public NSPoint textContainerOrigin()

See Also

textStorage

Returns the receiver’s text storage object.

public NSTextStorage textStorage()

tightenKerning

This action method decreases the space between glyphs in the receiver’s selection, or for all glyphs if the receiver is a plain text view.

public void tightenKerning(Object sender)

Discussion

Kerning values are determined by the point size of the fonts in the selection.

See Also

toggleContinuousSpellChecking

This action method toggles whether continuous spell checking is enabled for the receiver.

public void toggleContinuousSpellChecking(Object sender)

See Also

toggleTraditionalCharacterShape

This action method toggles the NSCharacterShapeAttibuteName attribute at the current selection.

public void toggleTraditionalCharacterShape(Object sender)

turnOffKerning

This action method causes the receiver to use nominal glyph spacing for the glyphs in its selection, or for all glyphs if the receiver is a plain text view.

public void turnOffKerning(Object sender)

See Also

turnOffLigatures

This action method causes the receiver to use only required ligatures when setting text, for the glyphs in the selection if the receiver is a rich text view, or for all glyphs if it’s a plain text view.

public void turnOffLigatures(Object sender)

See Also

typingAttributes

Returns the current typing attributes.

public NSDictionary typingAttributes()

See Also

underline

public void underline(Object sender)

Discussion

Adds the underline attribute to the selected text attributes if absent; removes the attribute if not. Uses NSUnderlineStyleAttribute with a default value of 1.

unmarkText

Removes any marking from pending input text and accepts the text in its current state.

public void unmarkText()

updateDragTypeRegistration

public void updateDragTypeRegistration()

Discussion

If the receiver is editable and is a rich text view, causes all NSTextViews associated with the receiver’s NSLayoutManager to register their acceptable drag types. If the NSTextView isn’t editable or isn’t rich text, causes those NSTextViews to unregister their dragged types.

Subclasses can override this method to change the conditions for registering and unregistering drag types, whether as a group or individually based on the current state of the NSTextView. They can then invoke this method when that state changes to perform that reregistration.

See Also

updateFontPanel

Updates the Font panel to contain the font attributes of the selection.

public void updateFontPanel()

Discussion

Does nothing if the receiver doesn’t use the Font panel. You should never need to invoke this method directly, but you can override it if needed to handle additional font attributes.

See Also

updateInsertionPointStateAndRestartTimer

Updates the insertion point’s location and, if flag is true, restarts the blinking cursor timer.

public void updateInsertionPointStateAndRestartTimer(boolean flag)

Discussion

This method is invoked automatically whenever the insertion point needs to be moved; you should never need to invoke it directly, but you can override it to add different insertion point behavior.

See Also

updateRuler

Updates the NSRulerView in the receiver’s enclosing scroll view to reflect the selection’s paragraph and marker attributes.

public void updateRuler()

Discussion

Does nothing if the ruler isn’t visible or if the receiver doesn’t use the ruler. You should never need to invoke this method directly, but you can override this method if needed to handle additional ruler attributes.

See Also

useAllLigatures

This action method causes the receiver to use all ligatures available for the fonts and languages used when setting text, for the glyphs in the selection if the receiver is a rich text view, or for all glyphs if it’s a plain text view.

public void useAllLigatures(Object sender)

See Also

usesFindPanel

Returns whether the receiver allows for a find panel.

public boolean usesFindPanel()

Availability
See Also

usesFontPanel

Returns true if the text views sharing the receiver’s NSLayoutManager use the Font panel, false otherwise.

public boolean usesFontPanel()

Discussion

See setUsesFontPanel and rangeForUserCharacterAttributeChange for the effect this method has on an NSTextView’s behavior.

usesRuler

Returns true if the text views sharing the receiver’s NSLayoutManager use a ruler view, false otherwise.

public boolean usesRuler()

Discussion

See setUsesRuler and rangeForUserParagraphAttributeChange for the effect this has on an NSTextView’s behavior

See Also

useStandardKerning

This action method causes the receiver to use pair kerning data for the glyphs in its selection, or for all glyphs if the receiver is a plain text view.

public void useStandardKerning(Object sender)

Discussion

This data is taken from a font’s AFM file

See Also

useStandardLigatures

This action method causes the receiver to use the standard ligatures available for the fonts and languages used when setting text, for the glyphs in the selection if the receiver is a rich text view, or for all glyphs if it’s a plain text view.

public void useStandardLigatures(Object sender)

See Also

validAttributesForMarkedText

Returns an array of NSString names for the attributes supported by the receiver.

public NSArray validAttributesForMarkedText()

Discussion

The input server may choose to use some of these attributes in the text it inserts or in marked text. Returns an empty array if no attributes are supported. See NSAttributedString for the set of string constants that you could return in the array.

validRequestorForTypes

Returns this if sendType specifies a type of data the text view can put on the pasteboard and returnType contains a type of data the text view can read from the pasteboard; otherwise returns null.

public Object validRequestorForTypes(String sendType, String returnType)

See Also

writablePasteboardTypes

public NSArray writablePasteboardTypes()

Discussion

If the text view contains some selected data, this method returns an array of strings describing the types that can be written to the pasteboard immediately. You can override this method to add new supported types to the array of strings.

See Also

writeSelectionToPasteboardOfType

Writes the current selection to pboard using the given type.

public boolean writeSelectionToPasteboardOfType(NSPasteboard pboard, String type)

Discussion

The complete set of data types being written to pboard should be declared before invoking this method. Returns true if the data was successfully written.

This method should be invoked only from writeSelectionToPasteboardOfTypes. You can override this method to add support for writing new types of data to the pasteboard. You should invoke super’s implementation of the method to handle any types of data your overridden version does not.

See Also

writeSelectionToPasteboardOfTypes

Writes the current selection to pboard under each type in the types array.

public boolean writeSelectionToPasteboardOfTypes(NSPasteboard pboard, NSArray types)

Discussion

This method declares the data types on pboard and then invokes writeSelectionToPasteboardOfType for each type in the types array. Returns true if the data for any single type was written successfully.

You should not need to override this method. You might need to invoke this method if you are implementing a new type of pasteboard to handle services other than copy/paste or dragging.

Constants

These constants specify how much the text view extends the selection when the user drags the mouse. They’re used by selectionGranularity, setSelectionGranularity, and selectionRangeForProposedRange:

Constant

Description

SelectByCharacter

Extends the selection character by character.

SelectByWord

Extends the selection word by word.

SelectByParagraph

Extends the selection paragraph by paragraph.

These constants specify the preferred direction of selection. They’re used by selectionAffinity and setSelectedRange:

Constant

Description

SelectionAffinityUpstream

The selection is moving toward the top of the document.

SelectionAffinityDownstream

The selection is moving toward the bottom of the document.

These constants define the tags for performFindPanelAction:

Constant

Description

FindPanelActionShowFindPanel

Displays the find panel.

FindPanelActionNext

Finds the next instance of the queried text.

FindPanelActionPrevious

Finds the previous instance of the queried text.

FindPanelActionReplaceAll

Replaces all query instances within the text view.

FindPanelActionReplace

Replaces a single query instance within the text view.

FindPanelActionReplaceAndFind

Replaces a single query instance and finds the next.

FindPanelActionSetFindString

Sets the query string to the current selection.

FindPanelActionReplaceAllInSelection

Replaces all query instances within the selection.

FindPanelActionSelectAll

Selects all query instances in the text view.

Available in Mac OS X v10.4 and later.

FindPanelActionSelectAllInSelection

Selects all query instances within the selection.

Available in Mac OS X v10.4 and later.

Delegate Methods

textView

public NSArray textView(NSTextView aTextView, NSCellForTextAttachment cell, int charIndex)

Discussion

Invoked after the user clicks on cell at the specified charIndex location in aTextView. If textViewDraggedCellAtIndex is not used, both variations of this method allows aTextView to take care of dragging and pasting attachment cell, with the delegate responsible only for writing the attachment to the pasteboard. An array of types that can be written to the pasteboard for the given attachment should be returned.

The receiver should attempt to write the given attachment to pasteboard with the given type and return success or failure.

public boolean textView(NSTextView aTextView, NSCellForTextAttachment cell, int charIndex, NSPasteboard pasteboard, String type)

textView:completionsForPartialWordRange

Allows the delegate to modify the list of completions that will be presented for the partial word at the given range

public abstract NSArray textViewCompletionsForPartialWordRange(NSTextView textView, NSArray words, NSRange charRange)

Discussion

. Returning null or a zero-length array suppresses completion.

Availability

textViewClickedCell

Invoked after the user clicks on attachmentCell within cellFrame in aTextView and the cell wants to track the mouse.

public abstract void textViewClickedCell(NSTextView aTextView, NSCellForTextAttachment attachmentCell, NSRect cellFrame)

Discussion

This method has been deprecated in favor of textViewClickedCellAtIndex.

See Also

textViewClickedCellAtIndex

Invoked after the user clicks on cell within cellFrame at the specified charIndex in an NSTextView and the cell wants to track the mouse.

public abstract void textViewClickedCellAtIndex(NSTextView aTextView, NSCellForTextAttachment cell, NSRect cellFrame, int charIndex)

Discussion

The delegate can use this message as its cue to perform an action or select the attachment cell’s character. aTextView is the first NSTextView in a series shared by an NSLayoutManager, not necessarily the one that draws cell.

The delegate may subsequently receive a textViewDoubleClickedCellAtIndex message if the user continues to perform a double click.

See Also

textViewClickedOnLink

Invoked after the user clicks link in aTextView if the delegate does not respond to the textViewClickedOnLinkAtIndex message.

public abstract boolean textViewClickedOnLink(NSTextView aTextView, Object link)

Discussion

This method has been deprecated in favor of textViewClickedOnLinkAtIndex.

See Also

textViewClickedOnLinkAtIndex

Invoked after the user clicks link at the specified charIndex in an NSTextView.

public abstract boolean textViewClickedOnLinkAtIndex(NSTextView aTextView, Object link, int charIndex)

Discussion

The delegate can use this method to handle the click on the link. Returns true to indicate that the click was handled; otherwise returns false to allow the next responder to handle it.

See Also

textViewDidChangeSelection

Invoked when the selection changes in the NSTextView.

public abstract void textViewDidChangeSelection(NSNotification aNotification)

Discussion

The name of aNotification is TextViewDidChangeSelectionNotification.

textViewDidChangeTypingAttributes

Delegate method invoked when text view’s typing attributes change.

public abstract void textViewDidChangeTypingAttributes(NSNotification aNotification)

Discussion

The default name of aNotification is TextViewDidChangeTypingAttributesNotification.

Allows the delegate to modify the notification sent when the typing attributes of the text view change.

Availability

textViewDoCommandBySelector

Sent from NSTextView’s doCommandBySelector, this method allows the delegate to perform the command for the text view.

public abstract boolean textViewDoCommandBySelector(NSTextView aTextView, NSSelector aSelector)

Discussion

If the delegate returns true, the text view doesn’t perform aSelector; if the delegate returns false, the text view attempts to perform it. aTextView is the first NSTextView in a series shared by an NSLayoutManager.

textViewDoubleClickedCell

Invoked when the user double-clicks attachmentCell within cellFrame in aTextView and the cell wants to track the mouse.

public abstract void textViewDoubleClickedCell(NSTextView aTextView, NSCellForTextAttachment attachmentCell, NSRect cellFrame)

Discussion

This method has been deprecated in favor of textViewDoubleClickedCellAtIndex.

See Also

textViewDoubleClickedCellAtIndex

Invoked when the user double-clicks cell within cellFrame at the specified charIndex in an NSTextView and the cell wants to track the mouse.

public abstract void textViewDoubleClickedCellAtIndex(NSTextView aTextView, NSCellForTextAttachment cell, NSRect cellFrame, int charIndex)

Discussion

The delegate can use this message as its cue to perform an action, such as opening the file represented by the attachment. aTextView is the first NSTextView in a series shared by an NSLayoutManager, not necessarily the one that draws cell.

See Also

textViewDraggedCell

Invoked when the user attempts to drag cell from aRect within aTextView and cell wants to track the mouse.

public abstract void textViewDraggedCell(NSTextView aTextView, NSCellForTextAttachment cell, NSRect aRect, NSEvent theEvent)

Discussion

theEvent is the mouse-down event that preceded the mouse-dragged event.

This method has been deprecated in favor of textViewDraggedCellAtIndex.

See Also

textViewDraggedCellAtIndex

Invoked when the user attempts to drag cell from aRect within aTextView and the cell wants to track the mouse.

public abstract void textViewDraggedCellAtIndex(NSTextView aTextView, NSCellForTextAttachment cell, NSRect aRect, NSEvent theEvent, int charIndex)

Discussion

theEvent is the mouse-down event that preceded the mouse-dragged event. The charIndex parameter indicates the character position where the mouse button was clicked. The delegate can use this message as its cue to initiate a dragging operation.

See Also

textViewShouldChangeTextInRange

Invoked when an NSTextView needs to determine if text in the range affectedCharRange should be changed.

public abstract boolean textViewShouldChangeTextInRange(NSTextView aTextView, NSRange affectedCharRange, String replacementString)

Discussion

If characters in the text string are being changed, replacementString contains the characters that will replace the characters in affectedCharRange. If only text attributes are being changed, replacementString is null. The delegate can return true to allow the replacement, or false to reject the change.

The aTextView argument is the first NSTextView in a series shared by an NSLayoutManager.

If a delegate implements this method and not its multiple-selection replacement, textViewShouldChangeTextInRanges, it is called with an appropriate range and string. If a delegate implements the new method, then this one is ignored.

textViewShouldChangeTextInRanges

Invoked when an NSTextView needs to determine if text in the range affectedRanges should be changed.

public abstract boolean textViewShouldChangeTextInRanges(NSTextView textView, NSArray affectedRanges, NSArray replacementStrings)

Discussion

If characters in the text string are being changed, replacementStrings contains an array of elements indicating the characters that will replace the characters in affectedRanges. The replacementStrings array must either be null or else contain one element for each range in affectedRanges. If only text attributes are being changed, replacementStrings is null. The delegate can return true to allow the replacement, or false to reject the change.

The affectedRanges argument must be a non-null, non-empty array of objects responding to the NSValue rangeValue method, and in addition its elements must be sorted, non-overlapping, non-contiguous, and (except for the case of a single range) have non-zero-length.

The textView argument is the first NSTextView in a series shared by an NSLayoutManager.

Availability

textViewShouldChangeTypingAttributes

Allows the delegate to intervene to allow, prevent, or modify changes to the typing attributes in textView from those contained in oldTypingAttributes to those contained in newTypingAttributes.

public abstract NSDictionary textViewShouldChangeTypingAttributes(NSTextView textView, NSDictionary oldTypingAttributes, NSDictionary newTypingAttributes)

Availability

textViewWillChangeSelection

Invoked before an NSTextView finishes changing the selection—that is, when the last argument to a setSelectedRange message is false.

public abstract NSRange textViewWillChangeSelection(NSTextView aTextView, NSRange oldSelectedCharRange, NSRange newSelectedCharRange)

Discussion

oldSelectedCharRange is the original range of the selection. newSelectedCharRange is the proposed character range for the new selection. The delegate can return an adjusted range or return newSelectedCharRange unmodified.

The aTextView argument is the first NSTextView in a series shared by an NSLayoutManager.

This is a multiple-selection variant of the method.

public abstract NSArray textViewWillChangeSelection(NSTextView aTextView, NSArray oldSelectedCharRanges, NSArray newSelectedCharRanges)

Discussion

The oldSelectedCharRanges argument is an array containing the original ranges of the selection. The newSelectedCharRanges argument is and array containing the proposed character ranges for the new selection. The delegate can return an array containing the adjusted ranges or return newSelectedCharRanges unmodified.

The oldSelectedCharRanges and newSelectedCharRanges arguments must be non-null, non-empty arrays of objects responding to the NSValue rangeValue method, and in addition their elements must be sorted, non-overlapping, non-contiguous, and (except for the case of a single range) have non-zero-length.

In Mac OS X version 10.4 and later, if a delegate implements the old single-selection variant of this delegate method and not its multiple-selection replacement, then multiple selection is effectively disallowed; attempts to set the selected ranges call the old delegate method with the first subrange, and afterwards only a single selected range is set.

If a delegate implements both the multiple-selection variant and the single-selection variant, then the latter is ignored.

Availability

textViewWillDisplayToolTip

Allows the delegate to modify the tool tip that will be displayed from that specified by NSToolTipAttributeName, or to suppress display of the tooltip (by returning null).

public abstract String textViewWillDisplayToolTip(NSTextView textView, String tooltip, int characterIndex)

Availability

undoManagerForTextView

Returns the undo manager instance for the text view specified by aTextView.

public abstract NSUndoManager undoManagerForTextView(NSTextView aTextView)

Discussion

This method provides the flexibility to return a custom undo manager for the text view. Although NSTextView implements undo and redo for changes to text, applications may need a custom undo manager to handle interactions between changes to text and changes to other items in the application.

Notifications

NSTextView posts the following notifications as well as those declared by its superclasses, particularly NSText. See the “Notifications” section in the NSText class specification for those other notifications.

TextViewDidChangeSelectionNotification

Posted when the selected range of characters changes.

NSTextView posts this notification whenever setSelectedRange is invoked, either directly or through the many methods (mouseDown, selectAll, and so on) that invoke it indirectly. When the user is selecting text, this notification is posted only once, at the end of the selection operation. The NSTextView’s delegate receives a textViewDidChangeSelection message when this notification is posted.

Key

Value

"NSOldSelectedCharacterRange"

An NSRange with the originally selected range.

The notification object is the notifying NSTextView. The userInfo dictionary contains the following information:

TextViewWillChangeNotifyingTextViewNotification

Posted when a new NSTextView is established as the NSTextView that sends notifications.

This notification allows observers to reregister themselves for the new NSTextView. Methods such as removeTextContainerAtIndex, textContainerChangedTextView, and insertTextContainerAtIndex cause this notification to be posted.

Key

Value

"NSOldNotifyingTextView"

The old NSTextView, if one exists, otherwise null.

"NSNewNotifyingTextView"

The new NSTextView, if one exists, otherwise null.

The notification object is the old notifying NSTextView, or null. The userInfo dictionary contains the following information:

There’s no delegate method associated with this notification. The text-handling system ensures that when a new NSTextView replaces an old one as the notifying NSTextView, the existing delegate becomes the delegate of the new NSTextView, and the delegate is registered to receive NSTextView notifications from the new notifying NSTextView. All other observers are responsible for registering themselves on receiving this notification.

See Also

TextViewDidChangeTypingAttributesNotification

Posted when there is a change in the typing attributes within an NSTextView. This notification is posted, via the textViewDidChangeTypingAttributes delegate method, whether or not text has changed as a result of the attribute change.

Availability


Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.