Summary of the issue:
Liblouis 3.24.0 has been released.

Description of user facing changes
Updates liblouis to 3.24.0 which adds new braille tables. Changelog.

Description of development approach
Update liblouis submodule and make new braille tables available from the NVDA settings.

#14483 was reverted via #14516 due to an issue with rate boost.
eSpeak changed the compilation flag, and that change wasn't in the Makefile.am diff, so it was missed.
This is fixed in 7e558da

Link to issue number:
Closes #14281
Closes #14241
Addresses #13875 (comment)

Summary of the issue:
Janitorial update of eSpeak.
Removes a workaround added to handle a bug with eSpeaks BreakCommand implementation, tracked in espeak-ng/espeak-ng#1232, #13875 (comment)

Description of user facing changes
eSpeak is updated.
Fixes pronunciation of large numbers (#14241).

Description of development approach
Dropped strength for eSpeak BreakCommand attribute per espeak-ng/espeak-ng#1232 being fixed in eSpeak.

Janitorial update
Followed instructions in include/espeak.md.
Checked the following diffs.

cd include/espeak
git diff a51235aa b17ed2d6 src/windows/config.h
git diff a51235aa b17ed2d6 Makefile.am
Addressed the following eSpeak changes:

Introduction of langopts.c: espeak-ng/espeak-ng@4a28902
Fix up of code standards: change DINCLUDE to DUSE: espeak-ng/espeak-ng@ca1f590
Note that eSpeak has changed MBROLA compilation, does not affect our build: espeak-ng/espeak-ng@78ac6c4

A comment refers to an outdated and fixed Chromium bug.
I don't believe there is a public chromium bug tracker issue for this bug, which was fixed in 2018.
However, NVDA tracked the bug in this issue #8777

…4133)

Summary of the issue:
Feature flags use a default option that results in a default value.
For example, for a boolean feature flag could have three options: Default (Enabled), Enabled, Disabled.
When comparing feature flags __eq__ is overridden such that Default (Enabled) == Enabled.

NVDA checks if a value has changed before marking a profile as dirty so that it is written to disk when saving the configuration.
Due to __eq__ being overridden, NVDA does not write changes to disk if you change from the default value to the value of default.

STR:

With NVDA running, open braille preferences
Update "Interrupt Speech While scrolling" from Default (Enabled) to Enabled
Save the settings and exit the settings dialog
Re-open braille preferences, note the setting is still set to Default (Enabled)
Description of user facing changes
NVDA correctly updates feature flags when changing from the default value to the value of default.

Description of development approach
When checking if a config setting has changed, compare non-sections as strings, as this is how they are written to the config profile.

…I consumers (#14503)

Replaces #9917

Summary of the issue:
Tools like NVDA remote that need to intercept speech and braille output currently rely on monkeypatching to do this.

Description of user facing changes
It is no longer possible to override the display size of the braille handler by setting braille.handler.displaySize. It is also no longer possible to enable/disable the handler by setting braille.handler.enabled.

Description of development approach
Added the following extension points:

inputCore.manager.decide_executeGesture: Decider for filtering gestures
tones.decide_beep
nvwave.decide_playWaveFile
braille.handler.pre_writeCells
braille.handler.filter_displaySize
braille.handler.decide_enabled
braille.handler.displayChange
braille.handler.displaySizeChanged
This means that NVDA Remote and similar tools can at least drop all monkeypatching related to braille, playing tones and waves. Speech is a separate subject and will be handled in a follow up.

…om add-ons (#14481)

Replaces #14405

Summary of the issue:
Addons have the ability to import custom code from the add-ons directory. This is used to load install tasks, for example.
This mechanism was based on a deprecated solution in pkgutil and allowed importing modules using backslashes, resulting in malformed module identifiers in sys.modules.

Description of user facing changes
Importing submodules with loadModule should be done with a dot separated name (i.e. loadModule("lib.example") instead of loadModule("lib\\example")
loadModule now raises an exception when a module can't be found
Description of development approach
We no longer rely on pkgutil.ImpImporter.

Testing strategy:
Tested importing a lib module from an example addon as well as modules without init.py and submodules. Also tested modules with malformed content, resulting in tracebacks.

Known issues with pull request:
This would break cases where add-ons would use loadModule with a module name containing backslashes to import submodules. However, this scenario was broken anyway since it added malformed names to sys.modules. Note that this is strictly API breaking but I don't think noone was using it anyway.
As loadModule now raises exceptions, add-on authors need to account for that when using this API.

…14526)

Follow up of #14507, #14480

Summary of the issue:
Firefox incorrectly throws an error when browsing annotated content with an unsupported role.
Instead an unknown role should be reported: i.e. "has details".

The typing for annotation data structures were incorrect.

Description of user facing changes
When browsing content in Firefox with an annotation with unsupported role, "has details" is reported instead of throwing an error.

Description of development approach
Update typing to be more accurate for annotation data structures, log and return None in the Firefox case to match Chromium behaviour.
Use Tuples rather than generators for annotations.targets and annotations.roles.
Drops the superfluous/unused annotations.summaries

…hrough systray (#14523)

Summary of the issue:
When accessing NVDA menu via the systray (enter or right click on the NVDA icon), the item "Install pending update" is present even if there is nothing to install.

In the code, it appears that the function to evaluate whether this item should be present or not is called only when accessing NVDA menu via NVDA+N shortcut, not when accessing it via the systray icon.

Description of user facing changes
The item "Install pending update" will not be present anymore in NVDA menu when there is no pending update available.

Description of development approach
Moved the corresponding piece of code so that it is called in both scenarios.

Fixup of #14503

Summary of the issue:
When a handler was registered to decide_enabled and a cursor was blinking or a message with timeout was shown on the braille display, the display would still be updated. Found when working on NVDA Remote to integrate the extension points.
The extensionPointTestHelpers wouldn't strictly test whether the handler was actually called. Also the handler argument for value was incorrect and using a class to store the filter value was overdone.
Description of user facing changes
When a handler decides to disable the braille handler, cursor blinking is now stopped and a message is dismissed.

…flow window and Open With dialog to allow mouse and touch interaction (#14540)

Closes #14538
Closes #14539

Summary of the issue:
Mouse and/or touch interaction does not work properly for Windows 11 22H2 UI, including upcoming redesigned system tray overflow window and Open With dialog.

Description of user facing changes
Mouse and touch interaction will work when opening system tray overflow window and Open With dialog in Windows 11 2022 Update.

Description of development approach
Edited "isGoodUIAWindow" found in File Explorer and Open With app modules to classify the following window class names as good UIA windows:

File Explorer: TopLevelWindowForOverflowXamlIsland (upcoming redesigned system tray overflow window)
Open With: Open With (top-level window for the dialog)

Commits:

* appModules/openwith: recognize 'Open With' window class as a good UIA window. Re #14538.

Windows 11 22H2 (at least newer updates) include modernized Open With dialog powered by WinUI, meaning no proper mouse and/or touch interaction. Therefore treat the top window for this dialog as a good UIA window so mouse and touch interaction can work properly. Also, rewrite isGoodUIAWindow method with one window class name per line.

* appModules/openwith: add typing information for isGoodUIAWindow method

* appModules/explorer: add 'TopLevelWindowForOverflowXamlIsland' as a good UIA window. Re #14539.

Later revisions of Windows 11 Version 22H2 (2022 Update) comes with redesigned system tray overflow window (class name: TopLevelWindowForOverflowXamlIsland) but without proper mouse and touch interaction from NVDA. Therefore, add the new class as a good UIA window so mouse and touch interaction can work.

* appModules/explorer: add typing information for isGoodUIAWindow method.

* appModules/explorer and openwith: update copyright year

* appModules/explorer: hwnd: int -> hwnd type

Co-authored-by: Sean Budd <seanbudd123@gmail.com>

* appModules/openwith: hwnd: int -> hwnd type

* appModules/explorer and openwith: move winAPI import to top of the module.

Suggested by Sean Budd (NV Access): move winAPI import to the top of the modules.

* update changes

Co-authored-by: Sean Budd <sean@nvaccess.org>

Summary of the issue:
When testing for deprecated code, the following message is found when importing something (even not deprecated) from security.py, e.g.:
from utils.security import post_sessionLockStateChanged

DEBUG - utils.security.__getattr__ (17:36:01.633) - MainThread (17584):
Deprecated __path__ imported while _allowDeprecatedAPI is False
Description of user facing changes
No change for users.

For developers, when deprecated functions are not allowed, removed irrelevant log messages, e.g. indicating that __path__ is deprecated.

Description of development approach
Fix made in the logic of utils.security.__getattr__ in order not to log a debug message for any missing variable in utils.security (e.g. __path__)
Removed the log.debug which did not seem useful in any case.
While checking at other deprecation management functions, moved the docstrings which were found not at the top of the functions.

…x FilterValueT name (#14549)

Summary of the issue:
FilterValueTypeT nneeded renaming to FilterValueT and had a wrong string in its TypeVar declaration.
When experimenting with the extensionPoints, particularlyy with registering a handler to decide_executeGesture in a braille display driver, I discovered that inputCore was not yet initialized when initializing the driver and therefore extension point registration failed.
Description of user facing changes
Moved extension points, changes file is changed as part of this pr to reflect this.

Description of development approach
Just moving and renaming code

Link to issue number:
Fixes #14527

May be considered a follow-up of #14233.

Summary of the issue:
When configuring NVDA Modifier Key for a non-default profile and for the default profile, we can end-up with no NVDA key defined at all in the non-default profile (see #14527 for detailed steps).

This is due to the fact that the config stores one item per NVDA key but that there is a dependency between these values to honor the requirement that at least one key should be defined as NVDA key. These values are checked when changing NVDA keys via the GUI. But the requirement may be missed when switching profiles and stacking their configurations.

There is also a second scenario allowing to have no NVDA key defined using only default profile:

In keyboard settings enable only caps lock and disable both insert, then validate
Open the NVDA startup dialog via Help menu, uncheck caps lock and validate.
This scenario is quite unlikely but there is no check in NVDA startup dialog to prevent such situation.

Description of user facing changes
Situations where no NVDA key is defined will not be possible anymore.

Description of development approach
Use only one config item to store the used NVDA modifier keys.
Define a config flag for NVDA key; each value corresponds to one bit so that all the values can be bitwise or-ed and the reesulting value can be stored in the config as an integer.

…r().processorArchitecture in most cases (#14564)

Closes #14534

Summary of the issue:
Replace os.environ["PROCESSOR_ARCHITEW6432"] with winVersion.getWinVer().processorArchitecture in most cases (see below for exceptions).

Description of user facing changes
None

Description of development approach
Replace os.environ["PROCESSOR_ARCHITEW6432"] with winVersion.getWinVer().processArchitecture in the following cases:

appModuleHandler.AppModule: is64bitProcess, appArchitecture
NVDA helper: when starting appropriate helper suite for the right 64-bit architecture
COM registration fixing tool: determining 32-bit or 64-bit Windows version
The only exception is update check, specifically since Windows 7 service pack 1 string must be recorded correctly; when NVDA moves to supporting Windows 8.1/10 or later, this can be dropped (no more service packs), allowing update check facility to switch to using winVersion.WinVersion class attributes, including processor architecture.


Commits:

* appModuleHandler.AppModule: os.environ -> processorArchitecture. Re #14534.

Replace usage of os.environ['PROCESSOR_ARCHITEW6432'] with winVersion.getWinver().processorArchitecture (this string comes from os.environ anyway). This affects is64bitProcess and appArchitecture methods in app module clas.

* COM registration fixing tool: os.environ -> processorArchitecture. Re #14534.

Replace os.environ with processorArchitecture when determining 32-bit versus 64-bit Windows.

* NVDA helper: os.environ -> processorArchitecture. Re #14534.

Store processorArchitecture string in the 'arch' variable when starting NVDA helper processes on various 64-bit architectures (AMD64, ARM64).

* Add type information for edited functions/nethods. Re #14534

* Update copyright year for modified files. Re #14534

* appModuleHandler.AppModule.is64BitProcess: lint

Summary of the issue:
Registering for custom UIA annotations and properties can only be done after NVDAHelper is initialized. In normal usage this is not a problem, however since registration occurs on import it is impossible to write unit tests or generate developer documentation for anything which imports from NVDAObjects.UIA. 

Description of user facing changes
This should affect only developers - classes holding custom UIA properties and annotations are no longer singletons.

Description of development approach
Rather than making UIAHandler.customAnnotations.CustomAnnotationTypesCommon, UIAHandler.customProps.CustomPropertiesCommon and the Excel specific annotations and properties singletons, we now register for custom properties and annotations first time they're needed rather than on import. To avoid unnecessary interactions with UIA registered id's are cached for lifetime of NVDA. While at it I've also moved imports below the module level docstring since that is the more standard place.

Fixes #14562

Summary of the issue:
Alert event text is not shown on braille displays when the event occurs such as when downloading files via Google Chrome.

Description of user facing changes
NVDA will present alert messages in braille.

Description of development approach
Add braille output (braille.handler.message) to NVDAObjects.IAccessible.IAccessible.event_alert, borrowing heavily from notification behavior.

commits:

* NVDAObjects.IAccessible: report alerts in braile. Re #14562.

When processing MSAA alert event, only speech output was invoked whereas other implementations such as notification behavior class also brailled alerts and notifications. Therefore add braille output to alert event handler, both for the root alert and its children, borrowing heavily from notification behavior.

* NVDAObjects.IAccessible: update copyright year

* NVDAObjects.IAccessible: add type information for alert event. Re #14562

* NVDAObjects.IAccessible: remove braille message comment.

Suggestion from Sean Budd (NV Access): since braille.handler.message comment is found in other places and the actual method is used elsewhere, remove the message comment.

* update changes

* fixup change

Co-authored-by: Sean Budd <sean@nvaccess.org>

Summary of the issue:
Previously, in the "Technical Design Overview" document, the startupShutdown link under the Launcher heading didn't work.

Description of user facing changes
Now, the startupShutdown link should correctly link to NVDA Starting and Exiting outline page.

Summary of the issue:
No support for Tivomatic Caiku Albatross 46/80 braille display models.

Description of how this pull request fixes the issue:
General

Different to many other displays, Albatross models do not wait for the driver to send a query of their presence to the device. Instead, the device continuously sends initialization packets until driver requests to them quit, as the connection has been established.

These displays also expect regular data packets, with frequency of at least one every 2 seconds. Otherwise they fall back to "wait for connection" state and start sending the initialization packets until the driver sends a quit packet.

Similarly, if the user enters the device internal menu, after exiting, initialization packets are continuously sent until driver sends quit packet.

Init packets are also sent when device is powered off and then on.

Display init packets consist of two bytes: the first one is \xff which tells that this is an init packet. The second one is a settings byte which contains display settings like length of display and number of status cells. The most meaningful setting is the length of display. Other settings contained by settings byte can be regarded as notes to screenreader, and it is screenreader or driver job to use them when applicable. For example, there are no separate status cells in the device but if screenreader supports using status cells, it can be notified to use them by settings byte.

The settings byte can be anything between \x00 and \xff. Thus it could be the same as init byte.

It is possible that settings byte may have same value with any display buttons. Because init packets may be sent also during session (user exits display internal menu for example), it is essential to know if byte is button press or part of init packet.

When display is in "wait for connection" state, it sends init packets continuously. As such, there may be hundreds of bytes to handle. There are several rx buffers between device and driver which seems to cause situation that all data cannot be read with one read operation. It cannot be known when all data has been read. This is the case with init packets but also with key combinations.

There are other devices with same PID&VID. When automatic braille display detection is used, other displays with same PID&VID are tried before Albatross. Those drivers try to send queries to the port to detect their own displays. These queries may cause Albatross to send unexpected init packets which in turn could disturb this driver - it could get inappropriate settings byte. This is tried to prevent by resetting I/O buffers so that strange packets would be discarded.

If however, there are still strange init packets, Albatross should be manually selected from the display list.

To reduce complexity of data handling this driver accepts only settings bytes <= \xfe. From user perspective this means that with 80 model user can ask screenreader to use at most 14 status cells when without limitation user could ask 15. Limitation is applied only if user has switched all other settings to values that cause value of byte to be \xff. From settings byte for status cells there are reserved the most right 4 bits. Limitation does not affect on 46 cells model because the most left bit of byte defines the length of display (0 for 46 and 1 for 80 cells model).

Note: This driver ignores status cells related settings because NVDA does not use status cells at the moment.

Driver requirements

support for both 46 and 80 cells models
support for both automatic and manual detection
when connected allows device plugging out and in, and power switching off and on so that display content is up-to-date and buttons work as expected after these operations.
Design

Driver has modular structure:

constants.py contains all the constant definitions, for example button values and names.

driver.py is the main part of the code. It implements BrailleDisplayDriver class which is in response of all read and write operations. It also takes care to format data which is meant to be displayed on the braille line.

Important main functions of BrailleDisplayDriver are:

_readHandling; performs connecting/reconnecting to the device, and all read operations during connection
_somethingToWrite; performs all write operations to the display
display; prepares data to be displayed on the braille line
In gestures.py numeric values of pressed buttons are interpreted as gestures so that they can be forwarded to NVDA input system.

_threads.py defines two threads. Thread called albatross_read calls BrailleDisplayDriver _readHandling function when it gets signaled that port has data to be read. Idea is somewhat similar to hwIo onReceive function. For deeper read and write operations control own thread was implemented. In addition, it calls _readHandling if it detects port problems so that _readHandling can try to reconnect. Albatross_read thread sleeps most of the time because user does not press buttons continuously, and connection problems occur rarely.

The second thread is timer which checks periodically (after approximately 1.5 seconds) that some data has been sent to display so that it keeps connected. _SomethingToWrite function updates time of last write operation. If there is at least 1.5 seconds from last write operation, display is feeded data packet containing START_BYTE and END_BYTE which enclose data which is sent to be displayed on the braille line.