diff options
author | Tor Arne Vestbø <tor.arne.vestbo@qt.io> | 2021-08-19 11:27:43 +0200 |
---|---|---|
committer | Tor Arne Vestbø <tor.arne.vestbo@qt.io> | 2021-08-19 19:10:59 +0200 |
commit | bb7fe09963decf6b2fef534c463e1d4907011c2e (patch) | |
tree | e6ba1f2b13a0704daa5fe4bd58e55a43fe9d22a6 /src/plugins/platforms/cocoa | |
parent | dcb4b5e7d2b916e1b6c2fbc13464955c7393299b (diff) |
macOS: Expand QNSView complex text documentation
Pick-to: 6.2
Change-Id: Iceb146d7aafb869a80cebe50e27c3bc98e67ebe1
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Diffstat (limited to 'src/plugins/platforms/cocoa')
-rw-r--r-- | src/plugins/platforms/cocoa/qnsview_complextext.mm | 59 |
1 files changed, 58 insertions, 1 deletions
diff --git a/src/plugins/platforms/cocoa/qnsview_complextext.mm b/src/plugins/platforms/cocoa/qnsview_complextext.mm index 35455a2812..a60f42bca8 100644 --- a/src/plugins/platforms/cocoa/qnsview_complextext.mm +++ b/src/plugins/platforms/cocoa/qnsview_complextext.mm @@ -43,13 +43,35 @@ // ------------- Text insertion ------------- +/* + Inserts the given text, potentially replacing existing text. + + The text input management system calls this as a result of: + + - A normal key press, via [NSView interpretKeyEvents:] or + [NSInputContext handleEvent:] + + - An input method finishing (confirming) composition + + - Pressing a key in the Keyboard Viewer panel + + - Confirming an inline input area (accent popup e.g.) + + \a replacementRange refers to the existing text to replace. + Under normal circumstances this is {NSNotFound, 0}, and the + implementation should replace either the existing marked text, + the current selection, or just insert the text at the current + cursor location. +*/ - (void)insertText:(id)text replacementRange:(NSRange)replacementRange { qCDebug(lcQpaKeys).nospace() << "Inserting \"" << text << "\"" << ", replacing range " << replacementRange; if (m_sendKeyEvent && m_composingText.isEmpty() && [text isEqualToString:m_inputSource]) { - // don't send input method events for simple text input (let handleKeyEvent send key events instead) + // We do not send input method events for simple text input, + // and instead let handleKeyEvent send the key event. + qCDebug(lcQpaKeys) << "Not sending simple text as input method event"; return; } @@ -78,6 +100,26 @@ // ------------- Text composition ------------- +/* + Updates the composed text, potentially replacing existing text. + + The NSTextInputClient protocol refers to composed text as "marked", + since it is "marked differently from the selection, using temporary + attributes that affect only display, not layout or storage."" + + The concept maps to the preeditString of our QInputMethodEvent. + + \a selectedRange refers to the part of the marked text that + is considered selected, for example when composing text with + multiple clause segments (Hiragana - Kana e.g.). + + \a replacementRange refers to the existing text to replace. + Under normal circumstances this is {NSNotFound, 0}, and the + implementation should replace either the existing marked text, + the current selection, or just insert the text at the current + cursor location. But when initiating composition of existing + committed text (Hiragana - Kana e.g.), the range will be valid. +*/ - (void)setMarkedText:(id)text selectedRange:(NSRange)selectedRange replacementRange:(NSRange)replacementRange { qCDebug(lcQpaKeys).nospace() << "Marking \"" << text << "\"" @@ -171,6 +213,14 @@ return range; } +/* + Confirms the marked (composed) text. + + The marked text is accepted as if it had been inserted normally, + and the preedit string is cleared. + + If there is no marked text this method has no effect. +*/ - (void)unmarkText { // FIXME: Match cancelComposingText in early exit and focus object handling @@ -191,6 +241,13 @@ m_composingFocusObject = nullptr; } +/* + Cancels composition. + + The marked text is discarded, and the preedit string is cleared. + + If there is no marked text this method has no effect. +*/ - (void)cancelComposingText { if (m_composingText.isEmpty()) |