1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
========================
MEP22: Toolbar rewrite
========================
.. contents::
:local:
Status
======
**Progress**
Branches and Pull requests
==========================
Previous work:
* https://github.com/matplotlib/matplotlib/pull/1849
* https://github.com/matplotlib/matplotlib/pull/2557
* https://github.com/matplotlib/matplotlib/pull/2465
Pull Requests:
* Removing the NavigationToolbar classes
https://github.com/matplotlib/matplotlib/pull/2740 **CLOSED**
* Keeping the NavigationToolbar classes https://github.com/matplotlib/matplotlib/pull/2759 **CLOSED**
* Navigation by events: https://github.com/matplotlib/matplotlib/pull/3652
Abstract
========
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
for ``Tool``\s where the most popular can be added into the main
distribution.
Detailed description
====================
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 https://github.com/matplotlib/matplotlib/issues/2694 also
the shortcuts are hardcoded and again not easily modifiable
https://github.com/matplotlib/matplotlib/issues/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
of ``Tool``\s.
A new class ``Navigation`` will be the bridge between the events from the
``Canvas`` and ``Toolbar`` and redirect them to the appropriate ``Tool``.
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.
Implementation
==============
ToolBase(object)
----------------
Tools can have a graphical representation as the ``SubplotTool`` or not even be
present in the Toolbar as ``Quit``.
The `.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:
* name
* navigation
Methods
~~~~~~~
* ``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 ``Tool`` graphical interface (if
exists)
Available Tools
~~~~~~~~~~~~~~~
* ToolQuit
* ToolEnableAllNavigation
* ToolEnableNavigation
* ToolToggleGrid
* ToolToggleFullScreen
* ToolToggleYScale
* ToolToggleXScale
* ToolHome
* ToolBack
* ToolForward
* SaveFigureBase
* ConfigureSubplotsBase
ToolToggleBase(ToolBase)
------------------------
The `.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
Methods
~~~~~~~
* ``enable(self, event)``: Called by `.ToolToggleBase.trigger` method
* ``disable(self, event)``: Called when the tool is untoggled
* ``toggled``: **Property** True or False
Available Tools
~~~~~~~~~~~~~~~
* ToolZoom
* ToolPan
NavigationBase
--------------
Defines the following attributes:
* canvas:
* keypresslock: Lock to know if the ``canvas`` ``key_press_event`` is
available and process it
* messagelock: Lock to know if the message is available to write
Methods (intended for the end user)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ``nav_connect(self, s, func)``: Connect to navigation for events
* ``nav_disconnect(self, cid)``: Disconnect from navigation event
* ``message_event(self, message, sender=None)``: Emit a
tool_message_event event
* ``active_toggle(self)``: **Property** The currently toggled tools or
None
* ``get_tool_keymap(self, name)``: Return a list of keys that are
associated with the tool
* ``set_tool_keymap(self, name, ``*keys``)``: Set the keys for the given tool
* ``remove_tool(self, name)``: Removes tool from the navigation control.
* ``add_tools(self, tools)``: Add multiple tools to ``Navigation``
* ``add_tool(self, name, tool, group=None, position=None)``: Add a tool
to the ``Navigation``
* ``tool_trigger_event(self, name, sender=None, canvasevent=None,
data=None)``: Trigger a tool and fire the event
* ``tools``: **Property** A dict with available tools with
corresponding keymaps, descriptions and objects
* ``get_tool(self, name)``: Return the tool object
ToolbarBase
-----------
Methods (for backend implementation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ``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 ``Toolbar``
Backward compatibility
======================
For backward compatibility added 'navigation' to the list of values
supported by :rc:`toolbar`, that is used for ``Navigation`` classes
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).]
|
