PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSTextInput


Package:
com.apple.yellow.application

Interface 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
setMarkedTextAndSelectedRange
hasMarkedText
markedRange
selectedRange
unmarkText
validAttributesForMarkedText
Other
attributedSubstringWithRange
characterIndexForPoint
conversationIdentifier
doCommandBySelector
firstRectForCharacterRange
insertText


Instance Methods



attributedSubstringWithRange

public abstract NSAttributedString attributedSubstringWithRange(NSRange theRange)

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

characterIndexForPoint

public abstract int characterIndexForPoint(NSPoint thePoint)

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

conversationIdentifier

public abstract int conversationIdentifier()

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

More information forthcoming.



doCommandBySelector

public abstract void doCommandBySelector(NSSelector 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

public abstract NSRect firstRectForCharacterRange(NSRange theRange)

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

hasMarkedText

public abstract boolean hasMarkedText()

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

More information forthcoming.



insertText

public abstract void insertText(Object 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

public abstract NSRange markedRange()

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

selectedRange

public abstract NSRange selectedRange()

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

setMarkedTextAndSelectedRange

public abstract void setMarkedTextAndSelectedRange( Object aString, NSRange selRange)

Description forthcoming.

unmarkText

public abstract void unmarkText()

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

More information forthcoming.



validAttributesForMarkedText

public abstract NSArray validAttributesForMarkedText()

Description forthcoming.


Table of Contents