Add braille text wrap modes with continuation marks

[LeonarddeR]

Link to issue number:

Part of #17010. Split out from #19916 at reviewer request — this is the second of three PRs. The pyphen abstraction layer was shipped in #20145; the syllable-aware wrap mode follows in a separate PR.

Summary of the issue:

The braille word-wrap setting is a single boolean that gives users no control over how words are broken at the display edge. When a word is cut mid-way there is also no visual indication that the word continues on the next row.

Description of user facing changes:

The boolean "word wrap" checkbox in the braille settings has been replaced with a Text wrap combo box with three choices:

• Off — Wrap at the raw edge of the display, cutting words in the middle if necessary. No visual indication that a word was cut.
• Show mark when words are cut — Wrap at the raw edge, but whenever a word is cut mid-way, replace the last cell of the row with a continuation mark (braille dots 7-8) so the reader knows the word continues on the next row.
• At word boundaries — Prefer breaking at spaces. If no space fits on the row, fall back to cutting the word and showing the continuation mark.

Existing config profiles with the old setting are automatically upgraded.

Description of developer facing changes:

• BrailleTextWrapFlag feature flag enum added to config.featureFlagEnums with members DEFAULT, NONE, MARK_WORD_CUTS, AT_WORD_BOUNDARIES.
• Config schema bumped v22 → v23; old wordWrap boolean is deprecated and bridged bidirectionally to textWrap via _linkDeprecatedValues, so add-ons reading or writing the old key keep working (with a deprecation warning).
• CONTINUATION_SHAPE = 0xC0 (dots 7-8) constant added to braille.
• _WindowRowPositions frozen dataclass added to braille to hold the start/end buffer positions and continuation-mark flag for each row of the braille window, replacing the previous anonymous tuple.

Description of development approach:

The continuation mark is unified: it consistently means "a word was cut here" regardless of mode, so readers get a predictable signal.

BrailleBuffer._calculateWindowRowBufferOffsets is extended to implement all three modes. Each entry in _windowRowBufferOffsets is a _WindowRowPositions instance whose showContinuationMark field records whether that row needs a continuation mark. BrailleBuffer._get_windowBrailleCells reads that flag to insert the mark. BrailleBuffer._set_windowEndPos short-circuits space-seeking for NONE and MARK_WORD_CUTS modes (backwards scroll alignment).

Testing strategy:

Unit tests cover:

• All three wrap modes and their edge cases in _calculateWindowRowBufferOffsets (no cells, fits exactly, word cut, word too long for display, no space on line).
• Continuation-mark rendering in _get_windowBrailleCells.
• Profile upgrade from wordWrap = True/False → correct textWrap flag values.

Manual testing: loaded a pre-upgrade profile with wordWrap = True/False and confirmed the upgrade writes the expected textWrap value and the braille settings panel shows the matching label.

Known issues with pull request:

None.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Replaces the boolean wordWrap braille setting with a three-valued textWrap feature flag (Off / Show mark when words are cut / At word boundaries), and introduces a continuation marker (dots 7-8) shown in the last cell of a row when a word is cut across rows.

Changes:

• New BrailleTextWrapFlag feature flag enum, settings dialog combo box, and updated _calculateWindowRowBufferOffsets / _get_windowBrailleCells logic to emit a continuation shape on cut rows.
• Config schema bumped to version 23 with a profile upgrade step migrating wordWrap → textWrap, and a deprecated-key link from wordWrap to textWrap.
• Updated user docs/changelog and added/updated unit tests.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
source/config/featureFlagEnums.py	Adds BrailleTextWrapFlag enum with display strings.
source/config/configSpec.py	Bumps schema to 23, marks wordWrap deprecated, adds textWrap.
source/config/profileUpgradeSteps.py	Adds upgrade step 22→23 migrating wordWrap to textWrap.
source/config/init.py	Re-enables _linkDeprecatedValues and bridges wordWrap ⇄ textWrap.
source/braille.py	Adds CONTINUATION_SHAPE, mid-word cut handling, continuation flag in row offsets.
source/gui/settingsDialogs.py	Replaces word-wrap checkbox with a FeatureFlagCombo.
tests/unit/test_braille/test_calculateWindowRowBufferOffsets.py	Updates and extends tests for new wrap flag behavior.
tests/unit/test_braille/test_windowBrailleCells.py	New tests for continuation cell injection in window cells.
user_docs/en/userGuide.md	Documents the new Text wrap combo and modes.
user_docs/en/changes.md	Notes the new feature and deprecation.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

[Qchristensen]

Reads well