Merge pull request #28169 from anntzer/tcp

timhoffm · web-flow · commit 9387431ab6ff · 2024-05-06T00:07:26.000+02:00
Clarify public-ness of some ToolContainerBase APIs.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -3395,11 +3395,17 @@ def trigger_tool(self, name):
 
     def add_toolitem(self, name, group, position, image, description, toggle):
         """
-        Add a toolitem to the container.
+        A hook to add a toolitem to the container.
 
-        This method must be implemented per backend.
+        This hook must be implemented in each backend and contains the
+        backend-specific code to add an element to the toolbar.
 
-        The callback associated with the button click event,
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolContainerBase.add_tool`.
+
+        The callback associated with the button click event
         must be *exactly* ``self.trigger_tool(name)``.
 
         Parameters
@@ -3425,7 +3431,16 @@ def add_toolitem(self, name, group, position, image, description, toggle):
 
     def toggle_toolitem(self, name, toggled):
         """
-        Toggle the toolitem without firing event.
+        A hook to toggle a toolitem without firing an event.
+
+        This hook must be implemented in each backend and contains the
+        backend-specific code to silently toggle a toolbar element.
+
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolManager.trigger_tool` or `.ToolContainerBase.trigger_tool`
+            (which are equivalent).
 
         Parameters
         ----------
@@ -3438,11 +3453,16 @@ def toggle_toolitem(self, name, toggled):
 
     def remove_toolitem(self, name):
         """
-        Remove a toolitem from the `ToolContainer`.
+        A hook to remove a toolitem from the container.
 
-        This method must get implemented per backend.
+        This hook must be implemented in each backend and contains the
+        backend-specific code to remove an element from the toolbar; it is
+        called when `.ToolManager` emits a `tool_removed_event`.
 
-        Called when `.ToolManager` emits a `tool_removed_event`.
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolManager.remove_tool`.
 
         Parameters
         ----------
