2025.1 Add-on API changes

[NVDA Add-on API Announcements]

NVDA 2025.1 is an API breaking release.

Reminder, this mailing list is read only, please provide feedback by replying directly to emails, or via GitHub.
This list is intended to notify of changes to the add-on API, for confirmation of the latest state for breakages or deprecations, please refer to the 'changes file' for the NVDA release you are interested in.

Add-on API changes have been merged, planned for inclusion in the 2024.1 release:
"Text displayed on a multiline braille display will now word wrap on every row in the braille window, not just at the end #17011"

Deprecations:
The braille.filter_displaySize extension point is deprecated. Please use braille.filter_displayDimensions instead.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Remove old winTerminalUIA module attribute #16820".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• NVDAObjects.UIA.winConsoleUIA.WinTerminalUIA has been removed with no public replacement.

Deprecations:

• None

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Remove FakeEmbeddingTextInfo which is no longer necessary" #16768.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• NVDAObjects.IAccessible.ia2TextMozilla.FakeEmbeddingTextInfo has been removed.

Deprecations:

• None

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Add ability to specify add-on store metadata URL from within NVDA" #17099.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The addonStore.network.BASE_URL constant has been removed. As the Add-on Store base URL is now configurable directly within NVDA, no replacement is planned.

Deprecations:

• None.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"soffice: Report keyboard-triggered font size change #17147".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The following symbols in appModules.soffice have been renamed:
  • SymphonyDocument.announceToolbarButtonToggle to SymphonyDocument.announceFormattingGestureChange
  • SymphonyDocument.script_toggleTextAttribute to SymphonyDocument.script_changeTextFormatting

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Remove unused 'upgrade' config profile section #17191".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The [upgrade] configuration section including [upgrade][newLaptopKeyboardLayout] has been removed.
  

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Correct internal gesture ID for Seika Notetaker #17047".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The space keyword argument for brailleDisplayDrivers.seikantk.InputGesture now expects an int rather than a bool.
  

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Add the ability to specify NVDA update check URL from within NVDA #17151".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The updateCheck.CHECK_URL constant has been removed.
  As the NVDA update check URL is now configurable directly within NVDA, no replacement is planned.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Fix braille next line command for documents of Notepad++ #17431".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• In NVDAObjects.window.scintilla.ScintillaTextInfo, if no text is selected, the `collapse` method is overriden to expand to line if the end parameter is set to True

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Remove winmm support from NVDA" #17496.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes

• The following symbols have been removed from nvwave: HWAVEOUT, LPHWAVEOUT, LPWAVEHDR, MAXPNAMELEN, MMSYSERR_NOERROR, usingWasapiWavePlayer, WAVEHDR, WAVEOUTCAPS, WHDR_DONE, WinmmWavePlayer, and winmm.
• gui.settingsDialogs.AdvancedPanelControls.wasapiComboBox has been removed.
• The WASAPI key has been removed from the audio section of the config spec.
• The output from nvwave.outputDeviceNameToID, and input to nvwave.outputDeviceIDToName are now string identifiers.

Deprecations:

• None.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

" Added short version for most commonly used command line options #17486".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes

• The following symbols have been removed with no replacement: languageHandler.getLanguageCliArgs, __main__.quitGroup and __main__.installGroup.
• Prefix matching on command line flags, e.g. using --di for --disable-addons is no longer supported.

Deprecations:

• NoConsoleOptionParser, stringToBool, stringToLang in __main__; use the same symbols in argsParsing instead.
• __main__.parser; use argsParsing.getParser() instead.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Create a MessageDialog API" #17304.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

• A new function, gui.guiHelper.wxCallOnMain, has been added, which allows safely and synchronously calling wx functions from non-GUI threads, and getting their return value.
• A new message dialog API has been added to gui.message.
  • Added classes: ReturnCode, EscapeCode, DialogType, Button, DefaultButton, DefaultButtonSet, MessageDialog.

Deprecations:

• The gui.message.messageBox and gui.runScriptModalDialog functions, and gui.nvdaControls.MessageDialog class are deprecated. Use gui.message.MessageDialog instead.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Add ability to add more constraints to bdDetect USB device registration #17537".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The useAsFallBack keyword argument of bdDetect.DriverRegistrar has been renamed to useAsFallback

Deprecations:

• bdDetect.DeviceType is deprecated in favour of bdDetect.ProtocolType and bdDetect.CommunicationType to take into account the fact that both HID and Serial communication can take place over USB and Bluetooth. 

On Friday, August 30, 2024 at 9:52:55 AM UTC+10 NVDA Add-on API Announcements wrote:

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Use endpoint IDs instead of device friendly names to store user's preferred output device" #17547.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The configuration key config.conf["speech"]["outputDevice"] has been removed. It has been replaced by `config.conf["audio"]["outputDevice"]`, which stores a Windows core audio endpoint device ID.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Fix audio output device selection" #17532.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The following symbols have been removed from nvwave: CALLBACK_EVENT, CALLBACK_FUNCTION, CALLBACK_NULL, LPWAVEFORMATEX, waveOutProc, WAVE_MAPPER.
• The outputDevice parameter to WasapiWavePlayer.__init__ should now only be passed string arguments.
• The deprecated closeWhenIdle and buffered parameters to WasapiWavePlayer.__init__ have been removed.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Make SAPI5 & MSSP voices use WavePlayer (WASAPI) #17592".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

•  Because SAPI5 voices now use nvwave.WavePlayer to output audio:
    * synthDrivers.sapi5.SPAudioState has been removed.
    * synthDrivers.sapi5.SynthDriver.ttsAudioStream has been removed.

On Friday, August 30, 2024 at 9:52:55 AM UTC+10 NVDA Add-on API Announcements wrote:

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Message Dialog API take 2" #17582 .

Please note that these changes replace those introduced in #1730.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

• A new function, gui.guiHelper.wxCallOnMain, has been added, which allows safely and synchronously calling wx functions from non-GUI threads, and getting their return value.
• A new message dialog API has been added to gui.message.
  • Added classes: ReturnCode, EscapeCode, DialogType, Button, DefaultButton, DefaultButtonSet, MessageDialog.

API Breaking Changes:

• updateCheck.UpdateAskInstallDialog no longer automatically performs an action when the update or postpone buttons are pressed. Instead, a callback property has been added, which returns a function that performs the appropriate action when called with the return value from the dialog.
• Dialogs opened with gui.runScriptModalDialog are now recognised as modal by NVDA.

Deprecations:

• The gui.message.messageBox and gui.runScriptModalDialog functions, and gui.nvdaControls.MessageDialog class are deprecated. Use gui.message.MessageDialog instead.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Sanitize browseableMessage html #17581".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• ui.browseableMessage now takes a parameter sanitizeHtmlFunc.
  This defaults to nh3.clean with default arguments.
  This means any HTML passed into ui.browseableMessage using isHtml=True is now sanitized by default.
  To change sanitization rules, such as whitelisting tags or attributes, create a function that calls nh3.clean with the desired parameters.

On Friday, August 30, 2024 at 9:52:55 AM UTC+10 NVDA Add-on API Announcements wrote:

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Remove 'Automatically set system focus to focusable elements' #17598".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The following API symbols related to the setting "Automatically set system focus to focusable elements" have been removed with no replacement:
  • globalCommands.GlobalCommands.script_toggleAutoFocusFocusableElements
  • config.conf["virtualBuffers"]["autoFocusFocusableElements"]
  • gui.settingsDialogs.BrowseModePanel.autoFocusFocusableElementsCheckBox

On Friday, August 30, 2024 at 9:52:55 AM UTC+10 NVDA Add-on API Announcements wrote:

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

'Add "Only in edit controls" mode for typing echo' #17505.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• Changed keyboard typing echo configuration from boolean to integer values.
  • config.conf["keyboard"]["speakTypedCharacters"] and config.conf["keyboard"]["speakTypedWords"] now use integer values.
  • Added TypingEcho enum in config.configFlags to represent these modes, 0=Off, 1=Only in edit controls, 2=Always.
  • gui.settingsDialogs.KeyboardSettingsPanel.wordsCheckBox and gui.settingsDialogs.KeyboardSettingsPanel.charsCheckBox have been removed.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Fix SAPI 4 driver" #17599.

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• Instances of autoSettingsUtils.driverSetting.DriverSetting with an id that starts with an underscore (_) are no longer shown in NVDA's settings.

Deprecations:

• SAPI4, synthDrivers.sapi4, is deprecated and planned for removal in 2026.1.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Add pyright for static type checking #17744".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• The winUser.paint has been renamed from painStruct to paintStruct, fixing a bug where passing in a PAINTSTRUCT would raise an exception.

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Simplify getDocFilePath function #17911".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• documentationUtils.getDocFilePath and installer.getDocFilePath no longer look for .txt files in locale documentation folders.

[NVDA Add-on API Announcements]

2025.1beta1 has been released.

API Status:

The add-on API for 2025.1 has entered feature freeze. Development is now focused on bug fixes. The core API functionality for this release has been established, and most changes introduced from this point should be minor and non-breaking. The API will be finalised with the 2025.1rc1 release, barring any emergency exceptions.

ATTENTION: This is an API breaking release. Please review the API breaking changes documented in this mailing list thread and thoroughly test your add-ons with this beta.

Action Items for Add-on Authors:

1. Test your add-ons against the 2025.1 API using 2025.1beta1
2. Consider publishing a beta/dev release to the Add-on Store for user testing

[NVDA Add-on API Announcements]

Add-on API changes have been merged, planned for inclusion in the 2025.1 release:

"Remove deprecated config options #18102".

If API breaks or planned future breaks (deprecations) will cause difficulties for the ongoing development of an add-on you maintain, please let NVDA developers know by replying directly to emails, or via GitHub.

Breaking changes:

• config.conf["documentFormatting"]["reportFontAttributes"]` has been removed, use config.conf["documentFormatting"]["fontAttributeReporting"] instead.
• config.conf["speech"]["includeCLDR"] has been removed, check/modify whether config.conf["speech"]["symbolDictionaries"] contains "cldr" instead.

[NVDA Add-on API Announcements]

2025.1beta6 has been released.

API Status:

This is the last planned beta for 2025.1.
The add-on API has now entered API freeze.
Only critical changes will be considered before the API is finalised with 2025.1rc1.

ATTENTION: This is an API breaking release. Please review the API breaking changes documented in this mailing list thread and thoroughly test your add-ons with this beta.

Action Items for Add-on Authors:

1. Perform final testing of your add-ons with 2025.1beta6
2. Submit beta/dev releases to the Add-on Store for user testing
3. Prepare stable releases for the upcoming RC

[NVDA Add-on API Announcements]

2025.1rc1 has been released.

API Status:

The add-on API for 2025.1 is now final.
ATTENTION: This is an API breaking release. Please review the final API breaking changes documented in this mailing list thread.

Action Items for Add-on Authors:

• Complete final testing with 2025.1rc1
• Release add-ons marked as compatible with the 2025.1 API
• Submit compatible add-ons to the Add-on Store's stable channel