Create a MessageDialog API

[SaschaCowley]

Link to issue number:

Closes #13007
Closes #12344
Closes #12353

Summary of the issue:

Currently, there are several ways to create message boxes/dialogs in NVDA, all of them with their own drawbacks.
Additionally, subclassing wx.Dialog (or using it directly) brings with it the risk of breaking parts of NVDA. See #13007 for in-depth discussion.

Thus, a new API for creating highly customizable dialogs that work well with NVDA is desired.

Description of user facing changes

This PR does not, in itself, introduce any end-user facing changes. However, it lays the groundwork for closing a number of issues.

Description of development approach

Subclassed wx.Dialog to add the desired functionality in #13007

Re-implemented the about box to use a MessageDialog.

Added a callback field to gui.blockAction._Context to allow adding a function to execute when the block condition is met.

Features and tasks

• Rename buttons
• Add custom buttons
• Associate context help with the given message box
• Show the dialog as a modal or a non-modal
• for non modal dialogs:
  • provide a default return code when dialogs are forced to close (eg via an exit, perform cancel) (WIP)
  • attach a callback to handle return codes
  • refocus a dialog in the event of needing to close it
  • if a default return code is provided, make the dialog close-able with alt+F4 and escape (WIP)
• for modal dialogs:
  • if wx.CANCEL is provided, make the dialog close-able with alt+F4 and escape (mostly done)
  • nice to have:
    • if wx.CANCEL is provided, perform this action when dialogs are forced to close.
    • refocus a dialog in the event of needing to close it
• Ensure that the test Quits from keyboard with about dialog open is re-enabled and works.
• Block exiting NVDA with modal MessageDialogs open.
• Focus open MessageDialogs without default actions when exiting.
• Tests
  • Unit tests
• Document the new API in the developer guide
• Migrate the new API from gui.MessageDialog to gui.message.
• Mark other means of creating message dialogs as deprecated.
  • Re implement their internals to use the new API
    • gui.message.messageBox
    • gui.nvdaControls.MessageDialog
    • gui.nvdaControls._ContinueCancelDialog

Testing strategy:

Unit and manual tests.

Unit tests are extensive, and reach around 85% coverage of the newly added code.

Message box shim tested with a variety of inputs and unittests. This is a fairly straightforward adapter.

nvdaControls.MessageDialog tested that screen curtain and add-on install warning dialogs still work as expected. Its private subclass, _ContinueCancelDialog, was tested by attempting to run the CRFT.

Known issues with pull request:

Internal dialogs are yet to be migrated. This should be done gradually before the existing means of creating message dialogs are removed.

Slightly odd behaviour when a callback function blocks, and focusBlockingInstances is called, where a hidden dialog is focused. This can be worked around, but possibly not without unintended consequences.

Some invalid combinations (namely a button which is set as the default action but set not to close the dialog) are silently changed. While documenting this should be sufficient, logging or raising an exception may be warranted.

Visual proportions of the re-implemented About dialog are different.

The ctrl+c behaviour of copying the dialog's title, contents and buttons is not supported.

Future work

• Remove all internal use of deprecated message dialog APIs.
• Remove deprecated message dialog APIs in 2026.1.

Nice to have

• Implement system tests for the new API.
• Comprehensively document a manual test plan, and develop any associated scripts.
• Add the ability to set a callback after a button has been added.
• Add a helper to add a "don't show this message again" checkbox.

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.

Summary by CodeRabbit

Release Notes for NVDA 2025.1

• New Features

  • Support for math in PDFs, including MathML formulas.
  • New commands to adjust the volume of other applications.
  • Ability to navigate per sentence in Microsoft PowerPoint using keyboard shortcuts.
  • Enhanced URL reporting in Mozilla Firefox, including text fragments.
  • Added actions in the Add-on Store for managing add-on installations.
  • Support for specifying mirror URLs for updates and the Add-on Store.
  • Sorting options in the Add-on Store by publication date.
  • Automatic language switching with SAPI5 and Microsoft Speech Platform voices.
  • Configuration for braille navigation to speak current lines or paragraphs.
  • Improved reporting of selection updates in Microsoft Word.

• Documentation

  • Added a new section on the message dialog API in the developer guide, detailing usage and customization options.

[seanbudd]

Thanks @SaschaCowley for all your excellent work here! Full review complete!

[seanbudd]

yahoo congrats on finishing this!

[gerald-hartig]

Nice work @SaschaCowley