See also: #12344, #12353, #10799, #8709, #13579

Current problems:

• Cannot rename buttons / add custom buttons (addon author request)
  • gui.messageBox does not allow button renaming #12344
  • Add a gui.MessageDialog function, in order to gain the features of dialogs, while still protecting from calling wx.MessageDialog #12353
• An open message dialog blocks exiting NVDA, and isn’t refocused
• An open message dialog without wx.OK or wx.CANCEL as an option cannot be closed with Alt+F4/Escape
  • Run COM Registration fixing tool Dialog can't be closed by ALT+F4 or ESC #10799
• An open message dialog blocks other input (example: opening the NVDA menu with the about dialog open)
  • Add a gui.MessageDialog function, in order to gain the features of dialogs, while still protecting from calling wx.MessageDialog #12353
  • Redesign of the NVDA About Window #8709
• Dialogs cannot have context help associated with them
  • Refactor COM Registration Fixing Tool part 2: remove bugs, return Windows errors, improve UX #12355
• unprotected open modals crash NVDA or cause undefined behaviour when exiting: Open modals crash NVDA when exiting #13579
• Ensure that the test Quits from keyboard with about dialog open is re-enabled and works. Tagged with # Excluded to be fixed still (#12976), however that issue is closed.

Requirements for the API

A developer should be able to:

• rename 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)
  • 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
• for modal dialogs:
  • if wx.CANCEL is provided, make the dialog close-able with alt+F4 and escape
  • 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

Constraints from wxPython

Support across wx.MessageBox, wx.MessageDialog and wx.Dialog for the following:

• if a default return code is provided, make the dialog close-able with alt+F4 and escape
  • this is the behaviour already when wx.CANCEL is an option for the wx.MessageBox/wx.MessageDialog. If Yes/No is required, we should not accept alt+F4 and escape
  • in Run COM Registration fixing tool Dialog can't be closed by ALT+F4 or ESC #10799 wx.CANCEL should replace wx.NO and the buttons should be renamed appropriately

wx.Dialog or wx.MessageDialog is required to add the following:

• rename buttons
• associate context help with the given message box

wx.MessageBox is a function that doesn't support this.
Using wx.MessageDialog directly also can implement this.

wx.Dialog with .Show is required to add the following :

• provide a default return code when dialogs are forced to close (eg via an exit, perform cancel)
• 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

wx.Dialog.ShowModal is blocking, so .Show must be used.
wx.MessageBox and wx.MessageDialog doesn't support .Show(), but wx.Dialog does.

Suggestions moving forward:

In 2022.1:

• gui.IsInMessageBox was a boolean, this has been replaced by a function gui.message.isModalMessageBoxActive, which tracks if a messageBox is open in a safer manner. Done in Replace boolean gui.IsInMessageBox with function gui.message.isModalMessageBoxActive #13376 .

In a future release

• Create a new gui.MessageDialog class, encourage migration to using it instead of gui.messageBox.
  • gui.messageDialog should not subclass wx.MessageDialog, and instead be a custom wx.Dialog subclass
  • override Show and ShowModal to track instances to track in IsInMessageBox
• Run COM Registration fixing tool Dialog can't be closed by ALT+F4 or ESC #10799 wx.CANCEL should be replaced with wx.NO to enable esc/alt+f4, with the buttons renamed

Reference documentation

• wx.MessageBox documentation
• wx.MessageDialog documentation
• wx.RichMessageDialog documentation
• wx.Dialog documentation

Additional context

Fix up #12984
#12976

Draft Sample API

class MessageBoxReturnCode(IntEnum):
	OK = wx.OK
	YES = wx.YES
	NO = wx.NO
	CANCEL = wx.CANCEL


class MessageDialog(
		DpiScalingHelperMixinWithoutInit,
		ContextHelpMixin,
		wx.Dialog,
		metaclass=SIPABCMeta
):
	def __init__(
		self, 
		parent: wx.Window,
		message: str,
		caption: str = wx.MessageBoxCaptionStr,
		style: int = wx.OK | wx.CENTER,
		**kwargs,
	) -> None:
		super().__init__(parent, message, caption, style, **kwargs)

	def Show(self) -> None:
		"""Show a non-blocking dialog.
		Attach buttons with button handlers"""
		pass

	def defaultAction(self) -> None:
	       return None

	@staticmethod
	def CloseInstances() -> None:
		"""Close all dialogs with a default action"""
		pass

	@staticmethod
	def BlockingInstancesExist() -> bool:
		"""Check if dialogs are open without a default return code
		(eg Show without `self._defaultReturnCode`, or ShowModal without `wx.CANCEL`)"""
		pass

	@staticmethod
	def FocusBlockingInstances() -> None:
		"""Raise and focus open dialogs without a default return code
		(eg Show without `self._defaultReturnCode`, or ShowModal without `wx.CANCEL`)"""
		pass