[Previous] [Protocol List] [Next]

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

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 responer chain. This method is invoked by an input manager in response to an interpretKeyEvents: message.

<<more information forthcoming>>

See Also: - interpretKeyEvents: (NSResponder)



getMarkedText:selectedRange:

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

Returns by reference in aString the receiver's marked text, if any, and in aRange the range of the selection within aString (not in terms of the receiver's entire text stream).

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)



setMarkedText:selectedRange:

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

<<forthcoming>>

unmarkText

- (void)unmarkText

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

<<more information forthcoming>>




[Previous] [Next]