Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 9eece50

Browse filesBrowse files
timhoffmtimhoffm
authored
Merge pull request #14525 from timhoffm/doc-offsetbox
improve documentation of OffsetBox
2 parents 569204b + 4de7705 commit 9eece50
Copy full SHA for 9eece50

File tree

Expand file treeCollapse file tree

2 files changed

+145
-75
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+145
-75
lines changed

‎lib/matplotlib/axes/_base.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_base.py
+3Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2428,6 +2428,7 @@ def autoscale_view(self, tight=None, scalex=True, scaley=True):
24282428
case, use :meth:`matplotlib.axes.Axes.relim` prior to calling
24292429
autoscale_view.
24302430
"""
2431+
print('asv', scalex, scaley)
24312432
if tight is not None:
24322433
self._tight = bool(tight)
24332434

@@ -2447,7 +2448,9 @@ def autoscale_view(self, tight=None, scalex=True, scaley=True):
24472448
def handle_single_axis(scale, autoscaleon, shared_axes, interval,
24482449
minpos, axis, margin, stickies, set_bound):
24492450

2451+
print('handle', axis, scale)
24502452
if not (scale and autoscaleon):
2453+
print('nothing to do')
24512454
return # nothing to do...
24522455

24532456
shared = shared_axes.get_siblings(self)

‎lib/matplotlib/offsetbox.py

Copy file name to clipboardExpand all lines: lib/matplotlib/offsetbox.py
+142-75Lines changed: 142 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -147,9 +147,11 @@ def __init__(self, *args, **kwargs):
147147

148148
def set_figure(self, fig):
149149
"""
150-
Set the figure
150+
Set the `.Figure` for the `.OffsetBox` and all its children.
151151
152-
accepts a class:`~matplotlib.figure.Figure` instance
152+
Parameters
153+
----------
154+
fig : `~matplotlib.figure.Figure`
153155
"""
154156
martist.Artist.set_figure(self, fig)
155157
for c in self.get_children():
@@ -164,6 +166,29 @@ def axes(self, ax):
164166
c.axes = ax
165167

166168
def contains(self, mouseevent):
169+
"""
170+
Delegate the mouse event contains-check to the children.
171+
172+
As a container, the `.OffsetBox` does not respond itself to
173+
mouseevents.
174+
175+
Parameters
176+
----------
177+
mouseevent : `matplotlib.backend_bases.MouseEvent`
178+
179+
Returns
180+
-------
181+
contains : bool
182+
Whether any values are within the radius.
183+
details : dict
184+
An artist-specific dictionary of details of the event context,
185+
such as which points are contained in the pick radius. See the
186+
individual Artist subclasses for details.
187+
188+
See Also
189+
--------
190+
.Artist.contains
191+
"""
167192
for c in self.get_children():
168193
a, b = c.contains(mouseevent)
169194
if a:
@@ -177,8 +202,10 @@ def set_offset(self, xy):
177202
Parameters
178203
----------
179204
xy : (float, float) or callable
180-
The (x,y) coordinates of the offset in display units.
181-
A callable must have the signature::
205+
The (x, y) coordinates of the offset in display units. These can
206+
either be given explicitly as a tuple (x, y), or by providing a
207+
function that converts the extent into the offset. This function
208+
must have the signature::
182209
183210
def offset(width, height, xdescent, ydescent, renderer) \
184211
-> (float, float)
@@ -188,58 +215,79 @@ def offset(width, height, xdescent, ydescent, renderer) \
188215

189216
def get_offset(self, width, height, xdescent, ydescent, renderer):
190217
"""
191-
Get the offset
218+
Return the offset as a tuple (x, y).
219+
220+
The extent parameters have to be provided to handle the case where the
221+
offset is dynamically determined by a callable (see
222+
`~.OffsetBox.set_offset`).
223+
224+
Parameters
225+
----------
226+
width, height, xdescent, ydescent
227+
Extent parameters.
228+
renderer : `.RendererBase` subclass
192229
193-
accepts extent of the box
194230
"""
195231
return (self._offset(width, height, xdescent, ydescent, renderer)
196232
if callable(self._offset)
197233
else self._offset)
198234

199235
def set_width(self, width):
200236
"""
201-
Set the width
237+
Set the width of the box.
202238
203-
accepts float
239+
Parameters
240+
----------
241+
width : float
204242
"""
205243
self.width = width
206244
self.stale = True
207245

208246
def set_height(self, height):
209247
"""
210-
Set the height
248+
Set the height of the box.
211249
212-
accepts float
250+
Parameters
251+
----------
252+
height : float
213253
"""
214254
self.height = height
215255
self.stale = True
216256

217257
def get_visible_children(self):
218-
"""
219-
Return a list of visible artists it contains.
220-
"""
258+
r"""Return a list of the visible child `.Artist`\s."""
221259
return [c for c in self._children if c.get_visible()]
222260

223261
def get_children(self):
224-
"""
225-
Return a list of artists it contains.
226-
"""
262+
r"""Return a list of the child `.Artist`\s."""
227263
return self._children
228264

229265
def get_extent_offsets(self, renderer):
230-
raise Exception("")
231-
232-
def get_extent(self, renderer):
233266
"""
234-
Return with, height, xdescent, ydescent of box
267+
Update offset of the children and return the extent of the box.
268+
269+
Parameters
270+
----------
271+
renderer : `.RendererBase` subclass
272+
273+
Returns
274+
-------
275+
width
276+
height
277+
xdescent
278+
ydescent
279+
list of (xoffset, yoffset) pairs
235280
"""
281+
raise NotImplementedError(
282+
"get_extent_offsets must be overridden in derived classes.")
283+
284+
def get_extent(self, renderer):
285+
"""Return a tuple ``width, height, xdescent, ydescent`` of the box."""
236286
w, h, xd, yd, offsets = self.get_extent_offsets(renderer)
237287
return w, h, xd, yd
238288

239289
def get_window_extent(self, renderer):
240-
'''
241-
get the bounding box in display space.
242-
'''
290+
"""Return the bounding box (`.Bbox`) in display space."""
243291
w, h, xd, yd, offsets = self.get_extent_offsets(renderer)
244292
px, py = self.get_offset(w, h, xd, yd, renderer)
245293
return mtransforms.Bbox.from_bounds(px - xd, py - yd, w, h)
@@ -249,7 +297,6 @@ def draw(self, renderer):
249297
Update the location of children if necessary and draw them
250298
to the given *renderer*.
251299
"""
252-
253300
width, height, xdescent, ydescent, offsets = self.get_extent_offsets(
254301
renderer)
255302

@@ -271,23 +318,29 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
271318
Parameters
272319
----------
273320
pad : float, optional
274-
Boundary pad.
321+
The boundary padding in points.
275322
276323
sep : float, optional
277-
Spacing between items.
324+
The spacing between items in points.
278325
279-
width : float, optional
326+
width, height : float, optional
327+
Width and height of the container box in pixels, calculated if
328+
*None*.
329+
330+
align : {'top', 'bottom', 'left', 'right', 'center', 'baseline'}
331+
Alignment of boxes.
280332
281-
height : float, optional
282-
Width and height of the container box, calculated if
283-
`None`.
333+
mode : {'fixed', 'expand', 'equal'}
334+
The packing mode.
284335
285-
align : str, optional
286-
Alignment of boxes. Can be one of ``top``, ``bottom``,
287-
``left``, ``right``, ``center`` and ``baseline``
336+
- 'fixed' packs the given `.Artists` tight with *sep* spacing.
337+
- 'expand' uses the maximal available space to distribute the
338+
artists with equal spacing in between.
339+
- 'equal': Each artist an equal fraction of the available space
340+
and is left-aligned (or top-aligned) therein.
288341
289-
mode : str, optional
290-
Packing mode.
342+
children : list of `.Artist`
343+
The artists to pack.
291344
292345
Notes
293346
-----
@@ -319,23 +372,29 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
319372
Parameters
320373
----------
321374
pad : float, optional
322-
Boundary pad.
375+
The boundary padding in points.
323376
324377
sep : float, optional
325-
Spacing between items.
378+
The spacing between items in points.
326379
327-
width : float, optional
380+
width, height : float, optional
381+
Width and height of the container box in pixels, calculated if
382+
*None*.
328383
329-
height : float, optional
384+
align : {'top', 'bottom', 'left', 'right', 'center', 'baseline'}
385+
Alignment of boxes.
330386
331-
width and height of the container box, calculated if
332-
`None`.
387+
mode : {'fixed', 'expand', 'equal'}
388+
The packing mode.
333389
334-
align : str, optional
335-
Alignment of boxes.
390+
- 'fixed' packs the given `.Artists` tight with *sep* spacing.
391+
- 'expand' uses the maximal available space to distribute the
392+
artists with equal spacing in between.
393+
- 'equal': Each artist an equal fraction of the available space
394+
and is left-aligned (or top-aligned) therein.
336395
337-
mode : str, optional
338-
Packing mode.
396+
children : list of `.Artist`
397+
The artists to pack.
339398
340399
Notes
341400
-----
@@ -346,10 +405,7 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
346405
super().__init__(pad, sep, width, height, align, mode, children)
347406

348407
def get_extent_offsets(self, renderer):
349-
"""
350-
update offset of childrens and return the extents of the box
351-
"""
352-
408+
# docstring inherited
353409
dpicor = renderer.points_to_pixels(1.)
354410
pad = self.pad * dpicor
355411
sep = self.sep * dpicor
@@ -395,22 +451,29 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
395451
Parameters
396452
----------
397453
pad : float, optional
398-
Boundary pad.
454+
The boundary padding in points.
399455
400456
sep : float, optional
401-
Spacing between items.
457+
The spacing between items in points.
458+
459+
width, height : float, optional
460+
Width and height of the container box in pixels, calculated if
461+
*None*.
402462
403-
width : float, optional
463+
align : {'top', 'bottom', 'left', 'right', 'center', 'baseline'}
464+
Alignment of boxes.
404465
405-
height : float, optional
406-
Width and height of the container box, calculated if
407-
`None`.
466+
mode : {'fixed', 'expand', 'equal'}
467+
The packing mode.
408468
409-
align : str
410-
Alignment of boxes.
469+
- 'fixed' packs the given `.Artists` tight with *sep* spacing.
470+
- 'expand' uses the maximal available space to distribute the
471+
artists with equal spacing in between.
472+
- 'equal': Each artist an equal fraction of the available space
473+
and is left-aligned (or top-aligned) therein.
411474
412-
mode : str
413-
Packing mode.
475+
children : list of `.Artist`
476+
The artists to pack.
414477
415478
Notes
416479
-----
@@ -421,9 +484,7 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
421484
super().__init__(pad, sep, width, height, align, mode, children)
422485

423486
def get_extent_offsets(self, renderer):
424-
"""
425-
update offset of children and return the extents of the box
426-
"""
487+
# docstring inherited
427488
dpicor = renderer.points_to_pixels(1.)
428489
pad = self.pad * dpicor
429490
sep = self.sep * dpicor
@@ -458,20 +519,30 @@ def get_extent_offsets(self, renderer):
458519

459520
return (width + 2 * pad, height + 2 * pad,
460521
xdescent + pad, ydescent + pad,
461-
list(zip(xoffsets, yoffsets)))
522+
list(zip(xoffsets, yoffsets)))
462523

463524

464525
class PaddedBox(OffsetBox):
526+
"""
527+
A container to add a padding around an `.Artist`.
528+
529+
The `.PaddedBox` contains a `.FancyBboxPatch` that is used to visualize
530+
it when rendering.
531+
"""
465532
def __init__(self, child, pad=None, draw_frame=False, patch_attrs=None):
466533
"""
467-
*pad* : boundary pad
468-
469-
.. note::
470-
*pad* need to given in points and will be
471-
scale with the renderer dpi, while *width* and *height*
472-
need to be in pixels.
534+
Parameters
535+
----------
536+
child : `~matplotlib.artist.Artist`
537+
The contained `.Artist`.
538+
pad : float
539+
The padding in points. This will be scaled with the renderer dpi.
540+
In contrast *width* and *hight* are in *pixel* and thus not scaled.
541+
draw_frame : bool
542+
Whether to draw the contained `.FancyBboxPatch`.
543+
patch_attrs : dict or None
544+
Additional parameters passed to the contained `.FancyBboxPatch`.
473545
"""
474-
475546
super().__init__()
476547

477548
self.pad = pad
@@ -492,10 +563,7 @@ def __init__(self, child, pad=None, draw_frame=False, patch_attrs=None):
492563
self._drawFrame = draw_frame
493564

494565
def get_extent_offsets(self, renderer):
495-
"""
496-
update offset of childrens and return the extents of the box
497-
"""
498-
566+
# docstring inherited.
499567
dpicor = renderer.points_to_pixels(1.)
500568
pad = self.pad * dpicor
501569

@@ -510,7 +578,6 @@ def draw(self, renderer):
510578
Update the location of children if necessary and draw them
511579
to the given *renderer*.
512580
"""
513-
514581
width, height, xdescent, ydescent, offsets = self.get_extent_offsets(
515582
renderer)
516583

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.