NSTextInput Protocol Reference

Adopted by
NSInputManager
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSInputManager.h
Companion guides
Text System Overview
Text Input Management

Overview

The NSTextInput protocol 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 protocol.

Tasks

Marked Text

Text Storage

Character Coordinates

Key Bindings

Other

Instance Methods

attributedSubstringFromRange:

Returns an attributed string derived from the given range in the receiver's text storage. (required)

- (NSAttributedString *)attributedSubstringFromRange:(NSRange)theRange
Parameters
theRange

The range in the text storage from which to create the returned string.

Return Value

The string created from the given range.

Discussion

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

An implementation of this method should be prepared for theRange to be out-of-bounds. For example, 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 nil.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSInputManager.h

characterIndexForPoint:

Returns the index of the character whose frame rectangle includes the given point. (required)

- (NSUInteger)characterIndexForPoint:(NSPoint)thePoint
Parameters
thePoint

A point, in screen coordinates.

Return Value

The character index, measured from the start of the receiver’s text storage, of the character containing the given point. Returns NSNotFound if the cursor is not within a character.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSInputManager.h

conversationIdentifier

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

- (NSInteger)conversationIdentifier
Return Value

The identifying number of the receiver.

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSInputManager.h

doCommandBySelector:

Invokes the given selector if possible. (required)

- (void)doCommandBySelector:(SEL)aSelector
Parameters
aSelector

The selector to be invoked.

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 protocol inherits from NSView, which inherits from NSResponder, so your implementation of this method will override the one in NSResponder. It should not call super.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSInputManager.h

firstRectForCharacterRange:

Returns the first frame rectangle for characters in the given range, in screen coordinates. (required)

- (NSRect)firstRectForCharacterRange:(NSRange)theRange
Parameters
theRange

The character range whose frame is returned.

Return Value

The frame rectangle for the given range of characters.

Discussion

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 coincides with the insertion point, and its width is 0.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSInputManager.h

hasMarkedText

Returns a Boolean value indicating whether or not the receiver has marked text. (required)

- (BOOL)hasMarkedText
Return Value

YES if the receiver has marked text, NO if it doesn’t.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSInputManager.h

insertText:

Inserts the given string into the receiver’s text storage. (required)

- (void)insertText:(id)aString
Parameters
aString

Either an NSString or an NSAttributedString object.

Discussion

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 text storage directly. Because this method pertains to the actions of the user, the text view must be editable for the insertion to work.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSInputManager.h

markedRange

Returns the range of the marked text. (required)

- (NSRange)markedRange
Return Value

The range of marked text.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSInputManager.h

selectedRange

Returns the range of selected text. (required)

- (NSRange)selectedRange
Return Value

The range of selected text.

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 NSNotFound, and its length is 0.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSInputManager.h

setMarkedText:selectedRange:

Replaces currently marked text in the receiver’s text storage with the given string and sets the selection to the given range, computed from the beginning of the marked text. (required)

- (void)setMarkedText:(id)aString selectedRange:(NSRange)selRange
Parameters
aString

Either an NSString or an NSAttributedString object; must not be nil.

selRange

The range within aString to set as the selection.

Discussion

If there is no marked text, the current selection is replaced. If there is no selection, the string is inserted at the insertion point.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSInputManager.h

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. (required)

- (void)unmarkText
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSInputManager.h

validAttributesForMarkedText

Returns an array of names for the attributes supported by the receiver. (required)

- (NSArray *)validAttributesForMarkedText
Return Value

An array of NSString objects representing names for the supported attributes.

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 Additions for the set of string constants that you could return in the array.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSInputManager.h


© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-22)

Did this document help you? Yes It's good, but... Not helpful...