artists. It returns artists that are currently supported by matplotlib.

For matplotlib v1.0 and before, the supported artists are as follows.

* :class:`~matplotlib.lines.Line2D`

* :class:`~matplotlib.patches.Patch`

* :class:`~matplotlib.collections.LineCollection`

* :class:`~matplotlib.collections.RegularPolyCollection`

And, :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` returns

all artists in *ax.lines*, *ax.patches* and

artists in *ax.collection* which are instance of

"_", those artists will be ignored.

Therefore, plots drawn by some *pyplot* commands are not supported by

legend. For example, :func:`~matplotlib.pyplot.fill_between` creates

:class:`~matplotlib.collections.PolyCollection` that is not

supported. Also support is limted for some commands that creat

multiple artists. For example, :func:`~matplotlib.pyplot.errorbar`

creates multiples :class:`~matplotlib.lines.Line2D` instances.

Unfortunately, there is no easy workaround when you need legend for an

artist not supported by matplotlib (You may use one of the supported

artist as a proxy. See below)

In newer version of matplotlib (v1.1 and later), the matplotlib

internals are revised to support

* complex plots that creates multiple artists (e.g., bar, errorbar, etc)

* custom legend handles

See below for details of new functionality.

Legend of Complex Plots

In matplotlib v1.1 (FIXME when released) and later, the legend is

improved to support more plot commands and ease the customization.

Legend Handler

One of the change is that drawing of legend handles is delegated to

legend handlers. For example, :class:`~matplotlib.lines.Line2D`

instances are handled by

:class:`~matplotlib.legend_handler.HandlerLine2D`. The mapping

between the artists and their corresponding handlers are defined in a

the handler_map of the legend. The handler_map is a dictionary of

key-handler pair, where key can be an artist instance or its

class. And the handler is a Handler instance.

Let's consider the following sample code, ::

For each *p_i*, matplotlib

1. check if *p_i* itself is in the handler_map

2. if not, iterate over type(p_i).mro() until a matching key is found in the handler_map

For example, the default handler_map

has following key-handler pairs (below is only a part of them).

* Line2D : legend_handler.HandlerLine2D()

* Patch : legend_handler.HandlerPatch()

* LineCollection : legend_handler.HandlerLineCollection()

* ...

The legend command takes an optional argument of "handler_map". When

provided, the default handler will be updated (using dict.update

method) with the provided one. ::

The above example will use *my_handler* for any Line2D

instances (p1 and p2). ::

In the above example, only *p1* will be handled by *my_handler*, while

others will be handled by default handlers.

Artist Container

The Artist Container is simple class (derived from tuple) that

contains multiple artists. This is introduced primarily to support

legends for complex plot commands that create multiple artists.

Axes instances now have a "containers" attribute (which is a list, and

this is only intended to be used for generating a legend). The items

in this attribute are also returned by

:meth:`~matplotlib.axes.Axes.get_legend_handles_labels`.

For example, "bar" command creates a series of Rectangle

patches. Previously, it returned a list of these patches. With the

current change, it creates a container object of these rectangle

patches (and these patches are added to Axes.patches attribute as

before) and return it instead. As the container class is derived from

a tuple, it should be backward-compatible. Furthermore, the container

object is added to the Axes.containers attributes so that legend

command can properly create a legend for the bar. Thus, you may do ::

or ::

At this time of writing, however, "bar" and "errorbar" are only

supported (hopefully the list will increase). Here is an example.

.. plot:: mpl_examples/pylab_examples/legend_demo4.py

The default *handler_map* has an entry for "tuple" which is mapped to

*HandlerTuple*. It simply overplots all the handles for items in the

given tuple. For example,

.. plot::

:include-source:

z = np.random.randn(10)

p1a, = plt.plot(z, "ro", ms=10, mfc="r", mew=2, mec="r") # red filled circle

p1b, = plt.plot(z, "w+", ms=10, mec="w", mew=2) # white cross

plt.legend([(p1a, p1b)], ["Attr A+B"])

Implement a Custom Handler

Handler can any callable object with following signature. ::

Where *legend* is the legend itself, *orig_handle* is the original

plot (*p_i* in the above example), *fontsize* is the fontsize in

pixles, and *handlebox* is a OffsetBox instance. Within the call, you

create relevant artists (using relevant properties from the *legend*

and/or *orig_handle*) and add them into the handlebox. The artists

needs to be scaled according to the fontsize (note that the size is in

pixel, i.e., this is dpi-scaled value). See legend_handler.py for more

details.