Merge beta to master

Summary of the issue:

In order to aid reviewing complex pull requests, having a description of the development approach is helpful.
Often this is implicitly included in "Description of how this pull request fixes the issue", however this is also used as a high level summary of the user facing changes. A separation of concerns is needed.

Description of how this pull request fixes the issue:

Adds this information to the PR template and explanation.

…3805)

Summary of the issue:
NVDAObjects.IAccessible.winword star imports everything from NVDAObjects.window.winword. This may cause issues when removing imports from NVDAObjects.window.winword, it is also better to be explicit.

Description of how this pull request fixes the issue:
NVDAObjects.IAccessible.winword now imports all used modules explicitly.

As per the documentation (https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/symstore-command-line-options) `-:NOREFS` should be used with `/p`. Reference pointer files are not included unless we use the `/p` flag. 

Description of how this pull request fixes the issue:

Removes `-:NOREFS`  and reorders options to be inline with documentation.

Fixes #13573

Summary of the issue:
"pt" when reporting font size measurements is not translatable.
Font size measurements are reported inconsistently, for example in excel and PowerPoint are reported as "11.0" instead of "11 pt".

Description of how this pull request fixes the issue:
Makes the font size measurement "pt" translatable across APIs.

Browsers provide "font-size" attribute directly as "12pt|px|em|%|rem|ex" or "large", "small", etc.
This requires a more strategic approach for catching each font-size case and replacing it with a translated string.
Documentation has been added for this.
https://developer.mozilla.org/en-US/docs/Web/CSS/font-size

…S Outlook (#13811)

Fixes #13810

Summary of the issue:
PR #13805 removed star imports from NVDAObjects.IAccessible.winword. Unfortunately the appModule for MS Outlook relied on some of the stuff star imported there.

Description of user facing changes
MS Outlook can once again be used with Alpha versions of NVDA.

Description of development approach
Inspected all imports from NVDAObjects.IAccessible.winword - - where they imported stuff which is actually defined in NVDAObjects.window.winword the imports were made explicit.

Summary of the issue:
When the requirements file changes, the ensureVenv script forcefully recreates the environment. In many cases, this behavior is slightly harsh.

Description of how this pull request fixes the issue:
Instead of always recreating the environment, ask the user what to do. If "No" is chosen, the requirements file is installed without recreating

Summary of the issue:
When UIA is enabled for Excel, merged cells were not mentioned as such. Instead, only the first coordinates of the merged range were reported.

Description of how this pull request fixes the issue:
There is no way to fetch the last cell in the range from Excel itself. The UIA implementation in Excel also refuses to provide real row and column numbers. Therefore we have to convert the alphabetical column representation to a column number, then correct the column number for column span and convert it back to alphabetical representation.

…preparation for usage by default (#13807)

Summary of the issue:
It was requested in #10964 (comment) that the ternary option be exposed separately to the change in default behaviour to ease revertability.

Description of how this pull request fixes the issue:
Exposes the ternary option as requested and updates the user guide.

…gui/inputGestures.py` after its split from `source/gui/settingsDialogs.py` (#12386)

Fix-up of PR #11402

Summary of the issue:
In PR #11402, part of source/gui/settingsDialogs.py has been extracted to the new source/gui/inputGestures.py for good reasons.
However, in the process, the name of the copyright holders for this portion of the code has not been reported to the header of the new file.

Description of how this pull request fixes the issue:
Copy all the names from the copryright headers in source/gui/settingsDialogs.py.

…(Windows 11 Sun Valley 2) (#10964)

Supersedes #9771 and #10716. Closes #1682. Closes #8653. Closes #9867. Closes #11172. Closes #11554.

Summary of the issue:

Microsoft has significantly improved performance and reliability of UIA console:
* microsoft/terminal#4018 is an almost complete rewrite of the UIA code which makes the console's UIA implementation more closely align with the API specification.
* microsoft/terminal#10886, microsoft/terminal#10925, and microsoft/terminal#11253 form a robust testing methodology for the UIA implementation, including bug fixes in response to newly added tests based on Word's UIA implementation.
* microsoft/terminal#11122 removes the thousands of empty lines at the end of the console buffer, significantly improving performance and stability. Since all console text ranges are now within the text buffer's bounds, it is no longer possible for console to crash due to the manipulation by UIA clients of an out-of-bounds text range.
* Countless other accessibility-related PRs too numerous to list here.

We should enable UIA support on new Windows Console builds by default for performance improvement and controllable password suppression.

Description of how this pull request fixes the issue:

This PR:
* Exposes all three options for the UIA console feature flag in the UI (replaces the UIA check box with a combo box).
* Adds a runtime check to test if `apiLevel >= FORMATTED`, and use UIA in this case when the user preference is auto. This is the case on Windows 11 Sun Valley 2 (SV2) available now in beta and set for release in the second half of 2022.

Fix-up of #10964.

Summary of the issue:

The link to Expose Text Attributes to UI Automation microsoft/terminal#10336 was broken by t2t preproc directives.

Additional clarification on "NVDA API levels" might be appreciated by some users.

Link to issue number:

Fixes #12097
Fixes #12086

Summary of the issue:

Some punctuation marks in Chinese and Arabic are treated as emoji characters by NVDA.

Description of how this pull request fixes the issue:

This pull request adds those symbols into NVDA's symbols dictionary.

…ernal code when running from sources (#13827)

Summary of the issue:
When starting NVDA from sources messages logged from nvda.pyw are shown as external. Example message:

INFO - external:__main__ (17:20:02.477) - MainThread (4316):
Starting NVDA version source-master-b817b03

This is clearly wrong. The problem is caused by the trailing backslash added in bat scripts (%~dp0 is already terminated with one and adding a second backslash causes logHandler.isPathExternalToNVDA to think that the path is external).

Description of user facing changes
Log messages from nvda.pyw are no longer marked as external.

Description of development approach
All usages of %~dp0 are inspected and trailing backslash is no longer added to the paths. To make logHandler.isPathExternalToNVDA more resilient to invalid paths the path is normalized before checking if it is the same as sys.path.

…handle (#13796)

Closes #13039

Summary of the issue:
When launching IntelliJ IDEA you minimise all windows with Windows+M before the IntelliJ window comes into view, then you get many errors and IntelliJ will take a long time to load. In addition NVDA will log many errors.

Description of how this pull request fixes the issue:
It seems like if a Java window never gets shown then Java Access Bridge is unable to get a window handle for it. Also the caching of window handles in NVDA's Java Access Bridge is unable to help as the Java window was never in focus. As the affected window is in the background and as there is nothing more NVDA can do to solve this I have checked for the presence of a window handle in the Java Access Bridge event handling, if no window handle is present then the event is ignored.

Testing strategy:
Manual testing. Tested using the steps in the issue. Also did some other use of Java applications to observe if this fix has negative impacts anywhere else, none found.

Known issues with pull request:
Technically these events could be processed as the Java Access Bridge objects contain all accessible information, so we are throwing away events when may be we could process them. However due to NVDA Window objects insisting on a window handle we cannot proceed with processing due to the NVDA limitation.

Summary of the issue:
Minor formatting issues with eSpeak.md file

Description of user facing changes:

Normalize capitalization to eSpeak
Normalize paths to NVDA root, link to them where possible
Added instruction to diff config file
Added example of expected build warnings

Summary of the issue:
When announcing if an object has details, more information can be provided about the role of the details.
For example, if a comment is tied to a word, "has comment" should be reported instead of "has details".

Description of how this pull request fixes the issue:
Collects the details role.

The attribute details role is determined in a number of cases.

Braille
Use has cmmt to report presence of comment role aria-details target. Discussion

Focus Mode
detailsRole is normalized on the NVDAObject level to a controlType.Role.

Chromium
The IA2 attribute details-roles is used to get the role.

This supports the following roles (code): comment, definition, doc-endnote, doc-footnote. Other roles are given a value of * .

Currently only chromium supports details-roles.
Additionally, doc-endnote and definition are not supported IA2 attributes, and are not supported in NVDA widely.

We limit reporting for all cases by only reporting the fully supported details-roles: doc-footnote, comment

Other roles are reported as "has details".

FireFox
The related details node is fetched using in process injection, and the IAccessible information is retrieved.
The role is determined from the IAccessible role of the related node.

This is slower and provides a wider reporting of roles.

Browse Mode
The detailsRole attribute is added directly to the buffer, either as a descriptive role string or a role integer as a string.

Testing strategy:
The system test cases test the details role for Chrome, using both focus and browse mode.

runsystemtests.bat -t "*aria details*"

Equivalent manual testing was performed using those test cases on both Chrome and FireFox.

Fixes #13232

Summary of the issue:
Since PR #12849, information about selected cells in LibreOffice Calc is queried using the 'IAccessibleTable2' interface which is supported from LibreOffice 7.3 on.
The call to the 'selectedCells' method on that interface requests a list of a11y objects for all currently selected cells, of which only the first and the last one are actually needed for the announcement of selected cells.
Since Calc spreadsheets have more than a billion cells, this is inefficient when many cells are selected and resulted in Calc becoming unresponsive.

Description of how this pull request fixes the issue:
Instead of using the 'selectedCells' method from the 'IAccessibleTable2' interface, the first and last selected cell are now retrieved using the 'accSelection' on the 'IAccessible' object of the table, which avoids that a11y objects for all other selected cells have to be generated as well.

Testing strategy:
use LibreOffice Calc 7.3 or above
select all cells in LO Calc and check that NVDA announces coordinate + content of the first cell (A1) and the last cell (AMJ1048576) in the spreadsheet
test a few other selections in the spreadsheet (use shift + arrow keys to increase/decrease selection)

…sts to workaround issues in find_module and for forward compatibility. (#13853)

None, discussion in PR #13814

Summary of the issue:
As mentioned in #13814 (comment) FileFinder.find_module is deprecated. find_spec is the recommended replacement method.
As noted in #13814 (comment), using either find_spec or find_module with pkgutil.iter_importers results in paths containing "." being incorrectly treated as python packages, causing #13813

Description of development approach
Description of user facing changes
No user facing change

Description of development approach
When checking if the given appModule exists, instead use importlib.util.find_spec, which does not have the same problematic behaviour as pkgutil.iter_importers.

Merge beta to master

Closes #13295 

#Summary of the issue:

eSpeak is updated using the steps outlined in espeak.md.

Build issues fixed:
1. When a language dictionary fails to compile, an `errno` is raised. our `IntEnum` implementation of `espeak_ng_STATUS` doesn't correctly capture `errno`. Usage of `IntFlag` is required.
1. The dictionary compilation action did not specify the name of the language.
This used to be handled by eSpeak implicitly through getting a mapping using the rules path.
This is no longer the case for some languages.
1. eSpeak added `CLEANFILES` for certain language dictionary components. This can be mirrored by `env.Clean` or `os.remove`.
1. A PR to eSpeak was created to fix building Malay (ms) espeak-ng/espeak-ng#1225.

# Description of user facing changes

Added languages:
  - Belarusian
  - Luxembourgish
  - Totontepec Mixe

# Description of development approach

New languages were added to the compile dictionary.

Summary of the issue:
The ui.browseableMessage has no margin. For people with visual difficulties, it makes more difficult to isolate the content of the browseable message from the text present in the background around the browseable message.

Description of user facing changes
The content of browseable message such as formatting information (double press of NVDA+F) is now rendered with a margin around the text.

Description of development approach
Just added the following style property to the message's body:
style="margin:1em"
The 1em measurement should correspond to 1 character.

Summary of the issue:
The BreakCommand is not implemented with SAPI4.
There is also a known issue with eSpeak not supporting the break SSML tag correctly.

Description of user facing changes
Fix pauses being announced correctly when using MathPlayer and SAPI4 or eSpeak.

Description of development approach
For SAPI5 the Pau tag is used to implement the pause.

There is a known issue with eSpeak and the break SSML tag, which has been fixed with a workaround, adding the strength attribute, while we wait for espeak-ng/espeak-ng#1232 to be fixed.

Summary of the issue:
There are no clear instructions for NVDA developers to test SAPI 4 synthesizers.
As SAPI 4 is no longer published by Microsoft, it requires research to set up and test SAPI 4 synthesizers with NVDA.

Description of user facing changes
Added notes for developers

Summary of the issue:
The width of the License Agreement was fixed, however the outer dialog scales with DPI.
This causes inconsistent behaviour for the License Agreement text sizing within the Launcher dialog.

Examples refer to a machine with high DPI and 200% scaling

For example, the width of the license agreement text for my machine display setting is roughly 2/3rds of the dialog.
Additionally, the GPL2 license text is manually wrapped wraps at different line lengths, with 80 being the most common.
Longer lines exist for custom changes to the GPL2 license.

Description of user facing changes
Makes the width of the license text dialog fit 80 characters of text comfortably.
Also changes the height of the dialog by ~100px (scaled) for readability.

Description of development approach
Get a the width of a line of license text by creating and destroying a hidden text control.
Use that to set the scaled size of the license text.

…lBuffer for PDF content (#13852)

Fixes #12920

# Summary of the issue:
Adobe Acrobat / Reader 64 bit crashes when NVDA renders a virtualBuffer for PDF content.
There are two reasons for this:
1. Adobe's IAccID custom interface has been changed so that specifically on 64 bit builds, the ID argument is now 64 bit wide instead of 32 bit. This meant that NVDA was using the wrong data type and wrong call signature for IAccID::get_accID, and therefore Acrobat / Reader was trying to write a 64 bit value in to the space that could only hold 32 bits, causing a buffer overrun.
2. Adobe Acrobat / Reader's accID values, including the MSAA child IDs used for IAccessible::get_accChild and AccessibleObjectFromEvent were 64 bit wide, though MSAA only supports 32 bit values. This would cause invalid and truncated values to be used for child IDs, in many cases causing a crash.

Adobe has addressed point 2 in Adobe Acrobat / Reader beta versions and will be in a stable build in the near future.
But NVDA needs to address point 1 in its own code.

# Description of user facing changes
Using a version of Adobe Acrobat / Reader with the required fixes on adobe's side, along with this PR in NVDA, the crash is avoided.
 
# Description of development approach
miscDeps has been updated to contain the newest version of acrobatAccess.idl from the Adobe Acrobat SDK.
The adobeAcrobat vbufBackend getAccID method has been changed to fetch the out param of IAccID::get_accID with a LONG_PRT which will be 64 bit wide on 64 bit Acrobat / Reader, and 32 bit wide on 32 bit Acrobat / Reader. The value is then static casted to long when returned. As Acrobat always uses 32 bit accID vlaues, no information will be lost in the conversion.

…h_did_not_occur` (#13877)

Summary of the issue:
While working on a separate PR, system tests were needed which changed the interval of checking speech, and to expect a failure.
This led to the contributor writing duplicate code to handle these cases, instead of improving the system test API.

That PR no longer requires this change, but the situation is generic enough to keep the API changes to make contributions easier in future.

Description of user facing changes
wait_for_specific_speech now accepts a parameter to change the checking interval.

A new function ensure_speech_did_not_occur has been introduced.

Objects from comInterfaces generally do not have helpful type hints.

Description of user facing changes
When a variable is type hinted with IUIAutomationTextRangeT supported functions will appear as type hints.

Description of development approach
Implements methods found in https://docs.microsoft.com/en-us/windows/win32/api/uiautomationclient/nn-uiautomationclient-iuiautomationtextrange, checked against usages in NVDA code.

…13906)

Fixes #13854

Summary of the issue:
When a tree item in the input gestures dialog is selected, then a filter event happens which makes the index no longer valid, an unhandled exception occurs.
This causes multiple Input Gestures to be able to be opened.

STR

Open input gestures dialog.
Arrow down to the 4th category (Configuration Profiles)
Press Shift+Tab to move to "filter by" edit field and type "z"
The dialog should refresh with 3 categories
Note an ERROR is logged, as the selected index (4) is larger than the number of categories
Close the Input Gestures dialog (press escape)
Open the Input Gestures dialog
Open a second Input Gestures dialog
Description of user facing changes
2 input gesture dialogs can no longer be opened.

Description of development approach
Unselect items when the input gesture filter is updated.

Summary of the issue:
In Windows Add/remove programs, there is a column that displays the estimated installation size of a product. This column is empty for NVDA.

Description of user facing changes
Calculate install size of the NVDA program files folder, and add it to the registry. This will be visible in Add/remove programs.

Description of development approach
I decided to calculate estimated size during installation. This takes the SystemConfig into account as that is part of the program files directory. This means that the estimated size is also based on the system config. I think this is OK, because when removing NVDA from Add/remove programs, the systemConfig dir is removed as well. Long story short, the estimated size is the best estimate we could get at time of installation

… braille display (#13131)

Fixes #2124
# Summary of the issue:
Some people prefer to be able to read in braille while still listening to the speech output for the current line/object. This is currently not possible, because every braille gesture will interrupt speech.

# Description of user facing changes
Adds a new setting: "Interrupt speech while scrolling", default  is "enabled".
The new setting determines if speech should be interrupted when the Braille display is scrolled backwards/forwards.
Previous/next line commands are not affected.

This is added as an option because some speech+braille users prefer a bimodal interaction pattern.
- For these users, speech may be distracting while reading Braille.
- These users repetitively swap between primarily focusing on speech or braille.
- For these users, the current and expected UX for cancelling speech when reading braille is to scroll the line of braille.
- Considering alternatives:
  - Most braille devices cannot detect fingers reading the display.
  - Using an additional braille gesture just to cancel speech will slow users down / isn't a good use of a button on a display.

To preserve the existing behavior, the option is enabled by default, interrupting speech when scrolling.
- Disabling this option allows speech to be heard while the user is simultaneously reading Braille.
- Users who don't find speech distracting with Braille, or rely on both Braille and speech, may prefer to disable the option.

# Description of how this pull request fixes the issue:
Add an option to interrupt speech while the display is being scrolled.
This option is enabled by default, so the previous behavior is preserved.
This implementation only works for scroll previous/next display and does not affect other gestures such as previous/next line.

Closes #13509

Summary of the issue:
The main use case is navigating character by character and a user encounters a character that they do not understand. The delayed phonetic character description is something like “alpha”/“beta”/“romeo”/“igloo”.

What makes understanding a character difficult?
This may be because a synthesizer pronounces a character unusually or indistinguishable from another character.
A user may also be hearing impaired or have other trouble processing the character. In this case, the user waits for the delayed phonetic description to occur.

Other ways to report the character description:
- script_review_currentCharacter
- script_review_currentWord
- script_review_currentLine
- script_reportCurrentLine

What makes determining the delay difficult?
The main determinate of the delay is the speed that a user interacts with the device, e.g. speed of navigating by character.
NVDA currently does not have a way to configure interaction rate, which is a general problem described in #13915.

Meeting auditory processing needs is generally achieved by adjusting the synthesizer rate.
Unfortunately, synthesizer rate varies by synthesizer, and so calculating a delay based on rate is challenging.

While a general solution for the interaction rate is blocked by #13915, using a sensible default will handle most users requirements. This delay can be configured easily by add-ons.

Description of user facing changes
Adds an option, which when enabled, causes character descriptions to be announced after a fixed delay of 1 second.
This delay value has been tested as a default in the “Enhanced phonetic reading” Add-on.

Description of development
This code modifies getTextInfoSpeech to emit a BreakCommand followed by several commands to speak a character description. This only happens if the unit of resolution is a single character, and the reason for querying for textInfo speech is caret. This causes NVDA to emit character descriptions in the following conditions:

when moving by character in an edit field.
When moving by character in review cursors.
When moving by character in browse mode.
When reporting single characters at review cursor.
Any other time that caret movement is being reported for single characters.
This solution also reads the character description with capitalization settings.

Using the BreakCommand means that the overall approach is simpler as opposed to using a timer, and handled by the synthesizer rather than NVDA.

It would be helpful if bug reporters include exact speech/braille that is expected vs. occurring.
This is requested in devDocs\githubIssueTemplateExplanationAndExamples.md but not in the issue template.

It would also be good to add a section for logs and other attachments, as they are often required when reporting an issue.
This is also requested in devDocs\githubIssueTemplateExplanationAndExamples.md but not in the issue template.

Description of user facing changes
Bug reports are now prompted to include explicit speech/braille and NVDA logs.

Summary of the issue:
There is no set of standards or guide when writing documentation for the "User Guide".

Description of user facing changes
The intended audience for this PR is NVDA contributors.
NVDA developers now have suggested formatting for key commands and feature flags.

Feature flag documentation suggests using definition lists.
The default CSS formatting for definition lists is not ideal, the term and definition are listed on separate lines. There is no text formatting, the only indication that a term is linked to a definition is an indentation in front of the term.