From f437723806b9350bf0b91fbc2954ca38df950fe7 Mon Sep 17 00:00:00 2001
From: Sascha Cowley <16543535+SaschaCowley@users.noreply.github.com>
Date: Wed, 18 Dec 2024 17:28:09 +1100
Subject: [PATCH] Added notes on thread safety

---
 projectDocs/dev/developerGuide/developerGuide.md | 5 +++--
 source/gui/message.py                            | 8 ++++++++
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/projectDocs/dev/developerGuide/developerGuide.md b/projectDocs/dev/developerGuide/developerGuide.md
index dcc93437dd..be23ea20c4 100644
--- a/projectDocs/dev/developerGuide/developerGuide.md
+++ b/projectDocs/dev/developerGuide/developerGuide.md
@@ -1666,8 +1666,9 @@ If none of the standard `ReturnCode` values are suitable for your button, you ma
 
 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.
-The following convenience class methods are provided:
+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 |
 |---|---|---|
diff --git a/source/gui/message.py b/source/gui/message.py
index 9ac71743cf..d38c2c746d 100644
--- a/source/gui/message.py
+++ b/source/gui/message.py
@@ -359,6 +359,8 @@ class MessageDialog(DpiScalingHelperMixinWithoutInit, wx.Dialog, metaclass=SIPAB
 	Mixing and matching both patterns is also allowed.
 
 	When subclassing this class, you can override `_addButtons` and `_addContents` to insert custom buttons or contents that you want your subclass to always have.
+
+	.. warning:: Unless noted otherwise, the message dialog API is **not** thread safe.
 	"""
 
 	_instances: deque["MessageDialog"] = deque()
@@ -782,6 +784,8 @@ def alert(
 	):
 		"""Display a blocking dialog with an OK button.
 
+		.. note:: This method is thread safe.
+
 		:param message: The message to be displayed in the alert dialog.
 		:param caption: The caption of the alert dialog, defaults to wx.MessageBoxCaptionStr.
 		:param parent: The parent window of the alert dialog, defaults to None.
@@ -808,6 +812,8 @@ def confirm(
 	) -> Literal[ReturnCode.OK, ReturnCode.CANCEL]:
 		"""Display a confirmation dialog with OK and Cancel buttons.
 
+		.. note:: This method is thread safe.
+
 		:param message: The message to be displayed in the dialog.
 		:param caption: The caption of the dialog window, defaults to wx.MessageBoxCaptionStr.
 		:param parent: The parent window for the dialog, defaults to None.
@@ -838,6 +844,8 @@ def ask(
 	) -> Literal[ReturnCode.YES, ReturnCode.NO, ReturnCode.CANCEL]:
 		"""Display a query dialog with Yes, No, and Cancel buttons.
 
+		.. note:: This method is thread safe.
+
 		:param message: The message to be displayed in the dialog.
 		:param caption: The title of the dialog window, defaults to wx.MessageBoxCaptionStr.
 		:param parent: The parent window for the dialog, defaults to None.