NSTextInput

Adopted by: NSInputManager

Declared in: AppKit/NSInputManager.h

Protocol Description

This class specification is incomplete and has not received a technical review. It is included in this release to test the linkage between the application development tools and the on-line documentation. What information it contains should be considered preliminary and subject to change.

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 reponsible 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 markedTextWillBeAbandoned: to the current Input Manager. It must send markedTextWillBeAbandoned: 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 NSResopnder) 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:

- getMarkedText:selectedRange:

- hasMarkedText

- unmarkText

Other

- conversationIdentifier

- doCommandBySelector:

- insertText:

Protocol Methods

conversationIdentifier

- (long)conversationIdentifier

<<more information forthcoming>>

doCommandBySelector:

- (void)doCommandBySelector:(SEL)aSelector

<<more information forthcoming>>

See Also: - interpretKeyEvents: (NSResponder)

getMarkedText:selectedRange:

- (void)getMarkedText:(out NSString **)aString selectedRange:(out NSRange *)aRange

hasMarkedText

- (BOOL)hasMarkedText

<<more information forthcoming>>

insertText:

- (void)insertText:(NSString *)aString

<<more information forthcoming>>

See Also: - interpretKeyEvents: (NSResponder)

setMarkedText:selectedRange:

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

unmarkText

- (void)unmarkText

<<more information forthcoming>>