Message Dialog API take 2

projectDocs/dev/developerGuide/developerGuide.md

@@ -1445,3 +1445,233 @@ Please see the `EventExtensionPoints` class documentation for more information,
 |`Action` |`post_reviewMove` |the position of the review cursor has changed.|
 |`Action` |`post_mouseMove` |the mouse has moved.|
 |`Action` |`post_coreCycle` |the end of each core cycle has been reached.|
+
+## Communicating with the user
+
+### The message dialog API
+
+The message dialog API provides a flexible way of presenting interactive messages to the user.
+The messages are highly customisable, with options to change icons and sounds, button labels, return values, and close behaviour, as well as to attach your own callbacks.
+
+All classes that make up the message dialog API are importable from `gui.message`.
+While you are unlikely to need all of them, they are enumerated below:
+
+* `ReturnCode`: Possible return codes from modal `MessageDialog`s.
+* `EscapeCode`: Escape behaviour of `MessageDialog`s.
+* `DialogType`: Types of dialogs (sets the dialog's sound and icon).
+* `Button`: Button configuration data structure.
+* `DefaultButton`: Enumeration of pre-configured buttons.
+* `DefaultButtonSet`: Enumeration of common combinations of buttons.
+* `MessageDialog`: The actual dialog class.
+
+In many simple cases, you will be able to achieve what you need by simply creating a message dialog and calling `Show` or `ShowModal`. For example:
+
+```py
+from gui.message import MessageDialog
+from gui import mainFrame
+
+MessageDialog(
+	mainFrame,
+	_("Hello world!"),
+).Show()
+```
+
+This will show a non-modal (that is, non-blocking) dialog with the text "Hello world!" and an OK button.
+
+If you want the dialog to be modal (that is, to block the user from performing other actions in NVDA until they have responded to it), you can call `ShowModal` instead.
+
+With modal dialogs, the easiest way to respond to user input is via the return code.
+
+```py
+from gui.message import DefaultButtonSet, ReturnCode
+
+saveDialog = MessageDialog(
+	mainFrame,
+	_("Would you like to save your changes before exiting?"),
+	_("Save changes?"),
+	buttons=DefaultButtonSet.SAVE_NO_CANCEL
+)
+
+match saveDialog.ShowModal():
+	case ReturnCode.SAVE:
+		...  # Save the changes and close
+	case ReturnCode.NO:
+		...  # Discard changes and close
+	case ReturnCode.CANCEL:
+		...  # Do not close
+```
+
+For non-modal dialogs, the easiest way to respond to the user pressing a button is via callback methods.
+
+```py
+def readChangelog():
+	...  # Do something
+
+def downloadUpdate():
+	...  # Do something
+
+def remindLater():
+	...  # Do something
+
+updateDialog = MessageDialog(
+	mainFrame,
+	"An update is available. "
+	"Would you like to download it now?",
+	"Update",
+	buttons=None,
+).addYesButton(
+	callback=downloadUpdate
+).addNoButton(
+	label=_("&Remind me later"),
+	fallbackAction=True,
+	callback=remindLater
+).addHelpButton(
+	label=_("What's &new"),
+	callback=readChangelog
+)
+
+updateDialog.Show()
+```
+
+You can set many of the parameters to `addButton` later, too:
+
+* The default focus can be set by calling `setDefaultFocus` on your message dialog instance, and passing it the ID of the button to make the default focus.
+* The fallback action can be set later by calling `setFallbackAction` or `SetEscapeId` with the ID of the button which performs the fallback action.
+* The button's label can be changed by calling `setButtonLabel` with the ID of the button and the new label.
+
+#### Fallback actions
+
+The fallback action is the action performed when the dialog is closed without the user pressing one of the buttons you added to the dialog.
+This can happen for several reasons:
+
+* The user pressed `esc` or `alt+f4` to close the dialog.
+* The user used the title bar close button or system menu close item to close the dialog.
+* The user closed the dialog from the Task View, Taskbar or App Switcher.
+* The user is quitting NVDA.
+* Some other part of NVDA or an add-on has asked the dialog to close.
+
+By default, the fallback action is set to `EscapeCode.CANCEL_OR_AFFIRMATIVE`.
+This means that the fallback action will be the cancel button if there is one, the button whose ID is `dialog.GetAffirmativeId()` (`ReturnCode.OK`, by default), or `None` if no button with either ID exists in the dialog.
+You can use `dialog.SetAffirmativeId(id)` to change the ID of the button used secondarily to Cancel, if you like.
+The fallback action can also be set to `EscapeCode.NO_FALLBACK` to disable closing the dialog like this entirely.
+If it is set to any other value, the value must be the id of a button to use as the default action.
+
+In some cases, the dialog may be forced to close.
+If the dialog is shown modally, a calculated fallback action will be used if the fallback action is `EscapeCode.NO_FALLBACK` or not found.
+The order of precedence for calculating the fallback when a dialog is forced to close is as follows:
+
+1. The developer-set fallback action.
+2. The developer-set default focus.
+3. The first button added to the dialog that closes the dialog.
+4. The first button added to the dialog, regardless of whether it closes the dialog.
+5. A dummy action that does nothing but close the dialog.
+   In this case, and only this case, the return code from showing the dialog modally will be `EscapeCode.NO_FALLBACK`.
+
+#### A note on threading
+
+**IMPORTANT:** Most `MessageDialog` methods are **not** thread safe.
+Calling these methods from non-GUI threads can cause crashes or unpredictable behavior.
+
+When calling non thread safe methods on `MessageDialog` or its instances, be sure to do so on the GUI thread.
+To do this with wxPython, you can use `wx.CallAfter` or  `wx.CallLater`.
+As these operations schedule the passed callable to occur on the GUI thread, they will return immediately, and will not return the return value of the passed callable.
+If you want to wait until the callable has completed, or care about its return value, consider using `gui.guiHelper.wxCallOnMain`.
+
+The `wxCallOnMain` function executes the callable you pass to it, along with any positional and keyword arguments, on the GUI thread.
+It blocks the calling thread until the passed callable returns or raises an exception, at which point it returns the returned value, or re-raises the raised exception.
+
+```py
+# To call
+someFunction(arg1, arg2, kw1=value1, kw2=value2)
+# on the GUI thread:
+wxCallOnMain(someFunction, arg1, arg2, kw=value1, kw2=value2)
+```
+
+In fact, you cannot create, initialise, or show (modally or non-modally) `MessageDialog`s from any thread other than the GUI thread.
+
+#### Buttons
+
+You can add buttons in a number of ways:
+
+* By passing a `Collection` of `Button`s to the `buttons` keyword-only parameter to `MessageDialog` when initialising.
+* By calling `addButton` on a `MessageDialog` instance, either with a `Button` instance, or with simple parameters.
+  * When calling `addButton` with a `Button` instance, you can override all of its parameters except `id` by providing their values as keyword arguments.
+  * When calling `addButton` with simple parameters, the parameters it accepts are the same as those of `Button`.
+  * In both cases, `id` or `button` is the first argument, and is positional only.
+* By calling `addButtons` with a `Collection` of `Button`s.
+* By calling any of the add button helpers.
+
+Regardless of how you add them, you cannot add multiple buttons with the same ID to the same `MessageDialog`.
+
+A `Button` is an immutable data structure containing all of the information needed to add a button to a `MessageDialog`.
+Its fields are as follows:
+
+| Field | Type | Default | Explanation |
+|---|---|---|---|
+| `id` | `ReturnCode` | No default | The ID used to refer to the button. |
+| `label` | `str` | No default | The text label to display on the button. Prefix accelerator keys with an ampersand (&). |
+| `callback` | `Callable` or `None` | `None` | The function to call when the button is clicked. This is most useful for non-modal dialogs. |
+| `defaultFocus` | `bool` | `False` | Whether to explicitly set the button as the default focus. (1) |
+| `fallbackAction` | `bool` | `False` | Whether the button should be the fallback action, which is called when the user presses `esc`, uses the system menu or title bar close buttons, or the dialog is asked to close programmatically. (2) |
+| `closesDialog` | `bool` | `True` | Whether the button should close the dialog when pressed. (3) |
+| `returnCode` | `ReturnCode` or `None` | `None` | Value to return when a modal dialog is closed. If `None`, the button's ID will be used. |
+
+1. Setting `defaultFocus` only overrides the default focus:
+
+  * If no buttons have this property, the first button will be the default focus.
+  * If multiple buttons have this property, the last one will be the default focus.
+
+2. `fallbackAction` only sets whether to override the fallback action:
+
+  * This button will still be the fallback action if the dialog's fallback action is set to `EscapeCode.CANCEL_OR_AFFIRMATIVE` (the default) and its ID is `ReturnCode.CANCEL` (or whatever the value of `GetAffirmativeId()` is (`ReturnCode.OK`, by default), if there is no button with `id=ReturnCode.CANCEL`), even if it is added with `fallbackAction=False`.
+    To set a dialog to have no fallback action, use `setFallbackAction(EscapeCode.NO_FALLBACK)`.
+  * If multiple buttons have this property, the last one will be the fallback action.
+
+3. Buttons with `fallbackAction=True` and `closesDialog=False` are not supported:
+
+  * When adding a button with `fallbackAction=True` and `closesDialog=False`, `closesDialog` will be set to `True`.
+  * If you attempt to call `setFallbackAction` with the ID of a button that does not close the dialog, `ValueError` will be raised.
+
+A number of pre-configured buttons are available for you to use from the `DefaultButton` enumeration, complete with pre-translated labels.
+None of these buttons will explicitly set themselves as the fallback action.
+You can also add any of these buttons to an existing `MessageDialog` instance with its add button helper, which also allows you to override all but the `id` parameter.
+The following default buttons are available:
+
+| Button | Label | ID/return code | Closes dialog | Add button helper |
+|---|---|---|---|---|
+| `APPLY` | &Apply | `ReturnCode.APPLY` | No | `addApplyButton` |
+| `CANCEL` | Cancel | `ReturnCode.CANCEL` | Yes | `addCancelButton` |
+| `CLOSE` | Close | `ReturnCode.CLOSE` | Yes | `addCloseButton` |
+| `HELP` | Help | `ReturnCode.HELP` | No | `addHelpButton` |
+| `NO` | &No | `ReturnCode.NO` | Yes | `addNoButton` |
+| `OK` | OK | `ReturnCode.OK` | Yes | `addOkButton` |
+| `SAVE` | &Save | `ReturnCode.SAVE` | Yes | `addSaveButton` |
+| `YES` | &Yes | `ReturnCode.YES` | Yes | `addYesButton` |
+
+As you usually want more than one button on a dialog, there are also a number of pre-defined sets of buttons available as members of the `DefaultButtonSet` enumeration.
+All of them comprise members of `DefaultButton`.
+You can also add any of these default button sets to an existing `MessageDialog` with one of its add buttons helpers.
+The following default button sets are available:
+
+| Button set | Contains | Add button set helper | Notes |
+|---|---|---|---|
+| `OK_CANCEL` | `DefaultButton.OK` and `DefaultButton.Cancel` | `addOkCancelButtons` | |
+| `YES_NO` | `DefaultButton.YES` and `DefaultButton.NO` | `addYesNoButtons` | You must set a fallback action if you want the user to be able to press escape to close a dialog with only these buttons. |
+| `YES_NO_CANCEL` | `DefaultButton.YES`, `DefaultButton.NO` and `DefaultButton.CANCEL` | `addYesNoCancelButtons` | |
+| `SAVE_NO_CANCEL` | `DefaultButton.SAVE`, `DefaultButton.NO`, `DefaultButton.CANCEL` | `addSaveNoCancelButtons` | The label of the no button is overridden to be "Do&n't save". |
+
+If none of the standard `ReturnCode` values are suitable for your button, you may also use `ReturnCode.CUSTOM_1` through `ReturnCode.CUSTOM_5`, which will not conflict with any built-in identifiers.
+
+#### Convenience methods
+
+The `MessageDialog` class also provides a number of convenience methods for showing common types of modal dialogs.
+Each of them requires a message string, and optionally a title string and parent window.
+They all also support overriding the labels on their buttons via keyword arguments.
+They are all thread safe.
+The following convenience class methods are provided (keyword arguments for overriding button labels indicated in parentheses):
+
+| Method | Buttons | Return values |
+|---|---|---|
+| `alert` | OK (`okLabel`) | `None` |
+| `confirm` | OK (`okLabel`) and Cancel (`cancelLabel`) | `ReturnCode.OK` or `ReturnCode.Cancel` |
+| `ask` | Yes (`yesLabel`), No (`noLabel`) and Cancel (`cancelLabel`) | `ReturnCode.YES`, `ReturnCode.NO` or `ReturnCode.CANCEL` |

requirements.txt

@@ -27,6 +27,8 @@ nuitka==2.5.4
 
 # Creating XML unit test reports
 unittest-xml-reporting==3.2.0
+# Feed parameters to tests neatly
+parameterized==0.9.0 
 
 # Building user documentation
 Markdown==3.7

source/documentationUtils.py

@@ -1,6 +1,6 @@
 # -*- coding: UTF-8 -*-
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2006-2023 NV Access Limited, Łukasz Golonka
+# Copyright (C) 2006-2024 NV Access Limited, Łukasz Golonka
 # This file may be used under the terms of the GNU General Public License, version 2 or later.
 # For more details see: https://www.gnu.org/licenses/gpl-2.0.html
 
@@ -13,7 +13,6 @@
 from logHandler import log
 import ui
 import queueHandler
-from gui.message import messageBox
 import wx
 
 
@@ -65,6 +64,9 @@ def reportNoDocumentation(fileName: str, useMsgBox: bool = False) -> None:
 		f"Documentation not found ({fileName}): possible cause - running from source without building user docs.",
 	)
 	if useMsgBox:
+		# Import late to avoid circular impoort.
+		from gui.message import messageBox
+
 		messageBox(
 			noDocMessage,
 			# Translators: the title of an error message dialog

source/gui/__init__.py

@@ -5,8 +5,10 @@
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
+from collections.abc import Callable
 import os
 import ctypes
+import warnings
 import wx
 import wx.adv
 
@@ -30,6 +32,8 @@
 	# messageBox is accessed through `gui.messageBox` as opposed to `gui.message.messageBox` throughout NVDA,
 	# be cautious when removing
 	messageBox,
+	MessageDialog,
+	displayDialogAsModal,
 )
 from . import blockAction
 from .speechDict import (
@@ -285,7 +289,7 @@ def onExecuteUpdateCommand(self, evt):
 					apiVersion=apiVersion,
 					backCompatTo=backCompatToAPIVersion,
 				)
-				runScriptModalDialog(confirmUpdateDialog)
+				runScriptModalDialog(confirmUpdateDialog, confirmUpdateDialog.callback)
 			else:
 				updateCheck.executePendingUpdate()
 
@@ -367,7 +371,7 @@ def onInputGesturesCommand(self, evt):
 
 	def onAboutCommand(self, evt):
 		# Translators: The title of the dialog to show about info for NVDA.
-		messageBox(versionInfo.aboutMessage, _("About NVDA"), wx.OK)
+		MessageDialog(None, versionInfo.aboutMessage, _("About NVDA")).Show()
 
 	@blockAction.when(blockAction.Context.SECURE_MODE)
 	def onCheckForUpdateCommand(self, evt):
@@ -878,21 +882,24 @@ def showGui():
 	wx.CallAfter(mainFrame.showGui)
 
 
-def runScriptModalDialog(dialog, callback=None):
+def runScriptModalDialog(dialog: wx.Dialog, callback: Callable[[int], Any] | None = None):
 	"""Run a modal dialog from a script.
-	This will not block the caller,
-	but will instead call C{callback} (if provided) with the result from the dialog.
+	This will not block the caller, but will instead call callback (if provided) with the result from the dialog.
 	The dialog will be destroyed once the callback has returned.
-	@param dialog: The dialog to show.
-	@type dialog: C{wx.Dialog}
-	@param callback: The optional callable to call with the result from the dialog.
-	@type callback: callable
+
+	This function is deprecated.
+	Use :class:`message.MessageDialog` instead.
+
+	:param dialog: The dialog to show.
+	:param callback: The optional callable to call with the result from the dialog.
 	"""
+	warnings.warn(
+		"showScriptModalDialog is deprecated. Use an instance of message.MessageDialog and wx.CallAfter instead.",
+		DeprecationWarning,
+	)
 
 	def run():
-		mainFrame.prePopup()
-		res = dialog.ShowModal()
-		mainFrame.postPopup()
+		res = displayDialogAsModal(dialog)
 		if callback:
 			callback(res)
 		dialog.Destroy()