ENH: property if DrawingArea clips children

tacaswell · tacaswell · commit fd8a41b16df3 · 2015-05-25T23:40:58.000-04:00
Add proprety `clip_children` to provide user interface
if DrawingArea tries to clip it's children.
diff --git a/doc/users/whats_new/offsetbox.rst b/doc/users/whats_new/offsetbox.rst
@@ -9,3 +9,7 @@ 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` can be
 clipped to the bounds of the `DrawingArea`.
+
+If `DrawingArea` tries to clip it's children is controlled by the
+`clip_children` property and clipping and disabled on a pre-child
+basis by using `child.set_clip_on(False)`.
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -570,7 +570,7 @@ 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 children can be  clipped at the
+    the parent is fixed. The children can be clipped at the
     boundaries of the parent.
     """
 
@@ -596,6 +596,15 @@ def __init__(self, width, height, xdescent=0.,
 
         self.dpi_transform = mtransforms.Affine2D()
 
+    @property
+    def clip_children(self):
+        return self._clip_children
+
+    @clip_children.setter
+    def clip_children(self, val):
+        self._clip_children = bool(val)
+        self.stale = True
+
     def get_transform(self):
         """
         Return the :class:`~matplotlib.transforms.Transform` applied
diff --git a/lib/matplotlib/tests/test_offsetbox.py b/lib/matplotlib/tests/test_offsetbox.py
@@ -2,8 +2,8 @@
                         unicode_literals)
 
 import nose
-
-from matplotlib.testing.decorators import image_comparison
+from nose.tools import assert_true, assert_false
+from matplotlib.testing.decorators import image_comparison, cleanup
 import matplotlib.pyplot as plt
 import matplotlib.patches as mpatches
 import matplotlib.lines as mlines
@@ -45,5 +45,42 @@ def test_offsetbox_clipping():
     ax.set_ylim((0, 1))
 
 
+@cleanup
+def test_offsetbox_clip_children():
+    # - 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, clip=True)
+    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)
+
+    fig.canvas.draw()
+    assert_false(fig.stale)
+    da.clip_children = True
+    assert_true(fig.stale)
+
 if __name__ == '__main__':
     nose.runmodule(argv=['-s', '--with-doctest'], exit=False)
