10000 DOC : move MEP22 · caspervdw/matplotlib@34263c1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 34263c1

Browse files
tacaswelltacaswell
committed
DOC : move MEP22
1 parent 06a0e8e commit 34263c1

File tree

2 files changed

+194
-0
lines changed

2 files changed

+194
-0
lines changed

‎doc/devel/MEP/MEP22.rst

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
========================
2+
MEP22: Toolbar rewrite
3+
========================
4+
5+
.. contents::
6+
:local:
7+
8+
Status
9+
======
10+
**Progress**
11+
12+
13+
Branches and Pull requests
14+
==========================
15+
16+
Previous work
17+
* https://github.com/matplotlib/matplotlib/pull/1849
18+
* https://github.com/matplotlib/matplotlib/pull/2557
19+
* https://github.com/matplotlib/matplotlib/pull/2465
20+
21+
Pull Requests:
22+
* Removing the NavigationToolbar classes
23+
https://github.com/matplotlib/matplotlib/pull/2740 **CLOSED**
24+
* Keeping the NavigationToolbar classes https://github.com/matplotlib/matplotlib/pull/2759 **CLOSED**
25+
* Navigation by events: https://github.com/matplotlib/matplotlib/pull/3652
26+
27+
Abstract
28+
========
29+
30+
The main goal of this MEP is to make it easier to modify (add, change,
31+
remove) the way the user interacts with the figures.
32+
33+
The user interaction with the figure is deeply integrated within the
34+
Canvas and Toolbar. Making extremely difficult to do any modification.
35+
36+
This MEP proposes the separation of this interaction into Toolbar,
37+
Navigation and Tools to provide independent access and
38+
reconfiguration.
39+
40+
This approach will make easier to create and share tools among
41+
users. In the far future, we can even foresee a kind of Marketplace
42+
for `Tools` where the most popular can be added into the main
43+
distribution.
44+
45+
Detailed description
46+
====================
47+
48+
The reconfiguration of the Toolbar is complex, most of the time it
49+
requires a custom backend.
50+
51+
The creation of custom Tools sometimes interferes with the Toolbar, as
52+
example see https://github.com/matplotlib/matplotlib/issues/2694 also
53+
the shortcuts are hardcoded and again not easily modifiable
54+
https://github.com/matplotlib/matplotlib/issues/2699
55+
56+
The proposed solution is to take the actions out of the `Toolbar` and
57+
the shortcuts out of the `Canvas`. This actions and shortcuts will be
58+
in the form of `Tools`.
59+
60+
A new class `Navigation` will be the bridge between the events from
61+
the `Canvas` and `Toolbar` and redirect them to the appropiate `Tool`.
62+
63+
At the end the user interaction will be divided into three classes:
64+
65+
* NavigationBase: This class is instantiated for each FigureManager
66+
and connect the all user interactions with the Tools
67+
* ToolbarBase: This existing class is relegated only as a GUI access
68+
to Tools.
69+
* ToolBase: Is the basic definition of Tools.
70+
71+
72+
Implementation
73+
==============
74+
75+
ToolBase(object)
76+
----------------
77+
78+
Tools can have a graphical representation as the `SubplotTool` or not even be present in the Toolbar as `Quit`
79+
80+
The `ToolBase` has the following class attributes for configuration at definition time
81+
82+
* keymap = None: Key(s) to be used to trigger the tool
83+
* description = '': Small description of the tool
84+
* image = None: Image that is used in the toolbar
85+
86+
The following instance attributes are set at instantiation:
87+
* name
88+
* navigation
89+
90+
**Methods**
91+
* trigger(self, event): This is the main method of the Tool, it is called when the Tool is triggered by:
92+
* Toolbar button click
93+
* keypress associated with the Tool Keymap
94+
* Call to navigation.trigger_tool(name)
95+
* set_figure(self, figure): Set the figure and navigation attributes
96+
* destroy(self, *args): Destroy the `Tool` graphical interface (if exists)
97+
98+
**Available Tools**
99+
* ToolQuit
100+
* ToolEnableAllNavigation
101+
* ToolEnableNavigation
102+
* ToolToggleGrid
103+
* ToolToggleFullScreen
104+
* ToolToggleYScale
105+
* ToolToggleXScale
106+
* ToolHome
107+
* ToolBack
108+
* ToolForward
109+
* SaveFigureBase
110+
* ConfigureSubplotsBase
111+
112+
113+
ToolToggleBase(ToolBase)
114+
------------------------
115+
116+
The `ToolToggleBase` has the following class attributes for
117+
configuration at definition time
118+
119+
* radio_group = None: Attribute to group 'radio' like tools (mutually
120+
exclusive)
121+
* cursor = None: Cursor to use when the tool is active
122+
123+
The **Toggleable** Tools, can capture keypress, mouse moves, and mouse
124+
button press
125+
126+
It defines the following methods
127+
* enable(self, event): Called by `ToolToggleBase.trigger` method
128+
* disable(self, event): Called when the tool is untoggled
129+
* toggled : **Property** True or False
130+
131+
**Available Tools**
132+
* ToolZoom
133+
* ToolPan
134+
135+
NavigationBase
136+
--------------
137+
138+
Defines the following attributes
139+
* canvas:
140+
* keypresslock: Lock to know if the `canvas` key_press_event` is
141+
available and process it
142+
* messagelock: Lock to know if the message is available to write
143+
144+
Public methods for **User use**:
145+
* nav_connect(self, s, func): Connect to to navigation for events
146+
* nav_disconnect(self, cid): Disconnect from navigation event
147+
* message_event(self, message, sender=None): Emit a
148+
tool_message_event event
149+
* active_toggle(self): **Property** The currently toggled tools or
150+
None
151+
* get_tool_keymap(self, name): Return a list of keys that are
152+
associated with the tool
153+
* set_tool_keymap(self, name, *keys): Set the keys for the given tool
154+
* remove_tool(self, name): Removes tool from the navigation control.
155+
* add_tools(self, tools): Add multiple tools to `Navigation`
156+
* add_tool(self, name, tool, group=None, position=None): Add a tool
157+
to the Navigation
158+
* tool_trigger_event(self, name, sender=None, canvasevent=None,
159+
data=None): Trigger a tool and fire the event
160+
161+
* tools(self) **Property**: Return a dict with available tools with
162+
corresponding keymaps, descriptions and objects
163+
* get_tool(self, name): Return the tool object
164+
165+
166+
167+
ToolbarBase
168+
-----------
169+
170+
Methods for **Backend implementation**
171+
* add_toolitem(self, name, group, position, image, description,
172+
toggle): Add a toolitem to the toolbar. This method is a callback
173+
from `tool_added_event` (emited by navigation)
174+
* set_message(self, s): Display a message on toolbar or in status bar
175+
* toggle_toolitem(self, name): Toggle the toolitem without firing
176+
event.
177+
* remove_toolitem(self, name): Remove a toolitem from the `Toolbar`
178+
179+
180+
Backward compatibility
181+
======================
182+
183+
For backward compatibility added a 'navigation' key to
184+
`rcsetup.validate_toolbar`, that is used for Navigation classes
185+
instantiation instead of the NavigationToolbar classes
186+
187+
With this parameter, it makes it transparent to anyone using the
188+
existing backends.
189+
190+
[@pelson comment: This also gives us an opportunity to avoid needing
191+
to implement all of this in the same PR - some backends can
192+
potentially exist without the new functionality for a short while (but
193+
it must be done at some point).]

‎doc/devel/MEP/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,5 @@ Matplotlib Enhancement Proposals
2323
MEP15
2424
MEP19
2525
MEP21
26+
MEP22
2627
MEP25

0 commit comments

Comments
 (0)
0