[PR #3659] Enable Word Navigation in UiaTextRange #25463

Open
opened 2026-01-31 09:09:41 +00:00 by claunia · 0 comments
Owner

Original Pull Request: https://github.com/microsoft/terminal/pull/3659

State: closed
Merged: Yes


Summary of the Pull Request

Enables support for word navigation when using an automation client (i.e.: Narrator, etc...). Specifically, adds this functionality to the UiaTextRange class. The only delimiter used is whitespace because that's how words are separated in English.

PR Checklist

Detailed Description of the Pull Request / Additional comments

General "Word Movement" Expectations

the resulting text range should include any word break characters that are present at the end of the word, but before the start of the next word. (Source)

  • If you already are on a word, getting the "next word" means you skip the word you are on, and highlight the upcoming word appropriately. (similar idea when moving backwards)

Reusing our old code

Word Expansion

Since word selection is supposed to detect word delimiters already, I figured I'd reuse that code. I moved it from TerminalCore to the TextBuffer.

Then I built on top of it by adding an optional additional parameter that decides if you want to include...

  • the delimiter run when moving forward
  • the character run when moving backwards

It defaults to false so that we don't have to care when using it in selection. But we change it to true when using it in our UiaTextRange

UiaTextRange

The code is based on character movement. This allows us to actually work with boundary conditions.

The main thing to remember here is that each text range is recorded as a MoveState. The text range is most easily defined when you think about the start Endpoint and the end Endpoint. An Endpoint is just a linear 1-dimensional indexing of the text buffer. Examples:

  • Endpoint 0 --> (0,0)

  • Endpoint 79 --> (79,0) (when the buffer width is 80)

  • Endpoint 80 -->(0,1) (when the buffer width is 80)

  • When moving forward, the strategy is to focus on moving the end Endpoint. That way, we properly get the indexing for the "next" word (this also fixes a wrapping issue). Then, we update the start Endpoint. (This is reversed for moving backwards).

  • When moving a specific Endpoint, we just have a few extra if statements to properly adjust for moving start vs end.

Hooking it up

All we really had to do is add an enum. This part was super easy :)

I originally wanted the delimiters to be able to be defined. I'm not so sure about that anymore. Either way, I hardcoded our delimiter into a variable so if we ever want to expand on it or make that customizable, we just modify that variable.

Validation Steps Performed

I'll be adding more tests for the kind of things that I was doing. If you really want to test it, I recommend you use Accessibility Insights. Click on the Terminal Control. On the bottom right, click on "Text Pattern Explore...". Then just mess around with any options that say "word" on it.

Concerns/Discussion Points

  1. How does this model expand to non-english languages? How is word navigation expected to work on CJK characters? As of now, we keep going until we hit a boundary or whitespace. Is that functionally correct?
  2. A lot of this code is repeated, unfortunately. It's repeated just enough where I want to do a refactor. HOWEVER, the same issues exist in the other code in this doc (I particularly noticed it in MoveByCharacter(). I think it might be better to do all the refactoring in one big sweep, but I'm open to discussion on this.
**Original Pull Request:** https://github.com/microsoft/terminal/pull/3659 **State:** closed **Merged:** Yes --- ## Summary of the Pull Request Enables support for word navigation when using an automation client (i.e.: Narrator, etc...). Specifically, adds this functionality to the UiaTextRange class. The only delimiter used is whitespace because that's how words are separated in English. <!-- Please review the items on the PR checklist before submitting--> ## PR Checklist * [x] Closes #3161 * [x] CLA signed. * [x] Tests added/passed * [x] General Word Navigation * [x] Empty Buffer Navigation * [x] Requires documentation to be updated (I think not!) ## Detailed Description of the Pull Request / Additional comments ### General "Word Movement" Expectations _the resulting text range should include any word break characters that are present at the end of the word, but before the start of the next word._ ([Source](https://docs.microsoft.com/en-us/windows/win32/winauto/uiauto-uiautomationtextunits)) - If you already are on a word, getting the "next word" means you skip the word you are on, and highlight the upcoming word appropriately. (similar idea when moving backwards) ### Reusing our old code #### Word Expansion Since word selection is supposed to detect word delimiters already, I figured I'd reuse that code. I moved it from TerminalCore to the TextBuffer. Then I built on top of it by adding an optional additional parameter that decides if you want to include... - the delimiter run when moving forward - the character run when moving backwards It defaults to false so that we don't have to care when using it in selection. But we change it to true when using it in our UiaTextRange #### UiaTextRange The code is based on character movement. This allows us to actually work with boundary conditions. The main thing to remember here is that each text range is recorded as a MoveState. The text range is most easily defined when you think about the `start` Endpoint and the `end` Endpoint. An `Endpoint` is just a linear 1-dimensional indexing of the text buffer. Examples: - Endpoint 0 --> (0,0) - Endpoint 79 --> (79,0) (when the buffer width is 80) - Endpoint 80 -->(0,1) (when the buffer width is 80) - When moving forward, the strategy is to focus on moving the `end` Endpoint. That way, we properly get the indexing for the "next" word (this also fixes a wrapping issue). Then, we update the `start` Endpoint. (This is reversed for moving backwards). - When moving a specific Endpoint, we just have a few extra if statements to properly adjust for moving `start` vs `end`. ### Hooking it up All we really had to do is add an enum. This part was super easy :) I originally wanted the delimiters to be able to be defined. I'm not so sure about that anymore. Either way, I hardcoded our delimiter into a variable so if we ever want to expand on it or make that customizable, we just modify that variable. ## Validation Steps Performed I'll be adding more tests for the kind of things that I was doing. If you really want to test it, I recommend you use [Accessibility Insights](https://accessibilityinsights.io/). Click on the Terminal Control. On the bottom right, click on "Text Pattern Explore...". Then just mess around with any options that say "word" on it. ## Concerns/Discussion Points 1. How does this model expand to non-english languages? How is word navigation expected to work on CJK characters? As of now, we keep going until we hit a boundary or whitespace. Is that functionally correct? 2. A lot of this code is repeated, unfortunately. It's repeated _just enough_ where I want to do a refactor. HOWEVER, the same issues exist in the other code in this doc (I particularly noticed it in `MoveByCharacter()`. I think it might be better to do all the refactoring in one big sweep, but I'm open to discussion on this.
claunia added the pull-request label 2026-01-31 09:09:41 +00:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/terminal#25463