Skip to content

Document How-to figure empty #15297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 21, 2019
Merged

Document How-to figure empty #15297

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 39 additions & 9 deletions doc/faq/howto_faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _howto-faq:

******
How-To
How-to
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We only capitalize the first letter in headings (also looks better IMHO).

******

.. contents::
Expand All @@ -10,8 +10,8 @@ How-To

.. _howto-plotting:

Plotting: howto
===============
How-to: Plotting
================

.. _howto-datetime64:

Expand All @@ -37,6 +37,36 @@ If you only want to use the `pandas` converter for `numpy.datetime64` values ::



.. _howto-figure-empty:

Check whether a figure is empty
-------------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, the next section uses findobj, can these two sections not be combined?

I think it would be nice if this info also went into figure.findobj. I was a little confused by this - I'd have just checked figure.get_children() findobj traverses the whole tree, I suspect needlessly for this case?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, get_children() is sufficient. Thanks, changed.

I don't know how to combine these sections - maybe don't have to anymore because they now use different methods. Will modify docstrings in a separate PR. Otherwise we can't port this back to the doc branch.

Empty can actually mean different things. Does the figure contain any artists?
Does a figure with an empty `~.axes.Axes` still count as empty? Is the figure
empty if it was rendered pure white (there may be artists present, but they
could be outside the drawing area or transparent)?

For the purpose here, we define empty as: "The figure does not contain any
artists except it's background patch." The exception for the background is
necessary, because by default every figure contains a `.Rectangle` as it's
background patch. This definition could be checked via::

def is_empty(figure):
"""
Return whether the figure contains no Artists (other than the default
background patch).
"""
contained_artists = figure.get_children()
return len(contained_artists) <= 1

We've decided not to include this as a figure method because this is only one
way of defining empty, and checking the above is only rarely necessary.
Usually the user or program handling the figure know if they have added
something to the figure.

Checking whether a figure would render empty cannot be reliably checked except
by actually rendering the figure and investigating the rendered result.

.. _howto-findobj:

Find all objects in a figure of a certain type
Expand Down Expand Up @@ -553,8 +583,8 @@ most GUI backends *require* being run from the main thread as well.

.. _howto-contribute:

Contributing: howto
===================
How-to: Contributing
====================

.. _how-to-request-feature:

Expand Down Expand Up @@ -641,8 +671,8 @@ or look at the open issues on github.

.. _howto-webapp:

Matplotlib in a web application server
======================================
How to use Matplotlib in a web application server
=================================================

In general, the simplest solution when using Matplotlib in a web server is
to completely avoid using pyplot (pyplot maintains references to the opened
Expand Down Expand Up @@ -694,8 +724,8 @@ contributing to these efforts that would be great.

.. _how-to-search-examples:

Search examples
===============
How to search for examples
==========================

The nearly 300 code :ref:`examples-index` included with the Matplotlib
source distribution are full-text searchable from the :ref:`search`
Expand Down