Skip to content

UIA text formatting: support paragraph indenting attributes#12908

Merged
michaelDCurran merged 3 commits into
masterfrom
i12899
Oct 5, 2021
Merged

UIA text formatting: support paragraph indenting attributes#12908
michaelDCurran merged 3 commits into
masterfrom
i12899

Conversation

@michaelDCurran

@michaelDCurran michaelDCurran commented Oct 5, 2021

Copy link
Copy Markdown
Member

Link to issue number:

Fixes #12899

Summary of the issue:

When NVDA accessed Microsoft Word documents with the Word object model, it was able to report paragraph indenting.
If the user configures NvDA to access MS Word via UIA, ro it is used by default in MS Word build 13901 or higher, paragraph indenting is no longer reported.

Description of how this pull request fixes the issue:

Report paragraph indenting in UIA text controls (including MS Word documents) by fetching and processing the appropriate UIA text attribute values.
These include:
indentationFirstLine, indentationLeading and indentationTrailing.
These values are all given by the UIA provider in points (1/72 of an inch) thus NvDA converts these to either inches or centermetres first.
this pr also adds a new useImperialMeasurements function to languageHandler which returns true if imperial measuremts (inches) should be used according to the user's current Regional preferences, otherwise metric (centermetres).

Testing strategy:

Ensured NVDA was using UIA to access MS Word.
Created a new Word document. Typed a line of text. Opened Paragraph properties from the context menu and set values for left indent, right indent and first line indent. Back in the Word document, pressed NVDA+f to report the formatting including paragraph indentation.
Ensured that the values were in inches if The measurement soption in Regional settings was set to U.S. or Centermetres if the setting was Metric.

Known issues with pull request:

None known.

Change log entries:

Bug fixes

  • When accessing MS Word with UIA, paragraph indenting is now reported.

Code Review Checklist:

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

Also add a useImperialMeasurements function to languageHandler.
@codeofdusk

Copy link
Copy Markdown
Contributor

useImperialMeasurements checks the current NVDA language, but what we really want to do is use the user's current custom locale settings.

Absolutely. Windows allows users to set their measurement system independent of region (for instance, I'm in the US and use metric) and this should be respected.

From this page:

The system of measurement can be obtain from GetLocaleInfoEx API with LCTYPE flag set to LOCALE_IMEASURE. The returned value is 0 if the metric system (Système International d'unités, or S.I.) is used, and 1 if the U.S. system is used. The maximum number of characters allowed for this string is two.

Comment thread source/languageHandler.py Outdated
localeName = normalizeLocaleForWin32(localeName)
bufLength = 2
buf = ctypes.create_unicode_buffer(bufLength)
if not winKernel.kernel32.GetLocaleInfoEx(localeName, LOCALE.IMEASURE, buf, bufLength):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, looks like you're already doing this.

…time setting by providing NULL (LOCALE_USER_DEFAULT) to GetLocaleInfoEx. No longer support an optional localeName argument (over enginerring).
@michaelDCurran

Copy link
Copy Markdown
Member Author

This pr now honors the user's current regional preferences.

@michaelDCurran michaelDCurran marked this pull request as ready for review October 5, 2021 03:18
@michaelDCurran michaelDCurran requested a review from a team as a code owner October 5, 2021 03:18
@michaelDCurran michaelDCurran added this to the 2021.3 milestone Oct 5, 2021
@AppVeyorBot

Copy link
Copy Markdown

See test results for failed build of commit 2543d7cb21

@michaelDCurran michaelDCurran merged commit 2bf1f71 into master Oct 5, 2021
@michaelDCurran michaelDCurran deleted the i12899 branch October 5, 2021 06:33
@CyrilleB79

Copy link
Copy Markdown
Contributor

This pr now honors the user's current regional preferences.

In the object model code version, paragraph indent used the Office option to determine which unit was used to report the indent; cf. the method WordDocument.getLocalizedMeasurementTextForPointSize in NVDAObjects\window\winword.py. Various units are available and supported, among which centimeter, millimeter, inch to cite more common ones.

Now with this PR, the user's regional preference (of the system) is used. This may lead to strange situations where:

  • Tab or indent script (ctrl+M, ctrl+T, etc.) report their result using Office options, e.g. in millimeter
  • NVDA+F reports paragraph indent using the system regional options, e.g. in centimeter.

Using object model may have the advantage that the reported measurements are expressed in the same unit of what is shown visually on the UI (in case of collaboration with a sighted person).
What about using object model if available and system regional settings if not?

seanbudd pushed a commit that referenced this pull request Oct 18, 2021
Fixes #12899
Fix-up of #12908
Relates to #12770

Summary of the issue:
Historically, the indent in NVDA is reported via object model and its terminology is similar to what is found in Word's paragraph formatting dialog.
In #12908, reporting indant via UIA has been introduced. A mapping between UIA text attributes relative to indent and the type of indent that is reported was used. This mapping was doing the following assumption:

UIA first line indent corresponds to Word's first line indent
UIA leading indent corresponds to Word's left indent
UIA trailing indent corresponds to Word's right indent
This assumption is not always correct for the first two points. And you can seen that object model access. And UIA access give not the same results in the following examples:
left indent = 2.5cm and first line indent = 2.5cm
left indent = 2.5cm and first line negative indent = 2.5cm
Moreover, first line negative was reported in the object model code, whereas it does not appear at all in the UIA code, what evidences missing code.

Description of how this pull request fixes the issue:
Correct matching between Word's and UIA terminology has been implemented. To clarify:

Word's terminology
left indent = distance from the left margin to the left-most start of a line (it may be the first line or the following lines)
right indent = distance from the right margin to the end of the paragraph's lines (except the last that may be incomplete)
first line indent = distance between the start of the first line and the start of the other lines when the first line starts after the other ones
hanging indent = distance between the start of the first line and the start of the other lines when the first line starts before the other ones
UIA terminology
first line indent = distance from the left margin to the start of the first line of the paragraph
leading indent: distance from the left margin to the start of the following lines (2nd, 3rd, etc.)
trailing indent = distance from the right margin to the end of the paragraph's lines (except the last that may be incomplete)
Addition: do not report zero indent
In addition, I have removed reporting any type of indent when its value is zero. Indeed, it was not reported in this case with the object model access, and I felt it was worth continuing in this way. Moreover, in #12908, nothing has been indicated that zero values should now be reported, so I assumed that it was unintentional.

Possible alternative design
I have aligned what is reported to what preexisted with the object model access, since in #12908 no information was indicating that it should have been modified.

But another option may have been to report indentation as provided by UIA and to align the object model access code to what is provided by UIA.

I have also not chosen this alternative design because I think that today, only Word provides indentation information via UIA. Thus, this makes sense to follow with Words conventions. If another provider should provide indent information one day, maybe the way indentation is reported should be reconsidered and uniformed.

Should you however prefer this alternative design, just let me know.

Testing strategy:
Tested various paragraph formatting with non-zero left indent and the 3 following cases:

no first line indent
first line indent > 0
negative indent > 0
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.

Enabling UIA Support in Word Causes Paragraph Indentation Not to be Reported

5 participants