siliu1 / tsf1

TSF1.0

Design Document

tsf1's Issues

Why is there a TSFTextStore per input type?

Can't the TSFTextStore change its type? I believe TSF1 supports that, doesn't it?

What happens if a focused editable element changes from input type="text" to type="email"? Do you swap the associated text store?

I don't think you discuss how conflicts are resolved beyond updating the view to Windows Text Services

Can you also say how the text actually gets committed to the DOM in the case of conflict, e.g. if selection moves in the DOM but TSF is requesting you replace "abc" (3 characters which formerly preceded the caret) with "xyz"?

should capitalize "at" in the new sentence sentence

search for "Supporting TSF1.0 framework doesn’t require architectural changes to Chromium. at", you'll see that "at" needs to be capitalized.

The architecture "overview" seems overly detailed

Consider making the "arcitecture overview" just "architecture" and add an overview between the summary and the architecture section.

I think the overview should contain some principles of your design and the broad brush strokes of how communication happens. I would explain conceptually how TSF works (in lay terms - don't use interface or method names), then state any contraints on the design and invariants that you want to keep so that the design follows from what's presented in this section.

<sample>
Windows Text Services facilitates communication between input methods (handwriting recognition, speech recognition, shape-writing, etc), and editing applications that want text input (code editors, spreadsheets, or rich text editing applications like Microsoft Word). Each editing application has a model for representing the content it edits, and to avoid the need for each input method to code against N different editor document models, Windows Text Services defines an intermediate language to facilitate communication between the editing applications and the input methods: a shared plain-text buffer of content.

The shared buffer is updated cooperatively with the help of Windows Text Services. When an input method delivers input to an editing application, it does so by requesting that Windows Text Services update the shared buffer, and Windows Text Services can in response notify the editing app how the buffer is being modified so that the editing application can update its document model.
...
</sample>

I would expand the above to talk about selection state, layout state, highlighting and modes for input. Say something about why each feature exists so its clear what the code we've written is trying to accomplish... example: "highlighting of text in the buffer can also be requested by an input method so it can, for example, indicate what text is being composed in response to phonetic input. When the input method requests a highlight over the range, Text Services does X and the editing app is responsible for Y."

After that if you can include some constraints, principles, invariants and key assumptions of the design and I think that will make the transition from summary to architecture will go smoothly...

<examples>
Constraint: Windows Text Services has evolved with various Windows releases. Our goal is to provide support back to Windows 7. TSF1 is available back to (insert version) and will be used to access the text input services of the Windows platform on Windows 7 and above.

Constraint and applicable Principle: TSF1 requires a synchronous response to queries about the state of the shared buffer, yet the input thread of the browser process must remain responsive. To acheive both requirements, no blocking cross-process calls or waiting for script to yield so the state of the DOM can be read will be allowed; instead all queries must be fulfilled from cached state maintained in the browser process that mirrors (with some imperceptible delay) the contents of the DOM in the renderer process.

Principle: Since both input methods and editing applications are trying to update the same editable content, conflicts can occur. To resolve conflicts, the order of operations as seen by the DOM will be considered authoritative.

Key assumption: The view of the editable content provided to Windows Text Services should be aligned with what the user sees on the screen. Transient state of the DOM that the user cannot see is irrelevant to the editing process and the view provided of the editable content to Windows Text Services.

Key assumption: We are free to reuse TSF objects that describe the content of an editable region of an editing app as there is no known data cached using the identity of these objects, i.e. all that is necessary to facilitate a great editing experience can be computed from the contents of the DOM and populated into an appropriate TSF object as focus shifts from one editable element to another.

...
</examples>

In tradeoffs with proposed design can you state more clearly if there is an actual tradeoff?

I don't really see any drawbacks being called out in this section. If there are none consider retitling to "Considerations for TSFTextStore Reuse" and state something about why (at least in theory) you would expect a 1-to-1 relation between the TSFTextStore and editable elements, but why its OK to reuse instead because of (insert practical reasons).

Do updates to the edit control result in syncing state with the browser process too frequently?

RE: When the editing context is changed in edit control, a mojo message is sent to the browser process to update the TextInputState struct to stay in sync with the focused edit control.

What's the trigger for the mojo message? Transient state generally isn't interesting. As a principle I'm thinking the view we provide to Windows Text Services should be aligned with the view provided to the user (when we update the screen).

Could you explain counts of key object types relative to each other?

In the browser process how many thread managers, document managers and edit contexts. Is it 1->1->8 (an edit context for each input type)? Does the pattern repeat per HWND or per document with a browsing context or something else?

nit typos

" such as on-screen keybard input suggestions, shape-writing in on-screen keyboard, customized on-screen keyard UI for different types of edit control, that were not previously available in IMM32."
Typo: Keyboard in this sentence

TSF1.0 framework also provides text intelligence features

Can we add some examples of text intelligence features such as shape-writing, handwriting panel etc

consider rewording "Now TSFTextStore is successful registered with Windows Input Service and is ready to receive function calls to modify content in edit control. "

Consider rewording "Now TSFTextStore is successful registered with Windows Input Service and is ready to receive function calls to modify content in edit control. " into "Once TSFTextStore is successfully registered with Windows Input Service it is ready to receive function calls to modify content in edit control. "

Browser process communication

In "graphical explainer to the design", "The communications between Windows Input Service(msctf.dll) and TSFTextStore are all synchronous" : This is in the browser process right? Can we mention that here just for clarification?