---

NSTextInput

Overview

The NSTextInput interface defines the methods that Cocoa text views must implement in order to interact properly with the text input management system. NSTextView and its abstract superclass NSText are the only classes included in Cocoa that implement NSTextInput. To create another text view class, you can either subclass NSTextView (and not NSText, for historical reasons), or subclass NSView and implement the NSTextInput interface.

Tasks

Marked Text

• hasMarkedText
• markedRange
• selectedRange
• setMarkedTextAndSelectedRange
• unmarkText
• validAttributesForMarkedText

Text Storage

• attributedSubstringWithRange
• insertText

Character Coordinates

• characterIndexForPoint
• firstRectForCharacterRange

Key Bindings

• doCommandBySelector

Other

• conversationIdentifier

Instance Methods

attributedSubstringWithRange

Returns attributed string at theRange.

public abstract NSAttributedString attributedSubstringWithRange(NSRange theRange)

Discussion

This method allows input mangers to query any range in text storage.

An implementation of this method should be prepared theRange to be out-of-bounds. The InkWell text input service can ask for the contents of the text input client that extends beyond the document’s range. In this case, you should return the intersection of the document’s range and theRange. If the location of theRange is completely outside of the document’s range, return null.

characterIndexForPoint

Returns the index of the character whose frame rectangle includes thePoint.

public abstract int characterIndexForPoint(NSPoint thePoint)

Discussion

The returned index measures from the start of the receiver’s text storage. thePoint is in the screen coordinate system. Returns NSArray.NotFound if the cursor is not within a character.

conversationIdentifier

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

public abstract int conversationIdentifier()

Discussion

Each text view within an application should return a unique identifier (typically its address). However, multiple text views sharing the same text storage must all return the same identifier.

doCommandBySelector

Invokes aSelector if possible.

public abstract void doCommandBySelector(NSSelector aSelector)

Discussion

If aSelector cannot be invoked, then doCommandBySelector should not pass this message up the responder chain. NSResponder also implements this method, and it does forward uninvokable commands up the responder chain, but a text view should not. A text view implementing the NSTextInput interface will inherit from NSView, which inherits from NSResponder, so your implementation of this method will override the one in NSResponder. It should not call super.

See Also

• interpretKeyEvents (NSResponder)
• doCommandBySelector (NSKeyBindingResponder)

firstRectForCharacterRange

public abstract NSRect firstRectForCharacterRange(NSRange theRange)

Discussion

Returns the first frame rectangle for characters in theRange, in screen coordinates. If theRange spans multiple lines of text in the text view, the rectangle returned is the one for the characters in the first line. If the length of theRange is 0 (as it would be if there is nothing selected at the insertion point), the rectangle will coincide with the insertion point, and its width will be 0.

hasMarkedText

Returns true if the receiver has marked text, false if it doesn’t.

public abstract boolean hasMarkedText()

Discussion

Unlike other methods in this protocol, this one is not called by an input server. The text view itself may call this method to determine whether there currently is marked text. NSTextView, for example, disables the Edit>Copy menu item when this method returns true.

See Also

• markedRange

insertText

Inserts aString into the receiver’s text storage.

public abstract void insertText(Object aString)

Discussion

aString can be either a String or an NSAttributedString.

markedRange

Returns the range of the marked text.

public abstract NSRange markedRange()

Discussion

The returned range measures from the start of the receiver’s text storage. The return value’s location is NSArray.NotFound, and its length is 0 if and only if hasMarkedText returns false.

See Also

• setMarkedTextAndSelectedRange
• unmarkText
• hasMarkedText

selectedRange

Returns the range of selected text.

public abstract NSRange selectedRange()

Discussion

The returned range measures from the start of the receiver’s text storage. If there is no selection, the return value’s location is NSArray.NotFound, and its length is 0.

See Also

• setMarkedTextAndSelectedRange

setMarkedTextAndSelectedRange

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

public abstract void setMarkedTextAndSelectedRange(Object aString, NSRange selRange)

Discussion

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

See Also

• selectedRange
• unmarkText

unmarkText

Removes any marking from pending input text, and disposes of the marked text as it wishes. The text view should accept the marked text as if it had been inserted normally.

public abstract void unmarkText()

See Also

• selectedRange
• setMarkedTextAndSelectedRange

validAttributesForMarkedText

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

public abstract 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.

---