docs(windows): describe windows compliant app implementation with sequence diagram by rc-swag · Pull Request #2326 · keymanapp/help.keyman.com

rc-swag · 2025-11-10T05:09:47Z

Add a description of the Windows Text Services Framework and sequence diagram for compliant apps.

Fixes:#2061

keymanapp-test-bot · 2025-11-10T05:10:02Z

User Test Results

Test specification and instructions

ERROR: user tests have not yet been defined

knowledge-base/kb0118.md

ermshiperete · 2026-03-03T11:28:10Z

knowledge-base/kb0118.md

+Keyman determines whether an application is compliant by inspecting the status returned by `ITfContext::GetStatus()`.
+
+- **Compliant applications** provide a stable, non-transitory context and correctly implement the TSF APIs needed to retrieve context and modify text.
+- **Non-compliant applications** may expose only a transitory context or fail to return reliable selection or text data.


Can TSF API be used for non-compliant apps?

Yes, to attempt to get context. It it is determined it is non compliant when attempting to get the context then it does not use the API to set selection.

knowledge-base/kb0118.md

ermshiperete · 2026-03-03T11:36:20Z

knowledge-base/kb0118.md

+**`GetText()`** — Retrieves text from a specified range around the caret, giving Keyman the context needed to process complex keyboard rules.
+
+**`SetText()`** — Replaces text in a specific range within the context.


I don't see GetText and SetText on the linked MS docs for ITfContext.

Yes that is correct I was not sure how much detail to go into. The API linked you make GetSelection call which will return a pointer to TF_SECTION. TF_SECTION in turn contains a ITfRange it is actually ITfRange that has methonds GetText and SetText. Even then Keyman for Windows provides wrapper functions DeleteLeftOfSelection and InsertTextAtSelection that use methods of ITfRange and the ITfContext to achieve the goals. I will have a go at updating this.

ermshiperete · 2026-03-03T11:40:24Z

knowledge-base/assets/kb0118/windows-compliant-app-sequence.mmd

+
+    Note right of Keyman: Keyman applies keyboard rules and computes output
+
+    Keyman->>TSF: ITfContext.SetText()


Does SetText allow to specify whether to insert the text or replace the selection, or do we have to update the selection first?

mcdurdin · 2026-03-04T12:58:01Z

knowledge-base/kb0118.md

+- **Backspace key events** are used to delete previously typed characters
+- **Synthetic key events** may be used to insert characters
+
+These simulated events are asynchronous and are processed by the application in sequence. As a result, text deletion and insertion may not always behave exactly as intended, particularly when dealing with composed characters or surrogate pairs.


This may need a little more elaboration. The main reason text deletion may not behave as expected is because there is no fixed definition of how many codepoints should be deleted in a Backspace key event -- one code point, a grapheme cluster, or something else. As a result, applications may have varied behavior here.

Very old applications may not handle surrogate pairs correctly and split them apart, but this is now rare.

I have decided to add link to the wiki to go into the weeds on the deletions you mention here.

mcdurdin · 2026-03-04T12:59:10Z

knowledge-base/kb0118.md

+- Using shortcut keys or menu commands to edit text
+- Switching to another application or document
+
+When such an action occurs, Keyman discards its internal context and assumes an empty context. If this happens in the middle of typing a multi-character sequence, the sequence may not be recognized correctly and may need to be retyped.


In Keyman, there is no real concept of a multi-character sequence. (Did you mean multi-keystroke sequence?) Each key event is isolated. We should be careful not to imply a state mechanism that does not exist.

I did mean character, however I realise character is an overloaded term with when thinking about unicode points vs charcater etc.
It was refernce back to the intro of this KB https://github.com/keymanapp/help.keyman.com/pull/2326/changes#diff-0bc53b3e68388acdad32bd067b6f9940b76087f855f1ebbbe14b4c204ba5ac2fL43

I have reworked this whole section because it was repeating what had already been said in the preamble. I have now just tried to emphasise the Windows specific work. I have also added link back to the start fo the document rather than repeating it.

Each key event is isolated. We should be careful not to imply a state mechanism that does not exist.

Huh? Each key event is not isolatated that is what the KB is about. It is processed against the context (whether tracked internal or read from context aware) this is state. When that state is lost the keyboard rule cannot work. We haven't mentioned deadkeys or markers in this KB but that information in our internal context is state and a keystroke is dependent on that state.

Back to the multi-character vs multi-keystroke sequence - both have problems with causing confusion. Because the Keyboard rules are actually based on the "charcaters" in the context NOT the keystrokes that preceeded the current keystroke, they have already been turned into a character/s or a deadkey. That's is why compliant apps can work because the read the context and get the characters.

Yeah, you are right -- there is state, but not in the form of a key sequence. The problem is people think of Keyman keyboards as describing key sequences, but they don't. They describe key + context transforms. Even deadkeys are implemented as invisible marker characters with a position in the context text stream.

In the ideal case -- apart from deadkeys -- this can be described as 'stateless': we don't carry information from keystroke to keystroke. You can position the text caret anywhere in a document and the keystroke will work with the context that it finds already there.

Historically, in a much earlier version of Keyman for Windows, we even inserted deadkeys as invisible 'embeds' into the text stream. This worked well in Word, but the vast majority of even TSF-aware apps didn't support embedding data objects, so we stripped that back out again. (And it turns out that that was better because deadkeys work best as ephemeral state-carrying markers!) But in that scenario, Keyman carried no state at all between keystrokes but queried the document every keystroke to determine the full context.

I'm not sure if I am articulating what I mean clearly though!

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

correct the sequence diagram.

ermshiperete · 2026-03-06T11:25:30Z

knowledge-base/kb0118.md

- **Non-compliant applications** may expose only a transitory context or fail to return reliable selection or text data.
-
-If the `TF_SS_TRANSITORY` flag is present or context cannot not be read as expected, Keyman treats the application as non-compliant and falls back to legacy behavior, maintaining its own internal context buffer and simulating text operations where possible.
+Note: For both compliant and non-compliant apps. When there is a highlighted section of text if backspace is the determined action from processing the keystroke on Windows Keyman will emit the key (backspace), allowing the application to handle clearing selected text in the correct manner. 


This sentence is hard to read and understand.

Ok. Reading it again, it is hard to understand.
The point I was trying to make in the in the higlighted text selection case when backspace is pressed, Keyman doesn't use SetSelection instead it emits the keystroke and leaves it up to the application to handle. I think this might be unique to Windows. However, I'm not sure it adds anything to this knowedge base which is more concerned with on complaint vs non-complaint behaviour. It is probably best not to mention it at all.

This is an interesting point which should be carried into our compatibility matrix discussion!

docs(windows): intial TSF commit todo seq diag

b727871

rc-swag self-assigned this Nov 10, 2025

github-actions bot added the docs label Nov 10, 2025

keyman-status added this to Keyman Nov 10, 2025

rc-swag added this to the A19S16 milestone Nov 10, 2025

github-project-automation bot moved this to Todo in Keyman Nov 10, 2025

keymanapp-test-bot bot added the user-test-missing label Nov 10, 2025

keyman-server modified the milestones: A19S16, A19S17 Nov 22, 2025

rc-swag changed the title ~~docs(windows): intial TSF commit todo seq diag~~ docs(windows): initial TSF commit todo seq diag Nov 24, 2025

keyman-server modified the milestones: A19S17, A19S18 Dec 6, 2025

keyman-server modified the milestones: A19S18, A19S19 Dec 21, 2025

docs(windows): windows compliants no sequence diagram

6993630

keyman-server modified the milestones: A19S19, A19S20 Jan 3, 2026

mcdurdin modified the milestones: A19S20, A19S21 Jan 25, 2026

docs(windows): add windows compliant sequence diagram

b2e1d9e

rc-swag requested review from ermshiperete and mcdurdin March 3, 2026 07:29

rc-swag marked this pull request as ready for review March 3, 2026 07:30

rc-swag changed the title ~~docs(windows): initial TSF commit todo seq diag~~ docs(windows): describes windows compliant app implmentation with sequence diagram Mar 3, 2026

ermshiperete changed the title ~~docs(windows): describes windows compliant app implmentation with sequence diagram~~ docs(windows): describe windows compliant app implementation with sequence diagram Mar 3, 2026

ermshiperete requested changes Mar 3, 2026

View reviewed changes

mcdurdin reviewed Mar 4, 2026

View reviewed changes

rc-swag and others added 2 commits March 5, 2026 22:36

docs(windows): review comments

842d4bc

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

docs(windows): remove dulpicate descriptions corrrect

1f55e0a

correct the sequence diagram.

ermshiperete reviewed Mar 6, 2026

View reviewed changes

docs(windows): remove un needed review comments

d961009

ermshiperete approved these changes Mar 9, 2026

View reviewed changes

mcdurdin approved these changes Mar 10, 2026

View reviewed changes

		`GetText()` — Retrieves text from a specified range around the caret, giving Keyman the context needed to process complex keyboard rules.

		`SetText()` — Replaces text in a specific range within the context.


		Note right of Keyman: Keyman applies keyboard rules and computes output

		Keyman->>TSF: ITfContext.SetText()

Uh oh!

Conversation

rc-swag commented Nov 10, 2025 • edited by mcdurdin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

keymanapp-test-bot bot commented Nov 10, 2025

User Test Results

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rc-swag Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rc-swag Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rc-swag commented Nov 10, 2025 •

edited by mcdurdin

Loading

rc-swag Mar 5, 2026 •

edited

Loading

rc-swag Mar 5, 2026 •

edited

Loading