NSTextInputClient

Inheritance

Not Applicable

Conforms To

Not Applicable

Import Statement

Swift

import AppKit

Objective-C

@import AppKit;

Availability

Available in OS X v10.5 and later.

The NSTextInputClient protocol defines the methods that Cocoa text views must implement in order to interact properly with the text input management system. To create another text view class, you can either subclass NSTextView (and not NSText, for historical reasons), or subclass NSView and implement the NSTextInputClient protocol

Important

Methods specific to the NSTextInputClient protocol are intended for dealing with text input and generally are not suitable for other purposes.

Import Statement

Availability

See Also

Declaration

Swift

funcunmarkText()

Objective-C

- (void)unmarkText

Discussion

The receiver 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. If there is no marked text, the invocation of this method has no effect.

Parameters

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

actualRange

The actual range of the returned string if it was adjusted, for example, to a grapheme cluster boundary or for performance or other reasons. NULL if range was not adjusted.

Return Value

The string created from the given range. May return nil.

Discussion

An implementation of this method should be prepared for aRange 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 aRange. If the location of aRange is completely outside of the document’s range, return nil.

Declaration

Parameters

aString

The text to insert, either an NSString or NSAttributedString instance.

replacementRange

The range of content to replace in the receiver’s text storage.

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.

Declaration

Parameters

aPoint

The point to test, 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’s bounding rectangle.

Parameters

If non-NULL, contains the character range corresponding to the returned area if it was adjusted, for example, to a grapheme cluster boundary or characters in the first line fragment.

Return Value

The boundary rectangle for the given range of characters, in screen coordinates. The rectangle’s size value can be negative if the text flows to the left.

Discussion

If aRange spans multiple lines of text in the text view, the rectangle returned is the one surrounding the characters in the first line. In that case actualRange contains the range covered by the first rect, so you can query all line fragments by invoking this method repeatedly. If the length of aRange 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

Declaration

Swift

funcdoCommandBySelector(_aSelector: Selector)

Objective-C

- (void)doCommandBySelector:(SEL)aSelector

Parameters

aSelector

The selector to invoke.

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

Declaration

Return Value

The attributed string of the receiver’s text storage.

Discussion

Implementation of this method is optional. A class adopting the NSTextInputClient protocol can implement this interface if it can be done efficiently to enable callers of this interface to access arbitrary portions of the receiver's content more efficiently.

Declaration

Parameters

aPoint

The point to test.

Return Value

The fraction of the distance aPoint is through the glyph in which it lies. May be 0 or 1 if aPoint is not within the bounding rectangle of a glyph (0 if the point is to the left or above the glyph; 1 if it's to the right or below).

Discussion

Implementation of this method is optional. This allows caller to perform precise selection handling.

For purposes such as dragging out a selection or placing the insertion point, a partial percentage less than or equal to 0.5 indicates that aPoint should be considered as falling before the glyph; a partial percentage greater than 0.5 indicates that it should be considered as falling after the glyph. If the nearest glyph doesn’t lie under aPoint at all (for example, if aPoint is beyond the beginning or end of a line), this ratio is 0 or 1.

For example, if the glyph stream contains the glyphs “A” and “b”, with the width of “A” being 13 points, and aPoint is 8 points from the left side of “A”, then the fraction of the distance is 8/13, or 0.615. In this case, the aPoint should be considered as falling between “A” and “b” for purposes such as dragging out a selection or placing the insertion point.