From 58afde60ad05d8802fc083c75bfc60cc09fcd77b Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Sat, 4 May 2024 13:16:12 +0200 Subject: [PATCH] Clarify public-ness of some ToolContainerBase APIs. add_toolitem is clearly intended as a helper for add_tool (add_tool sets up a bunch of auxiliary arguments for it which the end-user should not bother with). toggle_toolitem and remove_toolitem also look internal-ish. Document them as such. --- lib/matplotlib/backend_bases.py | 34 ++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py index e90c110c193b..851e678ea697 100644 --- a/lib/matplotlib/backend_bases.py +++ b/lib/matplotlib/backend_bases.py @@ -3388,11 +3388,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 @@ -3418,7 +3424,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 ---------- @@ -3431,11 +3446,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 ----------