Skip to content

Add braille text wrap modes with continuation marks#20146

Draft
LeonarddeR wants to merge 1 commit into
nvaccess:masterfrom
LeonarddeR:braille-textwrap-refactor
Draft

Add braille text wrap modes with continuation marks#20146
LeonarddeR wants to merge 1 commit into
nvaccess:masterfrom
LeonarddeR:braille-textwrap-refactor

Conversation

@LeonarddeR
Copy link
Copy Markdown
Collaborator

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 user profiles with the old wordWrap = True / wordWrap = False setting are automatically upgraded: True becomes "At word boundaries" and False becomes "Off".

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.

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. BrailleBuffer._get_windowBrailleCells inserts the continuation mark into rows flagged in _continuationRows. 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.

@LeonarddeR LeonarddeR mentioned this pull request May 16, 2026
12 tasks
@LeonarddeR LeonarddeR force-pushed the braille-textwrap-refactor branch from f9ebc30 to e142dde Compare May 16, 2026 08:03
Replaces boolean wordWrap config with BrailleTextWrapFlag feature flag
(NONE, MARK_WORD_CUTS, AT_WORD_BOUNDARIES, AT_WORD_OR_SYLLABLE_BOUNDARIES).
Adds profile upgrade step v22->v23, deprecated API bridge, GUI combo box,
continuation mark (dots 7-8) when a word is cut mid-display, and
_continuationRows tracking in BrailleBuffer. Syllable boundary mode
is wired but its backend follows in a separate PR.
@LeonarddeR LeonarddeR force-pushed the braille-textwrap-refactor branch from f040151 to e080142 Compare May 16, 2026 08:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant