Refactor COM Registration Fixing Tool part 2: remove bugs, return Windows errors, improve UX

source/gui/__init__.py

@@ -37,6 +37,7 @@
 	VoiceDictionaryDialog,
 	TemporaryDictionaryDialog,
 )
+from .utilityDialogs import ContinueCancelDialog
 
 # ExitDialog is accessed through `import gui.ExitDialog` as opposed to `gui.exit.ExitDialog`.
 # Be careful when removing, and only do in a compatibility breaking release.
@@ -483,49 +484,90 @@ def onInstallCommand(self, evt):
 		blockAction.Context.SECURE_MODE,
 		blockAction.Context.MODAL_DIALOG_OPEN,
 	)
-	def onRunCOMRegistrationFixesCommand(self, evt):
-		if (
-			messageBox(
-				_(
-					# Translators: A message to warn the user when starting the COM Registration Fixing tool
-					"You are about to run the COM Registration Fixing tool. "
-					"This tool will try to fix common system problems that stop NVDA from being able to access content "
-					"in many programs including Firefox and Internet Explorer. "
-					"This tool must make changes to the System registry and therefore requires administrative access. "
-					"Are you sure you wish to proceed?",
-				),
-				# Translators: The title of the warning dialog displayed when launching the COM Registration Fixing tool
-				_("Warning"),
-				wx.YES | wx.NO | wx.ICON_WARNING,
-				self,
-			)
-			== wx.NO
-		):
+	def onRunCOMRegistrationFixesCommand(self, evt) -> None:
+		"""Manages the interactive running of the COM Registration Fixing Tool.
+		Shows a dialog to the user, giving an overview of what is going to happen.
+		If the user chooses to continue: runs the tool, and displays a completion dialog.
+		Cancels the run attempt if the user fails or declines the UAC prompt.
+		"""
+		# Translators: The title of various dialogs displayed when using the COM Registration Fixing tool
+		genericTitle: str = _("Fix COM Registrations")
+		introDialog = ContinueCancelDialog(
+			self,
+			genericTitle,
+			self._CRFTIntroMessage(),
+		)
+		response: int = introDialog.ShowModal()
+		if response == wx.CANCEL:
+			log.debug("Run of COM Registration Fixing Tool canceled before UAC.")
 			return
 		progressDialog = IndeterminateProgressDialog(
 			mainFrame,
-			# Translators: The title of the dialog presented while NVDA is running the COM Registration fixing tool
-			_("COM Registration Fixing Tool"),
+			genericTitle,
 			# Translators: The message displayed while NVDA is running the COM Registration fixing tool
-			_("Please wait while NVDA tries to fix your system's COM registrations."),
+			_("Please wait while NVDA attempts to fix your system's COM registrations..."),
 		)
+		error: str | None = None
 		try:
 			systemUtils.execElevated(config.SLAVE_FILENAME, ["fixCOMRegistrations"])
-		except:  # noqa: E722
+		except WindowsError as e:
+			# 1223 is "The operation was canceled by the user."
+			if e.winerror == 1223:
+				# Same as if the user selected "no" in the initial dialog.
+				log.debug("Run of COM Registration Fixing Tool canceled during UAC.")
+				return
+			else:
+				log.error("Could not execute fixCOMRegistrations command", exc_info=True)
+				error = e  # Hold for later display to the user
+				return  # Safe because of finally block
+		except Exception:
 			log.error("Could not execute fixCOMRegistrations command", exc_info=True)
-		progressDialog.done()
-		del progressDialog
+			return
+		finally:  # Clean up the progress dialog, and display any important error to the user before returning
+			progressDialog.done()
+			del progressDialog
+			self.postPopup()
+			# If there was a Windows error, inform the user because it may have support value
+			if error is not None:
+				messageBox(
+					_(
+						# Translators: message shown to the user on COM Registration Fix fail
+						"The COM Registration Fixing Tool was unsuccessful. This Windows "
+						"error may provide more information.    {}",
+					).format(error),
+					# Translators: Added to the title of the dialog showing the COM Registration Fix failure
+					genericTitle + " " + _("Failed"),
+					wx.OK,
+				)
+		# Display success dialog if there were no errors
 		messageBox(
 			_(
-				# Translators: The message displayed when the COM Registration Fixing tool completes.
-				"The COM Registration Fixing tool has finished. "
+				# Translators: Message shown when the COM Registration Fixing tool completes.
+				"The COM Registration Fixing Tool has completed successfully.\n"
 				"It is highly recommended that you restart your computer now, to make sure the changes take full effect.",
 			),
-			# Translators: The title of a dialog presented when the COM Registration Fixing tool is complete.
-			_("COM Registration Fixing Tool"),
+			genericTitle,
 			wx.OK,
 		)
 
+	def _CRFTIntroMessage(self) -> str:
+		"""Helper that returns the COM Registration Fixing Tool's introductory statement."""
+		return _(
+			# Translators: Explain the COM Registration Fixing tool to users before running
+			"Welcome to the COM Registration Fixing tool.\n"
+			"This tool is used by NVDA to fix problems it may have as it tries to interact with various applications, "
+			"or with Windows itself.\n"
+			"It examines the system registry for corrupted or missing accessibility entries and will correct them.\n"
+			"Those entries are sometimes damaged by installing or uninstalling programs, or other system events. This "
+			'can result in "unknown" or "pane" being spoken instead of the content you were expecting, or previously '
+			"accessible elements suddenly no longer reading correctly.\n\n"
+			"You have most likely been asked to run this tool by NVDA support or a power user trying to assist you.\n"
+			"Because it needs to modify the Windows registry, if you have User Account Control (UAC) active, you will "
+			"be prompted by UAC before this tool can do its job. This is normal and you should answer by pressing the "
+			"yes button.\n\n"
+			"Press Continue to try to repair the registry now.\n",
+		)
+
 	@blockAction.when(blockAction.Context.MODAL_DIALOG_OPEN)
 	def onConfigProfilesCommand(self, evt):
 		self.prePopup()

source/gui/utilityDialogs.py

@@ -0,0 +1,47 @@
+# A part of NonVisual Desktop Access (NVDA)
+# Copyright (C) 2024 NV Access Limited, Luke Davis
+# 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
+
+import wx
+
+from .nvdaControls import MessageDialog
+
+
+class ContinueCancelDialog(MessageDialog):
+	"""
+	This implementation of a `gui.nvdaControls.MessageDialog`, provides `Continue` and `Cancel` buttons as its controls.
+	These serve the same functions as `OK` and `Cancel` in other dialogs, but may be more desirable in some situations.
+	"""
+
+	def __init__(
+		self,
+		parent,
+		title: str,
+		message: str,
+		dialogType: int = MessageDialog.DIALOG_TYPE_STANDARD,
+		continueByDefault: bool = True,
+	) -> None:
+		"""Creates a ContinueCancelDialog MessageDialog.
+
+		:param parent: The parent window for the dialog, usually `gui.mainFrame`.
+		:param title: The title or caption of the dialog.
+		:param message: The message to be shown in the dialog.
+		:param dialogType: One of the dialog type constants from MessageDialog, defaults to standard.
+		:param continueByDefault: Whether the Continue button should be the one wx sets as default, defaults to True.
+		"""
+		self.continueByDefault: bool = continueByDefault
+		super().__init__(parent, title, message, dialogType)
+
+	def _addButtons(self, buttonHelper) -> None:
+		"""Override to add Continue and Cancel buttons."""
+		# Translators: The label for the Continue button in an NVDA dialog.
+		continueButton = buttonHelper.addButton(self, id=wx.ID_OK, label=_("&Continue"))
+		continueButton.Bind(wx.EVT_BUTTON, lambda evt: self.EndModal(wx.OK))
+		# Translators: The label for the Cancel button in an NVDA dialog.
+		cancelButton = buttonHelper.addButton(self, id=wx.ID_CANCEL, label=_("Cancel"))
+		cancelButton.Bind(wx.EVT_BUTTON, lambda evt: self.EndModal(wx.CANCEL))
+		if self.continueByDefault:
+			continueButton.SetDefault()
+		else:
+			cancelButton.SetDefault()

user_docs/en/changes.md

@@ -16,13 +16,18 @@ In order to use this feature, the application volume adjuster needs to be enable
 
 * The Report link destination, Character formatting information, and Speak selection dialogs, now include "Close" and "Copy" buttons for user convenience. (#17018, @XLTechie)
 * The exit dialog now allows you to restart NVDA with add-ons disabled and debug logging enabled simultaneously. (#11538, @CyrilleB79)r
+* Changes to the COM Registration Fixing Tool: (#12355, @XLTechie)
+  * It will now show a message to the user, including the error, in the rare event of a Windows error while attempting COM re-registrations.
+  * It now starts with a more user friendly explanation of its purpose, instead of a warning. (#12351, @XLTechie, @britechguy)
+  * The initial window can now be exited with `escape` or `alt+f4`. (#10799, @XLTechie)
 
 ### Bug Fixes
 
 * Native support for the Dot Pad tactile graphics device from Dot Inc as a multiline braille display. (#17007)
 * Improvements when editing in Microsoft PowerPoint:
   * Caret reporting no longer breaks when text contains wide characters, such as emoji. (#17006 , @LeonarddeR)
   * Character location reporting is now accurate (e.g. when pressing `NVDA+Delete`. (#9941, @LeonarddeR)
+* The COM Registration Fixing Tool no longer reports success on failure. (#12355, @XLTechie)
 
 ### Changes for Developers
 
@@ -34,6 +39,7 @@ Add-ons will need to be re-tested and have their manifest updated.
   * Updated Ruff to 0.6.3. (#17102)
   * Updated Comtypes to 1.4.6. (#17061, @LeonarddeR)
 * `ui.browseableMessage` may now be called with options to present a button for copying to clipboard, and/or a button for closing the window. (#17018, @XLTechie)
+* There is a new `gui.utilityDialogs.ContinueCancelDialog`, for producing simple dialogs with Continue and Cancel buttons. (#12355, @XLTechie)
 
 #### API Breaking Changes