Legends

Clear the current legend information

Save information for later use in creating a legend

INPUTS

  text    -- text of the legend
  dy      -- defaults to `self.legend_text_dy`
  line_color
          -- defaults to `self.line_color`
  line_width
          -- defaults to `self.line_width`
  line_cap
          -- defaults to `self.line_cap`
  line_type
          -- defaults to `self.line_type`
  marker  -- defaults to None
  marker_color
          -- defaults to `self.line_color`
  marker_scale
          -- defaults to 0.5
  marker_dict
          -- defaults to None

The dict object holding the information given as input
argument is appended to the `self.legend_info` array.  If the
`marker` entry is present, then the marker with the given
`marker_color` and `marker_scale` will be shown in the middle
of the legend line.  If the `marker_dict` entry is present, it
will have the values for `x` and `y` set to the location of
the middle of the legend line and then it will be passed to
the `show_marker()` method.  This gives you the option of
using the full range of marker functionality in legends --
perhaps you would like to use a line marker that is rotated,
stretched, filled in one color, and stroked in another!
Sometimes you just want to have a marker in the legend without
a line; do this by setting `line_type` to None.

Create a vertical space of `dy` text heights in the legend

Show the legend in the current frame

Used as the alignment value in showing legend text

Used as the justification value in showing legend text

Each line in a legend is shifted up from the text baseline by
this amount measured in units of text height.  The
(`self.legend_line_dy` * `self.legend_scale` *
`self.default_text_height_dy`).

If this is non-negative, then it is used as the `line_width`
attribute when stroking the lines in a legend.  If it is
negative, then each legend line is stroked using the value of
the `line_width` attribute at the time the legend information
for the entry was saved by `save_legend_info()`.

The x position for the start of lines in a legend, measured in
units of text height.  The corresponding position in figure
coordinates is (`self.legend_line_x0` * `self.legend_scale` *
`self.default_text_height_dx`).

The x position for the end of lines in a legend, measured in
units of text height.  The corresponding position in figure
coordinates is (`self.legend_line_x1` * `self.legend_scale` *
`self.default_text_height_dx`).

Used for determining positions in the legend and for showing
legend text

The distance in y to move down after a legend line entry,
measured in units of text height.  The corresponding distance
in figure coordinates is (`self.legend_text_dy` *
`self.legend_scale` * `self.default_text_height_dy`).

The assumed width of text in a legend, measured in units of
text height.  The corresponding width in figure coordinates is
(`self.legend_text_width` * `self.legend_scale` *
`self.default_text_height_dx`).  The figure bounding box is
expanded if necessary to provide for this much space.  If
`self.legend_text_width` is negative, then the system will
provide a default value depending on the placement of the
legend.

The x position for the start of text in a legend, measured in
units of text height.  The corresponding position in figure
coordinates is (`self.legend_text_xstart` *
`self.legend_scale` * `self.default_text_height_dx`).

The y position for the start of text in a legend, measured in
units of text height.  The corresponding position in figure
coordinates is (`self.legend_text_ystart` *
`self.legend_scale` * `self.default_text_height_dy`).

A dict instance holding defaults for `show_plot_with_legend()`.

The height (in units of text heights) of the currently
saved legend information

The current array of saved legend dict instances.  See
`save_legend_info()` for details.