Skip to content
Permalink
Browse files

Add a note on text input

  • Loading branch information
qvacua committed Jul 3, 2016
1 parent 734b31c commit 4b4668ae2120e4daeabe253bb50e6916d58af835
Showing with 71 additions and 2 deletions.
  1. +5 −2 SwiftNeoVim/NeoVimViewEvents.swift
  2. +66 −0 docs/notes-on-cocoa-text-input.md
@@ -34,7 +34,7 @@ extension NeoVimView: NSTextInputClient {
}

public func insertText(aString: AnyObject, replacementRange: NSRange) {
// NSLog("\(#function): \(replacementRange): '\(aString)'")
NSLog("\(#function): \(replacementRange): '\(aString)'")

switch aString {
case let string as String:
@@ -56,7 +56,7 @@ extension NeoVimView: NSTextInputClient {
}

public override func doCommandBySelector(aSelector: Selector) {
// NSLog("\(#function): "\(aSelector)")
NSLog("\(#function): \(aSelector)");

// FIXME: handle when ㅎ -> delete
@@ -112,6 +112,7 @@ extension NeoVimView: NSTextInputClient {
public func selectedRange() -> NSRange {
// When the app starts and the Hangul input method is selected, this method gets called very early...
guard self.grid.hasData else {
NSLog("\(#function): not found")
return NSRange(location: NSNotFound, length: 0)
}

@@ -134,13 +135,15 @@ extension NeoVimView: NSTextInputClient {
}

public func hasMarkedText() -> Bool {
NSLog("\(#function)")
return self.markedText != nil
}

// FIXME: take into account the "return nil"-case
public func attributedSubstringForProposedRange(aRange: NSRange, actualRange: NSRangePointer) -> NSAttributedString? {
NSLog("\(#function): \(aRange), \(actualRange[0])")
if aRange.location == NSNotFound {
NSLog("\(#function): range not found: returning nil")
return nil
}

@@ -0,0 +1,66 @@
# Some Notes on Cocoa's Text Input

To use Cocoa's text input system, e.g. the 2-Set Korean input, your view has to implement the [NSTextInputClient](https://developer.apple.com/reference/appkit/nstextinputclient) protocol. Apple's documentation is very scarce, so we're writing down some of our findings.

## Simple Case

For simple cases like `ü`, which can be entered by `Opt-u` + `u`, it's quite straightforward:

1. Enter `Opt-u`.
1. `hasMarkedText()` is called to check whether we already have marked text.
1. `setMarkedText("¨", selectedRange NSRange(1, 0), replacementRange: NSRange(NSNotFound, 0))` is called. In this case the first argument is an `NSString`, `selectedRange` tells us where to put the cursor relative to the string: in this case after `¨`. The range `replacemenRange` tells us whether the string should replace some of the existing text. In this case no replacement is required.
1. Enter `u`.
1. `hasMarkedText()` is called again.
1. `insertText("ü", replacementRange: NSRange(NSNotFound, 0))` is called to finalize the input. It seems that for the replacement range `(NSNotFound, 0)` we should replace the previously marked text with the final string. So in this case we must first delete `¨` and insert `ü`.

## Korean (Hangul, 한글)

Let's move to a bit more complicated case: Korean. In this case more methods are involved:

* `selectedRange()`: all other additional methods seem to rely on this method. Ideally we should return `NSRange(CursorPosition, 0)` when nothing is selected or `NSRange(SelectionBegin, SelectionLength)` when there's a selection.
* `attributedSubstringForProposedRange(_:actualRange:)`: for entering only Hangul, this method can be ignored.

Let's assume we want to enter `하태원`: (`hasMarkedText()` is called here and there...)

1. `selectedRange()` is called multiple times when changing the input method from US to Korean. This is also the case when starting the app with Korean input selected.
1. Enter `ㅎ`.
1. `setMarkedText("ㅎ", selectedRange: NSRange(1, 0) replacementRange:NSRange(NotFound, 0))` is called.
1. Enter `ㅏ`.
1. `attributedSubstringForProposedRange(_:actualRange:)` and `selectedRange()` are called multiple times: again, for only Hangul, ignorable.
1. `setMarkedText("하", selectedRange: NSRange(1, 0), replacementRange: NSRange(NotFound, 0))` is called: delete `ㅎ` and insert `하`; not yet finalized.
1. Enter `ㅌ`
1. `attributedSubstringForProposedRange(_:actualRange:)` and `selectedRange()` are called multiple times: ignore.
1. `setMarkedText("핱", selectedRange: NSRange(1, 0), replacementRange: NSRange(NotFound, 0))` is called: delete `하` and insert `핱`; not yet finalized.
1. Enter `ㅐ`
1. `attributedSubstringForProposedRange(_:actualRange:)` and `selectedRange()` are called multiple times: ignore.
1. `setMarkedText("하", selectedRange: NSRange(1, 0), replacementRange: NSRange(NotFound, 0))` is called: delete `핱` and insert `하`; not yet finalized.
1. `insertText("하", replacementRange: NSRange(NotFound, 0))` is called to finalize the input of `하`.
1. `attributedSubstringForProposedRange(_:actualRange:)` and `selectedRange()` are called multiple times: ignore.
1. `setMarkedText("태", selectedRange: NSRange(1, 0), replacementRange: NSRange(NotFound, 0))` is called: Since the replacement range is `NotFound`, append the marked text `태` to the freshly finalized `하`.
1. ...

## Hanja (한자)

Let's consider the even more complicated case: Hanja in Korean. In this case the `selectedRange()` and `attributedSubstringForProposedRange(_:actualRange:)` play a vital role and also

* `firstRectForCharacterRange(_:actualRange)`: this method is used to determine where to show the Hanja popup. The character range is determined by `selectedRange()`.

Let's assume we want to enter `河`: (again `hasMarkedText()` is called here and there...)

1. Enter `ㅎ`.
1. `setMarkedText("ㅎ", selectedRange: NSRange(1, 0) replacementRange:NSRange(NotFound, 0))` is called.
1. Enter `ㅏ`.
1. `attributedSubstringForProposedRange(_:actualRange:)`, `selectedRange()` and `hasMarkedText()` are called multiple times: again, for only Hangul, ignorable.
1. `setMarkedText("하", selectedRange: NSRange(1, 0), replacementRange: NSRange(NotFound, 0))` is called: delete `ㅎ` and insert `하`; not yet finalized.
1. Enter `Opt-Return`.
1. `setMarkedText("하", selectedRange: NSRange(1, 0), replacementRange: NSRange(NotFound, 0))` is called again.
1. `selectedRange()` is called: here we should return a range which can be consistently used by `attributedSubstringForProposedRange(_:actualRange)` and `firstRectForCharacterRange(_:actualRange)`.
1. `insertText("하", replacementRange: NSRange(NotFound, 0))` is called even we are not done yet... So our view thinks we finalized the input of `하`.
1. `attributedSubstringForProposedRange(_:actualRange)` is called multiple times to get the Hangul syllable to replace with Hanja. The proposed range can be very different in each call.
1. Only if the range from `selectedRange()` could be somehow consistently used in `attributedSubstringForProposedRange(_:actualRange)`, then the Hanja popup is displayed. Otherwise we get the selector `insertNewlineIgnoringFieldEditor` in `doCommandBySelector()`.
1. `setMarkedText("下" , selectedRange: NSRange(1, 0), replacementRange: NSRange(1, 1))` is called: the replacement range is not `NotFound` which means that we first have to delete the text in the given range, in this case the finalized `하` and then append the marked text.
1. Selecting different Hanja calls the usual `setMarkedText(_:selectedRange:actualRange)` and `Return` finalizes the input of `河`.

## Other Writing System

Not a clue, since I only know Latin alphabet and Korean (+Hanja)...

0 comments on commit 4b4668a

Please sign in to comment.
You can’t perform that action at this time.