Mac Developer Library

Developer

Carbon Framework Reference IMKTextInput Protocol Reference

Options
Deployment Target:

On This Page
Language:

IMKTextInput

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import Carbon

Objective-C

@import Carbon;

Availability


Available in OS X v10.5 and later.

The IMKTextInput protocol defines methods for communicating with client input sessions. An input method uses this protocol to send text or obtain information about client text.

  • Sends fully converted text to an input session. (required)

    Declaration

    Swift

    func insertText(_ string: AnyObject!, replacementRange replacementRange: NSRange)

    Objective-C

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

    Parameters

    string

    The converted text.

    replacementRange

    The replacement range. This parameter allows input methods to insert text at a location other than the current selection. If you use it, the replacement range should be relative to the beginning of the client document. If the string should be inserted at the current selection specify a replacement range with a location and length of NSNotFound. If the client does not support the TSMDocumentAccess protocol, this method ignores the replacement range string.

    Discussion

    When an input method finishes a conversion it calls this method and passes the finished text as an NSString or NSAttributedString object.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Inserts the provided text and marks it to indicate that it is part of an active input session. (required)

    Declaration

    Swift

    func setMarkedText(_ string: AnyObject!, selectionRange selectionRange: NSRange, replacementRange replacementRange: NSRange)

    Objective-C

    - (void)setMarkedText:(id)string selectionRange:(NSRange)selectionRange replacementRange:(NSRange)replacementRange

    Parameters

    string

    An NSString or an NSAttributedString object. Passing an NSString object produces default marking. On a 72 dpi screen the default marking is a 2 pixel black underline for the entire string.

    selectionRange

    The selection range, which is relative to the string parameter. For example, if the string contains the these characters: "INPUT" and the range is (5,0), the selection is set immediately after the "T."

    replacementRange

    A range that specifies the location in the client document where the marked text should be placed. If the marked text should be placed at the current cursor location replacementRange equals NSNotFound. If not NSNotFound, the replacement range is relative to the client document ( 0 is the beginning of the document) and NOT the string parameter. Currently, the replacement range is sent to the client via the kEventParamTextInputSendReplaceRange Carbon Event parameter. For this parameter to be used the client must support the TSMDocumentAccess protocol. If a client does not support the TSMDocumentAccess protocol the replacementRange parameter is ignored.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns the current selection range. (required)

    Declaration

    Swift

    func selectedRange() -> NSRange

    Objective-C

    - (NSRange)selectedRange

    Return Value

    The current selection range, relative to the client document. If the client does not support the TSMDocumentAccess protocol the returned range has a location value of NSNotFound and a length of NSNotFound.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns the range in the document that is occupied by marked text, that is, the current inline session. (required)

    Declaration

    Swift

    func markedRange() -> NSRange

    Objective-C

    - (NSRange)markedRange

    Return Value

    The range of the marked text.

    Discussion

    While an input method is converting text input and sending it to the client, the client maintains a range of text that is marked. The marked text is underlined in certain ways to indicate to the user that their keystrokes are in the process of being converted by an input method and the conversion has not yet been finalized. The input method uses this method to request that range.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns the attributed string for the provided range of text. (required)

    Declaration

    Swift

    func attributedSubstringFromRange(_ range: NSRange) -> NSAttributedString!

    Objective-C

    - (NSAttributedString *)attributedSubstringFromRange:(NSRange)range

    Parameters

    range

    The range of text, relative to the document, that specifies the string to retrieve.

    Return Value

    The attributed string. See the CTStringAttributes.h header file for the attributes that can be included in this string. If the client does not support the TSMDocumentAccess protocol, the returned string is created from data obtained by sending the client application a kEventTextInputGetSelectedText Carbon event.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns the location in the text document that maps to a global point. (required)

    Declaration

    Swift

    func characterIndexForPoint(_ point: NSPoint, tracking mappingMode: IMKLocationToOffsetMappingMode, inMarkedRange inMarkedRange: UnsafeMutablePointer<ObjCBool>) -> Int

    Objective-C

    - (NSInteger)characterIndexForPoint:(NSPoint)point tracking:(IMKLocationToOffsetMappingMode)mappingMode inMarkedRange:(BOOL *)inMarkedRange

    Parameters

    point

    The point to map. This is a global point, typically from a mouse down operation.

    mappingMode

    The mapping mode. If the input method is tracking the mouse, the mode should be kIMKMouseTrackingMode. If the input method simply wants to map a screen position to an offset, than set the mode to kIMKNearestBoundaryMode.

    inMarkedRange

    On return, if the point is inside the text body and inside the marked range, this parameter is set to YEStrue. Otherwise, if the point is outside the marked range, then on return this parameter is set to NOfalse.

    Return Value

    The location in the text document.

    Discussion

    If the input method is tracking the mouse, the application should highlight to the active inline area.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns a dictionary of text attributes for the text at the provided character index. (required)

    Declaration

    Swift

    func attributesForCharacterIndex(_ index: Int, lineHeightRectangle lineRect: UnsafeMutablePointer<NSRect>) -> [NSObject : AnyObject]!

    Objective-C

    - (NSDictionary *)attributesForCharacterIndex:(NSUInteger)index lineHeightRectangle:(NSRect *)lineRect

    Parameters

    index

    The character index whose attributes you want to retrieve. The index is relative to the inline session. Note that if there is no inline session the value of index should be 0, which indicates that the information should be taken from the current selection.

    lineRect

    On return, a rectangle that frames a one-pixel wide rectangle with the height of the line. This rectangle is oriented the same way the line is oriented.

    Return Value

    A dictionary that contains the text attributes for the text at the provided character index. The attributes include the CTFontRef for the text at that index, and the text orientation. The text orientation is indicated by an NSNumber whose value is 0 if the text is vertically oriented and 1 if the text is horizontally oriented. The key for this value is IMKTextOrientationKey.

    Discussion

    An input method calls this method to place a candidate window on screen.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • length() - length Required

    Returns the length of the text document. (required)

    Declaration

    Swift

    func length() -> Int

    Objective-C

    - (NSInteger)length

    Return Value

    The text document length. If the client does not support the TSMDocumentAccess protocol the returned value is NSNotFound.

    Discussion

    This method can be computationally expense depending on how the client stores text. For that reason, you should avoid calling this method frequently.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of names for the attributes supported by the receiver. (required)

    Declaration

    Swift

    func validAttributesForMarkedText() -> [AnyObject]!

    Objective-C

    - (NSArray *)validAttributesForMarkedText

    Return Value

    An array of attribute names.

    Discussion

    Input methods should restrict the attributes used to create attributed strings to the attributes in this array.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Overrides the current keyboard. (required)

    Declaration

    Swift

    func overrideKeyboardWithKeyboardNamed(_ keyboardUniqueName: String!)

    Objective-C

    - (void)overrideKeyboardWithKeyboardNamed:(NSString *)keyboardUniqueName

    Parameters

    keyboardUniqueName

    A unique keyboard name.

    Discussion

    The client tries to locate a keyboard layout with that name in the input method bundle. If a layout is found it is passed to the client who then tells the text service manager to use that layout for keyboard events. Input methods should call the method each time they are activated. If an input method uses a system keyboard to override the current keyboard, they are responsible for determining the unique name of the keyboard. Typically this name a DNS type name such as: com.apple.<some name>.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Selects a new input mode. (required)

    Declaration

    Swift

    func selectInputMode(_ modeIdentifier: String!)

    Objective-C

    - (void)selectInputMode:(NSString *)modeIdentifier

    Parameters

    modeIdentifier

    An NSString object with a DNS format, such as: com.<company name> .inputmethod.<some name>. The identifier should match one of the keys in the component input mode dictionary.

    Discussion

    This method allows an input method to change its mode directly.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Tests to see if the current input session supports Unicode text. (required)

    Declaration

    Swift

    func supportsUnicode() -> Bool

    Objective-C

    - (BOOL)supportsUnicode

    Return Value

    YEStrue if the current input session supports Unicode text; otherwise NOfalse.

    Discussion

    Input methods that restrict the character codes sent to a client if that client does not support Unicode text should call this method to learn whether a given input session supports Unicode text.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns the bundle identifier for the process that the input session is attached to. (required)

    Declaration

    Swift

    func bundleIdentifier() -> String!

    Objective-C

    - (NSString *)bundleIdentifier

    Return Value

    The bundle identifier for the process that the input session is attached to.

    Discussion

    Many input methods need to be able to identify the process that input sessions belong to. This method provides that service.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • Returns the window level for a client window. (required)

    Declaration

    Swift

    func windowLevel() -> CGWindowLevel

    Objective-C

    - (CGWindowLevel)windowLevel

    Return Value

    The window level for a client window.

    Discussion

    Call this to determine the client window level. Internally, the IMKCandidates class uses this method to determine the correct level for candidate display. Therefore, input methods that use IMKCandidates have no reason to call this method. However, many input method developers build their own candidate display system, and this method is provided for their use. In order to display a candidate window at the correct level, use this method to obtain the client window level, increment the returned level, and then apply that level to any candidate windows.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • List modes for mapping a screen location to a text offset.

    Declaration

    Swift

    typealias IMKLocationToOffsetMappingMode = Int

    Objective-C

    enum { kIMKMouseTrackingMode = (1<<0), kIMKNearestBoundaryMode = (1<<1) };typedef NSInteger IMKLocationToOffsetMappingMode;

    Constants

    • kIMKMouseTrackingMode

      kIMKMouseTrackingMode

      Mouse tracking mode. When tracking, a coordinate does not change the offset until the coordinate is completely past a given character.

      Available in OS X v10.5 and later.

    • kIMKNearestBoundaryMode

      kIMKNearestBoundaryMode

      Nearest boundary mode. When trying to place an insertion point, a coordinate is mapped to the nearest character boundary.

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

  • The text orientation name key.

    Declaration

    Swift

    let IMKTextOrientationName: String

    Objective-C

    extern const *NSString IMKTextOrientationName;

    Constants

    • IMKTextOrientationName

      IMKTextOrientationName

      The key used to find the client text orientation value, which is part of the dictionary returned by the method attributesForCharacterIndex:lineHeightRectangle:. The associated value is an NSNumber object that represents a BOOL value. A value of 1 means the client text uses a horizontal layout. A value of 0 means that the client text uses a vertical layout.

      Available in OS X v10.5 and later.