Skip to content

Commit 689aff0

Browse files
jasonliw93jasonliw93
committed
Merge branch 'master' of https://github.com/matplotlib/matplotlib into Issue2841
2 parents e112aef + f532615 commit 689aff0

39 files changed

+3081
-38
lines changed

‎doc/devel/MEP/MEP08.rst

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
============
2+
MEP8: PEP8
3+
============
4+
5+
.. contents::
6+
:local:
7+
8+
9+
Status
10+
======
11+
12+
**Discussion**
13+
14+
Branches and Pull requests
15+
==========================
16+
17+
None so far.
18+
19+
Abstract
20+
========
21+
22+
The matplotlib codebase predates PEP8, and therefore is less than
23+
consistent style-wise in some areas. Bringing the codebase into
24+
compliance with PEP8 would go a long way to improving its legibility.
25+
26+
Detailed description
27+
====================
28+
29+
Some files use four space indentation, some use three. Some use
30+
different levels in the same file.
31+
32+
For the most part, class/function/variable naming follows PEP8, but it
33+
wouldn't hurt to fix where necessary.
34+
35+
Implementation
36+
==============
37+
38+
The implementation should be fairly mechanical: running the pep8 tool
39+
over the code and fixing where appropriate.
40+
41+
This should be merged in after the 2.0 release, since the changes will
42+
likely make merging any pending pull requests more difficult.
43+
44+
Additionally, and optionally, PEP8 compliance could be tracked by an
45+
automated build system.
46+
47+
Backward compatibility
48+
======================
49+
50+
Public names of classes and functions that require change (there
51+
shouldn't be many of these) should first be deprecated and then
52+
removed in the next release cycle.
53+
54+
Alternatives
55+
============
56+
57+
PEP8 is a popular standard for Python code style, blessed by the
58+
Python core developers, making any alternatives less desirable.

‎doc/devel/MEP/MEP09.rst

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
==================================
2+
MEP9: Global interaction manager
3+
==================================
4+
5+
.. contents::
6+
:local:
7+
8+
Add a global manager for all user interactivity with artists; make any
9+
artist resizeable, moveable, highlightable, and selectable as desired
10+
by the user.
11+
12+
Status
13+
======
14+
**Discussion**
15+
16+
Branches and Pull requests
17+
==========================
18+
https://github.com/dhyams/matplotlib/tree/MEP9
19+
20+
Abstract
21+
========
22+
23+
The goal is to be able to interact with matplotlib artists in a very
24+
similar way as drawing programs do. When appropriate, the user should
25+
be able to move, resize, or select an artist that is already on the
26+
canvas. Of course, the script writer is ultimately in control of
27+
whether an artist is able to be interacted with, or whether it is
28+
static.
29+
30+
This code to do this has already been privately implemented and
31+
tested, and would need to be migrated from its current "mixin"
32+
implementation, to a bona-fide part of matplotlib.
33+
34+
The end result would be to have four new keywords available to
35+
matplotlib.artist.Artist: _moveable_, _resizeable_, _selectable_, and
36+
_highlightable_. Setting any one of these keywords to True would
37+
activate interactivity for that artist.
38+
39+
In effect, this MEP is a logical extension of event handling in
40+
matplotlib; matplotlib already supports "low level" interactions like
41+
left mouse presses, a key press, or similar. The MEP extends the
42+
support to the logical level, where callbacks are performed on the
43+
artists when certain interactive gestures from the user are detected.
44+
45+
Detailed description
46+
====================
47+
48+
This new functionality would be used to allow the end-user to better
49+
interact with the graph. Many times, a graph is almost what the user
50+
wants, but a small repositioning and/or resizing of components is
51+
necessary. Rather than force the user to go back to the script to
52+
trial-and-error the location, and simple drag and drop would be
53+
appropriate.
54+
55+
Also, this would better support applications that use matplotlib;
56+
here, the end-user has no reasonable access or desire to edit the
57+
underlying source in order to fine-tune a plot. Here, if matplotlib
58+
offered the capability, one could move or resize artists on the canvas
59+
to suit their needs. Also, the user should be able to highlight (with
60+
a mouse over) an artist, and select it with a double-click, if the
61+
application supports that sort of thing. In this MEP, we also want to
62+
support the highlighting and selection natively; it is up to
63+
application to handle what happens when the artist is selected. A
64+
typical handling would be to display a dialog to edit the properties
65+
of the artist.
66+
67+
In the future, as well (this is not part of this MEP), matplotlib
68+
could offer backend-specific property dialogs for each artist, which
69+
are raised on artist selection. This MEP would be a necessary
70+
stepping stone for that sort of capability.
71+
72+
There are currently a few interactive capabilities in matplotlib
73+
(e.g. legend.draggable()), but they tend to be scattered and are not
74+
available for all artists. This MEP seeks to unify the interactive
75+
interface and make it work for all artists.
76+
77+
The current MEP also includes grab handles for resizing artists, and
78+
appropriate boxes drawn when artists are moved or resized.
79+
80+
Implementation
81+
==============
82+
* Add appropriate methods to the "tree" of artists so that the
83+
interactivity manager has a consistent interface for the
84+
interactivity manager to deal with. The proposed methods to add to
85+
the artists, if they are to support interactivity, are:
86+
87+
* get_pixel_position_ll(self): get the pixel position of the lower
88+
left corner of the artist's bounding box
89+
* get_pixel_size(self): get the size of the artist's bounding box,
90+
in pixels
91+
* set_pixel_position_and_size(self,x,y,dx,dy): set the new size of
92+
the artist, such that it fits within the specified bounding box.
93+
94+
* add capability to the backends to 1) provide cursors, since these
95+
are needed for visual indication of moving/resizing, and 2) provide
96+
a function that gets the current mouse position
97+
* Implement the manager. This has already been done privately (by
98+
dhyams) as a mixin, and has been tested quite a bit. The goal would
99+
be to move the functionality of the manager into the artists so that
100+
it is in matplotlib properly, and not as a "monkey patch" as I
101+
currently have it coded.
102+
103+
104+
105+
Current summary of the mixin
106+
============================
107+
108+
(Note that this mixin is for now just private code, but can be added
109+
to a branch obviously)
110+
111+
InteractiveArtistMixin:
112+
113+
Mixin class to make any generic object that is drawn on a matplotlib
114+
canvas moveable and possibly resizeable. The Powerpoint model is
115+
followed as closely as possible; not because I'm enamoured with
116+
Powerpoint, but because that's what most people understand. An artist
117+
can also be selectable, which means that the artist will receive the
118+
on_activated() callback when double clicked. Finally, an artist can
119+
be highlightable, which means that a highlight is drawn on the artist
120+
whenever the mouse passes over. Typically, highlightable artists will
121+
also be selectable, but that is left up to the user. So, basically
122+
there are four attributes that can be set by the user on a per-artist
123+
basis:
124+
125+
* highlightable
126+
* selectable
127+
* moveable
128+
* resizeable
129+
130+
To be moveable (draggable) or resizeable, the object that is the
131+
target of the mixin must support the following protocols:
132+
133+
* get_pixel_position_ll(self)
134+
* get_pixel_size(self)
135+
* set_pixel_position_and_size(self,x,y,sx,sy)
136+
137+
Note that nonresizeable objects are free to ignore the sx and sy
138+
parameters. To be highlightable, the object that is the target of the
139+
mixin must also support the following protocol:
140+
141+
* get_highlight(self)
142+
143+
Which returns a list of artists that will be used to draw the highlight.
144+
145+
If the object that is the target of the mixin is not an matplotlib
146+
artist, the following protocols must also be implemented. Doing so is
147+
usually fairly trivial, as there has to be an artist *somewhere* that
148+
is being drawn. Typically your object would just route these calls to
149+
that artist.
150+
151+
* get_figure(self)
152+
* get_axes(self)
153+
* contains(self,event)
154+
* set_animated(self,flag)
155+
* draw(self,renderer)
156+
* get_visible(self)
157+
158+
The following notifications are called on the artist, and the artist
159+
can optionally implement these.
160+
161+
* on_select_begin(self)
162+
* on_select_end(self)
163+
* on_drag_begin(self)
164+
* on_drag_end(self)
165+
* on_activated(self)
166+
* on_highlight(self)
167+
* on_right_click(self,event)
168+
* on_left_click(self,event)
169+
* on_middle_click(self,event)
170+
* on_context_click(self,event)
171+
* on_key_up(self,event)
172+
* on_key_down(self,event)
173+
174+
The following notifications are called on the canvas, if no
175+
interactive artist handles the event:
176+
177+
* on_press(self,event)
178+
* on_left_click(self,event)
179+
* on_middle_click(self,event)
180+
* on_right_click(self,event)
181+
* on_context_click(self,event)
182+
* on_key_up(self,event)
183+
* on_key_down(self,event)
184+
185+
The following functions, if present, can be used to modify the
186+
behavior of the interactive object:
187+
188+
* press_filter(self,event) # determines if the object wants to have
189+
the press event routed to it
190+
* handle_unpicked_cursor() # can be used by the object to set a cursor
191+
as the cursor passes over the object when it is unpicked.
192+
193+
Supports multiple canvases, maintaining a drag lock, motion notifier,
194+
and a global "enabled" flag per canvas. Supports fixed aspect ratio
195+
resizings by holding the shift key during the resize.
196+
197+
Known problems:
198+
199+
* Zorder is not obeyed during the selection/drag operations. Because
200+
of the blit technique used, I do not believe this can be fixed. The
201+
only way I can think of is to search for all artists that have a
202+
zorder greater then me, set them all to animated, and then redraw
203+
them all on top during each drag refresh. This might be very slow;
204+
need to try.
205+
* the mixin only works for wx backends because of two things: 1) the
206+
cursors are hardcoded, and 2) there is a call to
207+
wx.GetMousePosition() Both of these shortcomings are reasonably
208+
fixed by having each backend supply these things.
209+
210+
Backward compatibility
211+
======================
212+
213+
No problems with backward compatibility, although once this is in
214+
place, it would be appropriate to obsolete some of the existing
215+
interactive functions (like legend.draggable())
216+
217+
Alternatives
218+
============
219+
220+
None that I know of.

0 commit comments

Comments
 (0)