MEP22: Toolbar rewrite#
The main goal of this MEP is to make it easier to modify (add, change, remove) the way the user interacts with the figures.
The user interaction with the figure is deeply integrated within the Canvas and Toolbar. Making extremely difficult to do any modification.
This MEP proposes the separation of this interaction into Toolbar, Navigation and Tools to provide independent access and reconfiguration.
This approach will make easier to create and share tools among
users. In the far future, we can even foresee a kind of Marketplace
Tools where the most popular can be added into the main
The reconfiguration of the Toolbar is complex, most of the time it requires a custom backend.
The creation of custom Tools sometimes interferes with the Toolbar, as example see matplotlib/matplotlib#2694 also the shortcuts are hardcoded and again not easily modifiable matplotlib/matplotlib#2699
The proposed solution is to take the actions out of the
Toolbar and the
shortcuts out of the
Canvas. The actions and shortcuts will be in the form
A new class
Navigation will be the bridge between the events from the
Toolbar and redirect them to the appropriate
At the end the user interaction will be divided into three classes:
NavigationBase: This class is instantiated for each FigureManager and connect the all user interactions with the Tools
ToolbarBase: This existing class is relegated only as a GUI access to Tools.
ToolBase: Is the basic definition of Tools.
Tools can have a graphical representation as the
SubplotTool or not even be
present in the Toolbar as
ToolBase has the following class attributes for configuration at definition time
keymap = None: Key(s) to be used to trigger the tool
description = '': Small description of the tool
image = None: Image that is used in the toolbar
The following instance attributes are set at instantiation:
trigger(self, event): This is the main method of the Tool, it is called when the Tool is triggered by:
Toolbar button click
keypress associated with the Tool Keymap
Call to navigation.trigger_tool(name)
set_figure(self, figure): Set the figure and navigation attributes
destroy(self, *args): Destroy the
Toolgraphical interface (if exists)
ToolToggleBase has the following class attributes for
configuration at definition time
radio_group = None: Attribute to group 'radio' like tools (mutually exclusive)
cursor = None: Cursor to use when the tool is active
The Toggleable Tools, can capture keypress, mouse moves, and mouse button press
enable(self, event): Called by
disable(self, event): Called when the tool is untoggled
toggled: Property True or False
add_toolitem(self, name, group, position, image, description, toggle): Add a toolitem to the toolbar. This method is a callback from
tool_added_event(emitted by navigation)
set_message(self, s): Display a message on toolbar or in status bar
toggle_toolitem(self, name): Toggle the toolitem without firing event.
remove_toolitem(self, name): Remove a toolitem from the
For backward compatibility added 'navigation' to the list of values
'toolbar2'), that is used for
instantiation instead of the NavigationToolbar classes
With this parameter, it makes it transparent to anyone using the existing backends.
[@pelson comment: This also gives us an opportunity to avoid needing to implement all of this in the same PR - some backends can potentially exist without the new functionality for a short while (but it must be done at some point).]