add z_order (#4139)

* add z_order

* format

* add missing ,

* fix testss

* this time for real

* format [skip ci]

src/arg_desc.jl

@@ -52,6 +52,7 @@ const _arg_desc = KW(
     :primary            => "Bool.  Does this count as a 'real series'?  For example, you could have a path (primary), and a scatter (secondary) as 2 separate series, maybe with different data (see sticks recipe for an example).  The secondary series will get the same color, etc as the primary.",
     :hover              => "nothing or vector of strings. Text to display when hovering over each data point.",
     :colorbar_entry     => "Bool.  Include this series in the color bar?  Set to `false` to exclude.",
+    :z_order            => "Symbol or Integer. :front (default), :back or index of position where 1 is farest in the background.",
 
     # plot args
     :plot_title               => "String. Title for the whole plot (not the subplots)",

src/args.jl

@@ -399,6 +399,7 @@ const _series_defaults = KW(
     :hover        => nothing,  # text to display when hovering over the data points
     :stride       => (1, 1),    # array stride for wireframe/surface, the first element is the row stride and the second is the column stride.
     :connections  => nothing,  # tuple of arrays to specifiy connectivity of a 3d mesh
+    :z_order      => :front, # one of :front, :back or integer in 1:length(sp.series_list)
     :extra_kwargs => Dict(),
 )
 

src/backends.jl

@@ -240,6 +240,7 @@ const _base_supported_args = [
     :discrete_values,
     :projection,
     :show_empty_bins,
+    :z_order,
 ]
 
 function merge_with_base_supported(v::AVec)

src/pipeline.jl

@@ -427,7 +427,16 @@ function _add_the_series(plt, sp, plotattributes)
     warn_on_unsupported(plt.backend, plotattributes)
     series = Series(plotattributes)
     push!(plt.series_list, series)
+    z_order = plotattributes[:z_order]
+    if z_order == :front
         push!(sp.series_list, series)
+    elseif z_order == :back
+        pushfirst!(sp.series_list, series)
+    elseif z_order isa Integer
+        insert!(sp.series_list, z_order, series)
+    else
+        @error "Wrong type $(typeof(z_order)) for attribute z_order"
+    end
     _series_added(plt, series)
     _update_subplot_colorbars(sp)
 end

test/runtests.jl

@@ -38,6 +38,7 @@ end
 end
 
 for fn in (
+    "test_args.jl",
     "test_defaults.jl",
     "test_pipeline.jl",
     "test_axes.jl",

test/test_args.jl

@@ -0,0 +1,10 @@
+using Plots, Test
+
+@testset "Series Attributes" begin
+    pl = plot([[1, 2, 3], [2, 3, 4]], lw = 5)
+    @test hline!(deepcopy(pl), [1.75])[1].series_list[3][:label] ==
+          hline!(deepcopy(pl), [1.75], z_order = :front)[1].series_list[3][:label] ==
+          "y3"
+    @test hline!(deepcopy(pl), [1.75], z_order = :back)[1].series_list[1][:label] == "y3"
+    @test hline!(deepcopy(pl), [1.75], z_order = 2)[1].series_list[2][:label] == "y3"
+end