diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py index d7430a4494fd..740c01226f7d 100644 --- 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 ----------