Clipping for OffsetBoxes

- Child `Artists` of `DrawingArea` now get clipped to the bounds of
  the parent

doc/api/api_changes/2015-04-18-drawingarea.rst

@@ -0,0 +1,8 @@
+'OffsetBox.DrawingArea' no longer accepts the 'clip' keyword argument
+`````````````````````````````````````````````````````````````````````
+
+The call signature was `OffsetBox.DrawingArea(..., clip=True)` but nothing
+was done with the `clip` argument. The object did not do any clipping
+regardless of that parameter. Now the object can and does clip the child `Artists` if they are set to be clipped.
+
+You can turn off the clipping using :method:`Artist.set_clip_on(False)`

doc/users/whats_new/offsetbox.rst

@@ -0,0 +1,11 @@
+OffsetBoxes now support clipping
+````````````````````````````````
+
+`Artists` draw onto objects of type :class:`~OffsetBox`
+through :class:`~OffsetBox.DrawingArea` and :class:`~OffsetBox.TextArea`.
+The `TextArea` calculates the required space for the text and so the
+text is always within the bounds, for this nothing has changed.
+
+However, `DrawingArea` acts as a parent for zero or more `Artists` that
+draw on it and may do so beyond the bounds. Now child `Artists` are by
+default clipped to the bounds of the `DrawingArea`.

lib/matplotlib/__init__.py

@@ -1416,6 +1416,7 @@ def tk_window_focus():
     'matplotlib.tests.test_lines',
     'matplotlib.tests.test_mathtext',
     'matplotlib.tests.test_mlab',
+    'matplotlib.tests.test_offsetbox',
     'matplotlib.tests.test_patches',
     'matplotlib.tests.test_path',
     'matplotlib.tests.test_patheffects',

lib/matplotlib/axes/_base.py

@@ -29,6 +29,7 @@
 import matplotlib.font_manager as font_manager
 import matplotlib.text as mtext
 import matplotlib.image as mimage
+from matplotlib.offsetbox import OffsetBox
 from matplotlib.artist import allow_rasterization
 from matplotlib.cbook import iterable
 
@@ -3284,6 +3285,10 @@ def get_tightbbox(self, renderer, call_axes_locator=True):
         if bb_yaxis:
             bb.append(bb_yaxis)
 
+        for child in self.get_children():
+            if isinstance(child, OffsetBox) and child.get_visible():
+                bb.append(child.get_window_extent(renderer))
+
         _bbox = mtransforms.Bbox.union(
             [b for b in bb if b.width != 0 or b.height != 0])
 

lib/matplotlib/offsetbox.py

@@ -24,6 +24,7 @@
 import matplotlib.transforms as mtransforms
 import matplotlib.artist as martist
 import matplotlib.text as mtext
+import matplotlib.path as mpath
 import numpy as np
 from matplotlib.transforms import Bbox, BboxBase, TransformedBbox
 
@@ -149,11 +150,6 @@ def __init__(self, *args, **kwargs):
 
         super(OffsetBox, self).__init__(*args, **kwargs)
 
-        # Clipping has not been implemented in the OffesetBox family, so
-        # disable the clip flag for consistency. It can always be turned back
-        # on to zero effect.
-        self.set_clip_on(False)
-
         self._children = []
         self._offset = (0, 0)
 
@@ -562,11 +558,12 @@ class DrawingArea(OffsetBox):
     """
     The DrawingArea can contain any Artist as a child. The DrawingArea
     has a fixed width and height. The position of children relative to
-    the parent is fixed.
+    the parent is fixed. By default the children are clipped at the
+    boundaries of the parent.
     """
 
     def __init__(self, width, height, xdescent=0.,
-                 ydescent=0., clip=True):
+                 ydescent=0.):
         """
         *width*, *height* : width and height of the container box.
         *xdescent*, *ydescent* : descent of the box in x- and y-direction.
@@ -648,7 +645,17 @@ def draw(self, renderer):
         self.dpi_transform.clear()
         self.dpi_transform.scale(dpi_cor, dpi_cor)
 
+        # At this point the DrawingArea has a transform
+        # to the display space so the path created is
+        # good for clipping children
+        tpath = mtransforms.TransformedPath(
+            mpath.Path([[0, 0], [0, self.height],
+                        [self.width, self.height],
+                        [self.width, 0]]),
+            self.get_transform())
         for c in self._children:
+            if not c.clipbox and not c._clippath:
+                c.set_clip_path(tpath)
             c.draw(renderer)
 
         bbox_artist(self, renderer, fill=False, props=dict(pad=0.))

lib/matplotlib/tests/test_offsetbox.py

@@ -0,0 +1,49 @@
+from __future__ import (absolute_import, division, print_function,
+                        unicode_literals)
+
+import nose
+
+from matplotlib.testing.decorators import image_comparison
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+import matplotlib.lines as mlines
+from matplotlib.offsetbox import AnchoredOffsetbox, DrawingArea
+
+
+@image_comparison(baseline_images=['offsetbox_clipping'], remove_text=True)
+def test_offsetbox_clipping():
+    # - create a plot
+    # - put an AnchoredOffsetbox with a child DrawingArea
+    #   at the center of the axes
+    # - give the DrawingArea a gray background
+    # - put a black line across the bounds of the DrawingArea
+    # - see that the black line is clipped to the edges of
+    #   the DrawingArea.
+    fig, ax = plt.subplots()
+    size = 100
+    da = DrawingArea(size, size)
+    bg = mpatches.Rectangle((0, 0), size, size,
+                            facecolor='#CCCCCC',
+                            edgecolor='None',
+                            linewidth=0)
+    line = mlines.Line2D([-size*.5, size*1.5], [size/2, size/2],
+                         color='black',
+                         linewidth=10)
+    anchored_box = AnchoredOffsetbox(
+        loc=10,
+        child=da,
+        pad=0.,
+        frameon=False,
+        bbox_to_anchor=(.5, .5),
+        bbox_transform=ax.transAxes,
+        borderpad=0.)
+
+    da.add_artist(bg)
+    da.add_artist(line)
+    ax.add_artist(anchored_box)
+    ax.set_xlim((0, 1))
+    ax.set_ylim((0, 1))
+
+
+if __name__ == '__main__':
+    nose.runmodule(argv=['-s', '--with-doctest'], exit=False)