|
| 1 | +Constrained Layout Manager |
| 2 | +--------------------------- |
| 3 | + |
| 4 | +.. warning:: |
| 5 | + |
| 6 | + Constrained Layout is **experimental**. The |
| 7 | + behaviour and API are subject to change, or the whole functionality |
| 8 | + may be removed without a deprecation period. |
| 9 | + |
| 10 | + |
| 11 | +A new method to automatically decide spacing between subplots and their |
| 12 | +organizing ``GridSpec`` instances has been added. It is meant to |
| 13 | +replace the venerable ``tight_layout`` method. It is invoked via |
| 14 | +a new ``constrained_layout=True`` kwarg to |
| 15 | +`~.figure.Figure` or `~.figure.subplots`. |
| 16 | + |
| 17 | +There are new ``rcParams`` for this package, and spacing can be |
| 18 | +more finely tuned with the new `~.set_constrained_layout_pads`. |
| 19 | + |
| 20 | +Features include: |
| 21 | + |
| 22 | + - Automatic spacing for subplots with a fixed-size padding in inches around |
| 23 | + subplots and all their decorators, and space between as a fraction |
| 24 | + of subplot size between subplots. |
| 25 | + - Spacing for `~.figure.suptitle`, and colorbars that are attached to |
| 26 | + more than one axes. |
| 27 | + - Nested `~.GridSpec` layouts using `~.GridSpecFromSubplotSpec`. |
| 28 | + |
| 29 | + For more details and capabilities please see the new tutorial: |
| 30 | + :doc:`/tutorials/intermediate/constrainedlayout_guide` |
| 31 | + |
| 32 | +Note the new API to access this: |
| 33 | + |
| 34 | +New ``plt.figure`` and ``plt.subplots`` kwarg: ``constrained_layout`` |
| 35 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 36 | + |
| 37 | +:meth:`~matplotlib.pyplot.figure` and :meth:`~matplotlib.pyplot.subplots` |
| 38 | +can now be called with ``constrained_layout=True`` kwarg to enable |
| 39 | +constrained_layout. |
| 40 | + |
| 41 | +New ``ax.set_position`` behaviour |
| 42 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 43 | + |
| 44 | +:meth:`~matplotlib.axes.set_position` now makes the specified axis no |
| 45 | +longer responsive to ``constrained_layout``, consistent with the idea that the |
| 46 | +user wants to place an axis manually. |
| 47 | + |
| 48 | +Internally, this means that old ``ax.set_position`` calls *inside* the library |
| 49 | +are changed to private ``ax._set_position`` calls so that |
| 50 | +``constrained_layout`` will still work with these axes. |
| 51 | + |
| 52 | +New ``figure`` kwarg for ``GridSpec`` |
| 53 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 54 | + |
| 55 | +In order to facilitate ``constrained_layout``, ``GridSpec`` now accepts a |
| 56 | +``figure`` keyword. This is backwards compatible, in that not supplying this |
| 57 | +will simply cause ``constrained_layout`` to not operate on the subplots |
| 58 | +orgainzed by this ``GridSpec`` instance. Routines that use ``GridSpec`` (e.g. |
| 59 | +``fig.subplots``) have been modified to pass the figure to ``GridSpec``. |
0 commit comments