Mac Developer Library

Developer

AppKit Framework Reference NSTextInputClient Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSTextInputClient

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

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.
  • Returns a Boolean value indicating whether the receiver has marked text. (required)

    Declaration

    Swift

    func hasMarkedText() -> Bool

    Objective-C

    - (BOOL)hasMarkedText

    Return Value

    YEStrue if the receiver has marked text; otherwise NOfalse.

    Discussion

    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;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – markedRange

  • Returns the range of the marked text. (required)

    Declaration

    Swift

    func markedRange() -> NSRange

    Objective-C

    - (NSRange)markedRange

    Return Value

    The range of marked text or {NSNotFound, 0} if there is no marked range.

    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;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the range of selected text. (required)

    Declaration

    Swift

    func selectedRange() -> NSRange

    Objective-C

    - (NSRange)selectedRange

    Return Value

    The range of selected text or {NSNotFound, 0} if there is no selection.

    Discussion

    The returned range measures from the start of the receiver’s text storage, that is, from 0 to the document length.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Replaces a specified range in the receiver’s text storage with the given string and sets the selection. (required)

    Declaration

    Swift

    func setMarkedText(_ aString: AnyObject, selectedRange selectedRange: NSRange, replacementRange replacementRange: NSRange)

    Objective-C

    - (void)setMarkedText:(id)aString selectedRange:(NSRange)selectedRange replacementRange:(NSRange)replacementRange

    Parameters

    aString

    The string to insert. Can be either an NSString or NSAttributedString instance.

    selectedRange

    The range to set as the selection, computed from the beginning of the inserted string.

    replacementRange

    The range to replace, computed from the beginning of the marked text.

    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.

    When aString is an NSString object, the receiver is expected to render the marked text with distinguishing appearance (for example, NSTextView renders with markedTextAttributes).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Unmarks the marked text. (required)

    Declaration

    Swift

    func unmarkText()

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of attribute names recognized by the receiver. (required)

    Declaration

    Swift

    func validAttributesForMarkedText() -> [AnyObject]

    Objective-C

    - (NSArray *)validAttributesForMarkedText

    Return Value

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

    Discussion

    Returns an empty array if no attributes are supported. See NSAttributedString AppKit Additions Reference for the set of string constants representing standard attributes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func attributedSubstringForProposedRange(_ aRange: NSRange, actualRange actualRange: NSRangePointer) -> NSAttributedString?

    Objective-C

    - (NSAttributedString *)attributedSubstringForProposedRange:(NSRange)aRange actualRange:(NSRangePointer)actualRange

    Parameters

    aRange

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Inserts the given string into the receiver, replacing the specified content. (required)

    Declaration

    Swift

    func insertText(_ aString: AnyObject, replacementRange replacementRange: NSRange)

    Objective-C

    - (void)insertText:(id)aString replacementRange:(NSRange)replacementRange

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func characterIndexForPoint(_ aPoint: NSPoint) -> Int

    Objective-C

    - (NSUInteger)characterIndexForPoint:(NSPoint)aPoint

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the first logical boundary rectangle for characters in the given range. (required)

    Declaration

    Swift

    func firstRectForCharacterRange(_ aRange: NSRange, actualRange actualRange: NSRangePointer) -> NSRect

    Objective-C

    - (NSRect)firstRectForCharacterRange:(NSRange)aRange actualRange:(NSRangePointer)actualRange

    Parameters

    aRange

    The character range whose boundary rectangle is returned.

    actualRange

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Invokes the action specified by the given selector. (required)

    Declaration

    Swift

    func doCommandBySelector(_ 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    interpretKeyEvents: (NSResponder)
    doCommandBySelector: (NSResponder)

  • Returns an attributed string representing the receiver's text storage.

    Declaration

    Swift

    optional func attributedString() -> NSAttributedString

    Objective-C

    - (NSAttributedString *)attributedString

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the fraction of the distance from the left side of the character to the right side that a given point lies.

    Declaration

    Swift

    optional func fractionOfDistanceThroughGlyphForPoint(_ aPoint: NSPoint) -> CGFloat

    Objective-C

    - (CGFloat)fractionOfDistanceThroughGlyphForPoint:(NSPoint)aPoint

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the baseline position of a given character relative to the origin of rectangle returned by firstRectForCharacterRange:actualRange:.

    Declaration

    Swift

    optional func baselineDeltaForCharacterAtIndex(_ anIndex: Int) -> CGFloat

    Objective-C

    - (CGFloat)baselineDeltaForCharacterAtIndex:(NSUInteger)anIndex

    Parameters

    anIndex

    Index of the character whose baseline is tested.

    Return Value

    The vertical distance, in points, between the baseline of the character at anIndex and the rectangle origin.

    Discussion

    Implementation of this method is optional. This information allows the caller to determine finer-grained character positioning within the text storage of the text view adopting NSTextInputClient.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the window level of the receiver.

    Declaration

    Swift

    optional func windowLevel() -> Int

    Objective-C

    - (NSInteger)windowLevel

    Return Value

    The window level of the receiver.

    Discussion

    Implementation of this method is optional. A class adopting NSTextInputClient can implement this interface to specify its window level if it is higher than NSFloatingWindowLevel.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Informs the text input management system whether the protocol-conforming client renders the character at the given index vertically.

    Declaration

    Swift

    optional func drawsVerticallyForCharacterAtIndex(_ charIndex: Int) -> Bool

    Objective-C

    - (BOOL)drawsVerticallyForCharacterAtIndex:(NSUInteger)charIndex

    Parameters

    charIndex

    The index of the character to test.

    Return Value

    YEStrue if the character is rendered vertically; otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.