It's time to add legends 😄 ! Laying out ideas first, with some inspiration from pyqtgraph

Basics

Multiple legends will be allowed in a Subplot or Dock. They can exist in moveable and non-moveable states.

A Legend is created and then graphics can be added to it:

import fastplotlib as fpl

plot = fpl.Plot()

line_a = plot.add_line(line_data, name="A")

# create a legend
legend = fpl.Legend(plot_area=plot.docks["top"])   # can also just be `plot`

# add a "legend item" by adding the graphic to the legend
# this adds a graphical item to the legend along with text that corresponds to the graphic
legend.add_graphic(line_a, label=None)  # if label is None, uses graphic name to set the label

All legend items will auto add event handlers to relevant graphic features so that they are automatically updated.

Line collections or scatters

For line collections, use a standard legend if a qualitative colormap was used.

line_coll = plot.add_line_collection(data, colors="tab10")

# use the same legend box or create a new one
legend.add_graphic(line_coll, labels=["B", "B", "C", "C", "D"])  # label for each line in the collection, legend only contains unique labels

If a quantitative cmap is used, use colorbars instead

line_coll_jet = plot.add_line_collection(data, colors="jet")  # quantitative cmap

cbar = fpl.Colorbar(plot_area=plot.docks["top"])

cbar.add_graphic(line_coll_jet)  # colorbar if quantitative data are used for lines and scatter

Other cool features :D

Click on legend item's line, highlights corresponding graphic. Just use the feature event handlers. Click anywhere else in the legend to deactivate the highlight.

More thoughts:

• I think we should enforce unique labels among all LegendItems within a single Legend. Legends don't really make sense anyways if their entries aren't unique?
• If there are multiple colors along a single line:
  • If it is quantitative make a colorbar.
  • If it is qualitative make a legend with an item for each color?
• For LineCollection, do we need to do a sanity check to make sure that when a user passes labels, that these lines all have the same color? Likewise for other aspects like line thickness.
• For scatter, there can be different colors and sizes too, so that will also have to be dealt with just like qualitative vs. quantitative cmaps.
• ImageGraphic Colorbars are made per-ImageGraphic, and auto-made and placed next to the HistogramLUTWidget when present.
• For colorbars allow displaying just min and max, or min and max with ticks and spaced out tick labels.
• How to deal with changes? If graphic features change that's easy, our event handlers. What about larger scale changes? If the labels change for a line collection but we still have a 1 -> 1 direct mapping from old to new labels. What if the grouping of the new labels is completely diff? For example, if we colored a line collection based on neuron ID and then based on brain region, and then based on behavior?