PATH  Documentation > Mac OS X > Application Kit Reference: Objective-C

Table of Contents

NSTextInput


Adopted by: NSInputManager
Declared in:
AppKit/NSInputManager.h



Protocol Description


The methods of the NSTextInput protocol are implemented by objects-for example, responders-that handle text input. A client object such as a text view ("the client object") that speaks this protocol must be responsible for the following things:

  1. The client object must maintain a "marked region" within which text input and, possibly, character conversion take place. The marked region may have a length of zero. The client object must maintain an "insertion point"-typically at the end of the marked region, though it may be within the region. The "selection" within the client object, if any, is entirely contained within the marked region whenever there is a marked region.
  2. The client object is responsible for sending messages to current Input Manager when the mouse goes down inside the marked region, or when the mouse leaves the marked region. Within the marked region, this allows the selection to be changed. Out of the marked region, it allows the region to be "abandoned". (See below.)
  3. When there is a non-zero marked region, the client object is responsible for notifying the input manager when the selection changes, or when other programmatic changes to the text affect the marked region. It can do this by sending a message to set the selection, abandon the marked region, etc.
  4. When the client object relinquishes first responder, it will typically send markedTextAbandoned: to the current Input Manager. It must send markedTextAbandoned: when its insertion point (or selection moves outside the marked range. The server will typically respond by simply unmarking the region, but may remove the marked region's text entirely.

If this protocol is not implemented by a client object that does have a keyDown: method, then in-line input is not possible for that client object, and will have to be handled externally.

The NSTextInput protocol is implemented by an Input Manager to receive input from the server on behalf of the current client, and otherwise mediate between the client object and the server. It then forwards the corresponding messages to the client, or gets information from the client to pass back to the server, as appropriate.

The message passing between NSApp, Input Manager, User Interface object, and Server is all synchronous. That is, e.g., when the Input Manager sends a message to Server, any reply comes back and is relayed to the User Interface object before the original message returns.

A key binding manager splits the stream of keyDown: messages (intercepted by NSResponder) into commands and text. If there is an Input Manager in the loop, it will further use any of these NSTextInput messages to control the marked region.



Method Types


Marking text
- setMarkedText:selectedRange:
- hasMarkedText
- markedRange
- selectedRange
- unmarkText
- validAttributesForMarkedText
Other
- attributedSubstringFromRange:
- characterIndexForPoint:
- conversationIdentifier
- doCommandBySelector:
- firstRectForCharacterRange:
- insertText:


Instance Methods



attributedSubstringFromRange:

- (NSAttributedString *)attributedSubstringFromRange:(NSRange)theRange

Returns attributed string at theRange. This allows input mangers to query any range in backing-store.

characterIndexForPoint:

- (unsigned int)characterIndexForPoint:(NSPoint)thePoint

Returns the index for character that is nearest to thePoint. thePoint is in the screen coordinate system.

conversationIdentifier

- (long)conversationIdentifier

Returns a number used to identify the receiver's input management session to the input server.

More information forthcoming.



doCommandBySelector:

- (void)doCommandBySelector:(SEL)aSelector

Attempts to invoke aSelector or pass the message up the responder chain. This method is invoked by an input manager in response to an interpretKeyEvents: message.

More information forthcoming.

See Also: - interpretKeyEvents: (NSResponder)



firstRectForCharacterRange:

- (NSRect)firstRectForCharacterRange:(NSRange)theRange

Returns the first frame of rectangles for theRange in screen coordinate system.

hasMarkedText

- (BOOL)hasMarkedText

Returns YES if the receiver has text that's still being interpreted by the input manager, NO if it doesn't.

More information forthcoming.



insertText:

- (void)insertText:(NSString *)aString

Inserts aString into the receiver's text stream. This method is invoked by an input manager in response to an interpretKeyEvents: message.

More information forthcoming.

See Also: - interpretKeyEvents: (NSResponder)



markedRange

- (NSRange)markedRange

Returns the range for the marked region. If hasMarkedText returns NO, markedRange returns NSNotFound for location and zero-length range.

selectedRange

- (NSRange)selectedRange

Returns the range for selected region. Just like markedRange , the location field contains the character index from the text beginning.

setMarkedText:selectedRange:

- (void)setMarkedText:(NSString *)aString selectedRange:(NSRange)selRange

Description forthcoming.

unmarkText

- (void)unmarkText

Removes any marking from pending input text, and accepts the text in its current state.

More information forthcoming.



validAttributesForMarkedText

- (NSArray*)validAttributesForMarkedText

Description forthcoming.


Table of Contents