From 72c00b89657d691bab75ca09041af486616c46af Mon Sep 17 00:00:00 2001 From: Eric Firing Date: Sat, 20 Apr 2019 11:07:51 -1000 Subject: [PATCH] DOC: explain zorder for gridlines in grid docstring Closes #5045. A little extra information is also given in the set_axisbelow docstring. --- lib/matplotlib/axes/_base.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index d15136551a6a..4a5d0797e724 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2701,8 +2701,9 @@ def set_axisbelow(self, b): Possible values: - *True* (zorder = 0.5): Ticks and gridlines are below all Artists. - - 'line' (zorder = 1.5): Ticks and gridlines are above patches ( - e.g. rectangles) but still below lines / markers. + - 'line' (zorder = 1.5): Ticks and gridlines are above patches + (e.g. rectangles, with default zorder = 1) but still below lines + and markers (with their default zorder = 2). - *False* (zorder = 2.5): Ticks and gridlines are above patches and lines / markers. @@ -2730,17 +2731,17 @@ def grid(self, b=None, which='major', axis='both', **kwargs): Parameters ---------- - b : bool or None + b : bool or None, optional Whether to show the grid lines. If any *kwargs* are supplied, it is assumed you want the grid on and *b* will be set to True. If *b* is *None* and there are no *kwargs*, this toggles the visibility of the lines. - which : {'major', 'minor', 'both'} + which : {'major', 'minor', 'both'}, optional The grid lines to apply the changes on. - axis : {'both', 'x', 'y'} + axis : {'both', 'x', 'y'}, optional The axis to apply the changes on. **kwargs : `.Line2D` properties @@ -2754,7 +2755,11 @@ def grid(self, b=None, which='major', axis='both', **kwargs): Notes ----- - The grid will be drawn according to the axes' zorder and not its own. + The axis is drawn as a unit, so the effective zorder for drawing the + grid is determined by the zorder of each axis, not by the zorder of the + `.Line2D` objects comprising the grid. Therefore, to set grid zorder, + use `.set_axisbelow` or, for more control, call the + `~matplotlib.axis.Axis.set_zorder` method of each axis. """ if len(kwargs): b = True