Mac Developer Library

Developer

AppKit Framework Reference NSTextInput Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSTextInput

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns a Boolean value indicating whether or not the receiver has marked text. (required)

    Declaration

    Objective-C

    - (BOOL)hasMarkedText

    Return Value

    YEStrue if the receiver has marked text, NOfalse 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 YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    – markedRange

  • markedRange - markedRange (OS X v10.6)

    Returns the range of the marked text. (required)

    Declaration

    Objective-C

    - (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 NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns the range of selected text. (required)

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • 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)

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • unmarkText - unmarkText (OS X v10.6)

    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)

    Declaration

    Objective-C

    - (void)unmarkText

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • insertText: - insertText: (OS X v10.6)

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Invokes the given selector if possible. (required)

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    – interpretKeyEvents: (NSResponder)
    – doCommandBySelector: (NSResponder)

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.