allow Legend to be created from multiple Axis (re-submit of #4984) (#5551)

* add option to collect legend entries from multiple axes

* add change to changelog

* fix formatting

* make tests more specific

* improve documentation

* create Legend from multiple axes

* fix

* update docstring

* format

---------

Co-authored-by: Justin Ackers <justin.ackers@imte.fraunhofer.de>
Co-authored-by: tom <tom.rottier@manchester.ac.uk>
Co-authored-by: ffreyer <frederic481994@hotmail.de>

Author: 4 people

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Added possibility to gather legend entries from multiple axes [#5551](https://github.com/MakieOrg/Makie.jl/pull/5551)
 - Added complete inverse transformation support to `register_projected_positions!` with `apply_inverse_transform`, `apply_inverse_transform_func`, `apply_inverse_float32convert`, and `apply_inverse_model` kwargs. These enable correct projection from non-data spaces back to data space. Includes early-exit optimization to skip redundant transform/inverse pairs when `input_space === output_space`. [#5485](https://github.com/MakieOrg/Makie.jl/pull/5485)
 - Fixed `bracket` not supporting `LaTeXString` text, which would render with dollar signs instead of mathematical notation [#5536](https://github.com/MakieOrg/Makie.jl/pull/5536)
 - Added text glow to CairoMakie [#5542](https://github.com/MakieOrg/Makie.jl/pull/5542)

Makie/src/makielayout/blocks/legend.jl

@@ -998,22 +998,29 @@ end
 
 
 """
-    Legend(fig_or_scene, axis::Union{Axis, Scene, LScene}, title = nothing; merge = false, unique = false, kwargs...)
+    Legend(fig_or_scene, axis, title = nothing; merge = false, unique = false, kwargs...)
 
-Create a single-group legend with all plots from `axis` that have the
-attribute `label` set.
+Create a single-group legend with all plots from `axis` that have the attribute
+`label` set. `axis` can be any `AbstractAxis`, `AbstractScene` or `Vector`
+of the former.
 
 If `merge` is `true`, all plot objects with the same label will be layered on top of each other into one legend entry.
 If `unique` is `true`, all plot objects with the same plot type and label will be reduced to one occurrence.
+
+To create a joint legend for multiple axes it is also possible to pass a `Vector` of axis objects.
 """
-function Legend(fig_or_scene, axis::Union{Axis, Axis3, Scene, LScene}, title = nothing; merge = false, unique = false, kwargs...)
+function Legend(
+        fig_or_scene,
+        axis::Union{AbstractAxis, AbstractScene, AbstractArray{<:Union{AbstractAxis, AbstractScene}}},
+        title = nothing; merge = false, unique = false, kwargs...
+    )
     plots, labels = get_labeled_plots(axis, merge = merge, unique = unique)
     isempty(plots) && error("There are no plots with labels in the given axis that can be put in the legend. Supply labels to plotting functions like `plot(args...; label = \"My label\")`")
     return Legend(fig_or_scene, plots, labels, title; kwargs...)
 end
 
 function get_labeled_plots(ax; merge::Bool, unique::Bool)
-    lplots_init = filter(get_plots(ax)) do plot
+    lplots_init = filter(reduce(vcat, get_plots.(ax), init = AbstractPlot[])) do plot
         haskey(plot.attributes, :label) ||
             plot isa PlotList && any(x -> haskey(x.attributes, :label), plot.plots)
     end

Makie/test/SceneLike/makielayout.jl

@@ -534,6 +534,25 @@ end
     @test make_fig(linesegments!, rand(8)) isa Figure
 end
 
+@testset "Joint legend data gathering" begin
+    f = Figure()
+    ax1 = Axis(f[1, 1])
+    l1a = lines!(ax1, rand(10), label = "test a")
+    l1b = lines!(ax1, rand(10), label = "test b")
+    ax2 = Axis(f[1, 2])
+    l2a = lines!(ax2, rand(10), label = "test a")
+    leg = Legend(f[1, 3], [ax1, ax2], merge = true)
+
+    @test f isa Figure
+    # The joint legend has two entries
+    @test length(leg.entrygroups[][][2]) == 2
+    # The first entry has two linked plots
+    @test length(leg.entrygroups[][][2][1].elements) == 2
+    # The two linked plots are the plots from two different axes
+    @test leg.entrygroups[][][2][1].elements[1].plots[] == l1a
+    @test leg.entrygroups[][][2][1].elements[2].plots[] == l2a
+end
+
 @testset "ReversibleScale" begin
     @test ReversibleScale(identity).inverse === identity
     @test ReversibleScale(log).inverse === exp

docs/src/reference/blocks/legend.md

@@ -87,6 +87,25 @@ end
 f
 ```
 
+To create a joint legend for multiple axes it is also possible to pass a `Vector` of axis objects. Together with the `merge` keyword this can be useful for legend interactivity spanning multiple axes.
+
+```@figure
+
+f = Figure()
+
+ax1 = Axis(f[1, 1])
+ax2 = Axis(f[1, 2])
+
+xs = range(0, 4pi, length = 31)
+lines!(ax1, xs, sin, label = "sin", color = :blue)
+lines!(ax2, xs, cos, label = "cos", color = :red)
+scatter!(ax1, xs, sin, label = "Points", color = :black)
+scatter!(ax2, xs, cos, label = "Points", color = :black)
+
+f[0, 1:2] = Legend(f, [ax1, ax2], "Automatic Joint Legend", merge = true, orientation = :horizontal, tellheight = true)
+
+f
+```
 
 ## Legend Inside An Axis