Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 075e336

Browse files
leejjoonleejjoon
committed
legend doc. update
svn path=/trunk/matplotlib/; revision=7308
1 parent c6bf0f7 commit 075e336

File tree

5 files changed

+177
-48
lines changed

5 files changed

+177
-48
lines changed

‎lib/matplotlib/axes.py

Lines changed: 49 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3906,31 +3906,66 @@ def legend(self, *args, **kwargs):
39063906
'center' 10
39073907
=============== =============
39083908
3909-
If none of these are locations are suitable, loc can be a 2-tuple
3910-
giving x,y in axes coords, ie::
39113909
3912-
loc = 0, 1 # left top
3913-
loc = 0.5, 0.5 # center
3910+
Users can specify any arbitrary location for the legend using the
3911+
*bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
3912+
of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
3913+
For example,
3914+
3915+
loc = 'upper right', bbox_to_anchor = (0.5, 0.5)
3916+
3917+
will place the legend so that the upper right corner of the legend at
3918+
the center of the axes.
3919+
3920+
The legend location can be specified in other coordinate, by using the
3921+
*bbox_transform* keyword.
3922+
3923+
The loc itslef can be a 2-tuple giving x,y of the lower-left corner of
3924+
the legend in axes coords (*bbox_to_anchor* is ignored).
3925+
39143926
39153927
Keyword arguments:
39163928
3917-
*isaxes*: [ True | False ]
3918-
Indicates that this is an axes legend
3929+
*prop*: [ None | FontProperties | dict ]
3930+
A :class:`matplotlib.font_manager.FontProperties`
3931+
instance. If *prop* is a dictionary, a new instance will be
3932+
created with *prop*. If *None*, use rc settings.
39193933
39203934
*numpoints*: integer
3921-
The number of points in the legend line, default is 4
3935+
The number of points in the legend for line
39223936
3923-
*prop*: [ None | FontProperties ]
3924-
A :class:`matplotlib.font_manager.FontProperties`
3925-
instance, or *None* to use rc settings.
3937+
*scatterpoints*: integer
3938+
The number of points in the legend for scatter plot
3939+
3940+
*scatteroffsets*: list of floats
3941+
a list of yoffsets for scatter symbols in legend
39263942
39273943
*markerscale*: [ None | scalar ]
39283944
The relative size of legend markers vs. original. If *None*, use rc
39293945
settings.
39303946
3947+
*fancybox*: [ None | False | True ]
3948+
if True, draw a frame with a round fancybox. If None, use rc
3949+
39313950
*shadow*: [ None | False | True ]
39323951
If *True*, draw a shadow behind legend. If *None*, use rc settings.
39333952
3953+
*ncol* : integer
3954+
number of columns. default is 1
3955+
3956+
*mode* : [ "expand" | None ]
3957+
if mode is "expand", the legend will be horizontally expanded
3958+
to fill the axes area (or *bbox_to_anchor*)
3959+
3960+
*bbox_to_anchor* : an instance of BboxBase or a tuple of 2 or 4 floats
3961+
the bbox that the legend will be anchored.
3962+
3963+
*bbox_transform* : [ an instance of Transform | None ]
3964+
the transform for the bbox. transAxes if None.
3965+
3966+
*title* : string
3967+
the legend title
3968+
39343969
Padding and spacing between various elements use following keywords
39353970
parameters. The dimensions of these values are given as a fraction
39363971
of the fontsize. Values from rcParams will be used if None.
@@ -3946,9 +3981,13 @@ def legend(self, *args, **kwargs):
39463981
columnspacing the spacing between columns
39473982
================ ==================================================================
39483983
3984+
39493985
**Example:**
39503986
39513987
.. plot:: mpl_examples/api/legend_demo.py
3988+
3989+
Also see :ref:`plotting-guide-legend`.
3990+
39523991
"""
39533992

39543993
if len(args)==0:

‎lib/matplotlib/figure.py

Lines changed: 53 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -829,28 +829,59 @@ def legend(self, handles, labels, *args, **kwargs):
829829
(0,0) is the left, bottom of the figure and 1,1 is the right,
830830
top.
831831
832-
The legend instance is returned. The following kwargs are supported
833-
834-
*loc*
835-
the location of the legend
836-
*numpoints*
837-
the number of points in the legend line
838-
*prop*
839-
a :class:`matplotlib.font_manager.FontProperties` instance
840-
*pad*
841-
the fractional whitespace inside the legend border
842-
*markerscale*
843-
the relative size of legend markers vs. original
844-
*shadow*
845-
if True, draw a shadow behind legend
846-
*labelsep*
847-
the vertical space between the legend entries
848-
*handlelen*
849-
the length of the legend lines
850-
*handletextsep*
851-
the space between the legend line and legend text
852-
*axespad*
853-
the border between the axes and legend edge
832+
Keyword arguments:
833+
834+
*prop*: [ None | FontProperties | dict ]
835+
A :class:`matplotlib.font_manager.FontProperties`
836+
instance. If *prop* is a dictionary, a new instance will be
837+
created with *prop*. If *None*, use rc settings.
838+
839+
*numpoints*: integer
840+
The number of points in the legend line, default is 4
841+
842+
*scatterpoints*: integer
843+
The number of points in the legend line, default is 4
844+
845+
*scatteroffsets*: list of floats
846+
a list of yoffsets for scatter symbols in legend
847+
848+
*markerscale*: [ None | scalar ]
849+
The relative size of legend markers vs. original. If *None*, use rc
850+
settings.
851+
852+
*fancybox*: [ None | False | True ]
853+
if True, draw a frame with a round fancybox. If None, use rc
854+
855+
*shadow*: [ None | False | True ]
856+
If *True*, draw a shadow behind legend. If *None*, use rc settings.
857+
858+
*ncol* : integer
859+
number of columns. default is 1
860+
861+
*mode* : [ "expand" | None ]
862+
if mode is "expand", the legend will be horizontally expanded
863+
to fill the axes area (or *bbox_to_anchor*)
864+
865+
*title* : string
866+
the legend title
867+
868+
Padding and spacing between various elements use following keywords
869+
parameters. The dimensions of these values are given as a fraction
870+
of the fontsize. Values from rcParams will be used if None.
871+
872+
================ ==================================================================
873+
Keyword Description
874+
================ ==================================================================
875+
borderpad the fractional whitespace inside the legend border
876+
labelspacing the vertical space between the legend entries
877+
handlelength the length of the legend handles
878+
handletextpad the pad between the legend handle and text
879+
borderaxespad the pad between the axes and legend border
880+
columnspacing the spacing between columns
881+
================ ==================================================================
882+
883+
884+
**Example:**
854885
855886
.. plot:: mpl_examples/pylab_examples/figlegend_demo.py
856887
"""

‎lib/matplotlib/legend.py

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -126,13 +126,15 @@ def __init__(self, parent, handles, labels,
126126
================ ==================================================================
127127
Keyword Description
128128
================ ==================================================================
129-
loc a location code or a tuple of coordinates
130-
numpoints the number of points in the legend line
129+
loc a location code
131130
prop the font property
132131
markerscale the relative size of legend markers vs. original
132+
numpoints the number of points in the legend for line
133+
scatterpoints the number of points in the legend for scatter plot
134+
scatteryoffsets a list of yoffsets for scatter symbols in legend
133135
fancybox if True, draw a frame with a round fancybox. If None, use rc
134136
shadow if True, draw a shadow behind legend
135-
scatteryoffsets a list of yoffsets for scatter symbols in legend
137+
ncol number of columns
136138
borderpad the fractional whitespace inside the legend border
137139
labelspacing the vertical space between the legend entries
138140
handlelength the length of the legend handles
@@ -147,9 +149,14 @@ def __init__(self, parent, handles, labels,
147149
The dimensions of pad and spacing are given as a fraction of the
148150
_fontsize. Values from rcParams will be used if None.
149151
150-
bbox_to_anchor can be an instance of BboxBase(or its derivatives) or a
151-
tuple of 2 or 4 floats. See :meth:`set_bbox_to_anchor` for more
152-
detail.
152+
Users can specify any arbitrary location for the legend using the
153+
*bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
154+
of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
155+
See :meth:`set_bbox_to_anchor` for more detail.
156+
157+
The legend location can be specified by setting *loc* with a tuple of
158+
2 floats, which is interpreted as the lower-left corner of the legend
159+
in the normalized axes coordinate.
153160
"""
154161
from matplotlib.axes import Axes # local import only to avoid circularity
155162
from matplotlib.figure import Figure # local import only to avoid circularity
@@ -158,8 +165,13 @@ def __init__(self, parent, handles, labels,
158165

159166
if prop is None:
160167
self.prop=FontProperties(size=rcParams["legend.fontsize"])
168+
elif isinstance(prop, dict):
169+
self.prop=FontProperties(**prop)
170+
if "size" not in prop:
171+
self.prop.set_size(rcParams["legend.fontsize"])
161172
else:
162173
self.prop=prop
174+
163175
self._fontsize = self.prop.get_size_in_points()
164176

165177
propnames=['numpoints', 'markerscale', 'shadow', "columnspacing",

‎lib/matplotlib/offsetbox.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -833,6 +833,10 @@ def __init__(self, loc,
833833

834834
if prop is None:
835835
self.prop=FontProperties(size=rcParams["legend.fontsize"])
836+
elif isinstance(prop, dict):
837+
self.prop=FontProperties(**prop)
838+
if "size" not in prop:
839+
self.prop.set_size(rcParams["legend.fontsize"])
836840
else:
837841
self.prop = prop
838842

‎lib/matplotlib/pyplot.py

Lines changed: 53 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -438,7 +438,7 @@ def figlegend(handles, labels, loc, **kwargs):
438438
.. seealso::
439439
440440
:func:`~matplotlib.pyplot.legend`
441-
For information about the location codes
441+
442442
"""
443443
l = gcf().legend(handles, labels, loc, **kwargs)
444444
draw_if_interactive()
@@ -6322,31 +6322,69 @@ def legend(*args, **kwargs):
63226322
'center' 10
63236323
=============== =============
63246324
6325-
If none of these are locations are suitable, loc can be a 2-tuple
6326-
giving x,y in axes coords, ie::
63276325
6328-
loc = 0, 1 # left top
6329-
loc = 0.5, 0.5 # center
6326+
Users can specify any arbitrary location for the legend using the
6327+
*bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
6328+
of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
6329+
For example, ::
6330+
6331+
loc = 'upper right', bbox_to_anchor = (0.5, 0.5)
6332+
6333+
will place the legend so that the upper right corner of the legend at
6334+
the center of the axes.
6335+
6336+
The legend location can be specified in other coordinate, by using the
6337+
*bbox_transform* keyword.
6338+
6339+
The loc itslef can be a 2-tuple giving x,y of the lower-left corner of
6340+
the legend in axes coords (*bbox_to_anchor* is ignored).
6341+
63306342
63316343
Keyword arguments:
63326344
63336345
*isaxes*: [ True | False ]
63346346
Indicates that this is an axes legend
63356347
6348+
*prop*: [ None | FontProperties | dict ]
6349+
A :class:`matplotlib.font_manager.FontProperties`
6350+
instance. If *prop* is a dictionary, a new instance will be
6351+
created with *prop*. If *None*, use rc settings.
6352+
63366353
*numpoints*: integer
6337-
The number of points in the legend line, default is 4
6354+
The number of points in the legend for line
63386355
6339-
*prop*: [ None | FontProperties ]
6340-
A :class:`matplotlib.font_manager.FontProperties`
6341-
instance, or *None* to use rc settings.
6356+
*scatterpoints*: integer
6357+
The number of points in the legend for scatter plot
6358+
6359+
*scatteroffsets*: list of floats
6360+
a list of yoffsets for scatter symbols in legend
63426361
63436362
*markerscale*: [ None | scalar ]
63446363
The relative size of legend markers vs. original. If *None*, use rc
63456364
settings.
63466365
6366+
*fancybox*: [ None | False | True ]
6367+
if True, draw a frame with a round fancybox. If None, use rc
6368+
63476369
*shadow*: [ None | False | True ]
63486370
If *True*, draw a shadow behind legend. If *None*, use rc settings.
63496371
6372+
*ncol* : integer
6373+
number of columns. default is 1
6374+
6375+
*mode* : [ "expand" | None ]
6376+
if mode is "expand", the legend will be horizontally expanded
6377+
to fill the axes area (or *bbox_to_anchor*)
6378+
6379+
*bbox_to_anchor* : an instance of BboxBase or a tuple of 2 or 4 floats
6380+
the bbox that the legend will be anchored.
6381+
6382+
*bbox_transform* : [ an instance of Transform | None ]
6383+
the transform for the bbox. transAxes if None.
6384+
6385+
*title* : string
6386+
the legend title
6387+
63506388
Padding and spacing between various elements use following keywords
63516389
parameters. The dimensions of these values are given as a fraction
63526390
of the fontsize. Values from rcParams will be used if None.
@@ -6362,9 +6400,14 @@ def legend(*args, **kwargs):
63626400
columnspacing the spacing between columns
63636401
================ ==================================================================
63646402
6403+
63656404
**Example:**
63666405
6367-
.. plot:: mpl_examples/api/legend_demo.py"""
6406+
.. plot:: mpl_examples/api/legend_demo.py
6407+
6408+
Also see :ref:`plotting-guide-legend`.
6409+
6410+
"""
63686411
ret = gca().legend(*args, **kwargs)
63696412
draw_if_interactive()
63706413
return ret

0 commit comments

Comments
 (0)