From 1520705fa76ad134bba761c9232907499c513f11 Mon Sep 17 00:00:00 2001
From: Simon Christ <SimonChrist@gmx.de>
Date: Fri, 11 Mar 2022 15:57:06 +0100
Subject: [PATCH] add z_order (#4139)

* add z_order

* format

* add missing ,

* fix testss

* this time for real

* format [skip ci]
---
 src/arg_desc.jl   |  1 +
 src/args.jl       |  1 +
 src/backends.jl   |  1 +
 src/pipeline.jl   | 11 ++++++++++-
 test/runtests.jl  |  1 +
 test/test_args.jl | 10 ++++++++++
 6 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 test/test_args.jl

diff --git a/src/arg_desc.jl b/src/arg_desc.jl
index 11c9bc8c..8d5b8adb 100644
--- a/src/arg_desc.jl
+++ b/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)",
diff --git a/src/args.jl b/src/args.jl
index 93a1b7b7..5efbe506 100644
--- a/src/args.jl
+++ b/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(),
 )
 
diff --git a/src/backends.jl b/src/backends.jl
index 59325bfb..1258fa10 100644
--- a/src/backends.jl
+++ b/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)
diff --git a/src/pipeline.jl b/src/pipeline.jl
index 8f8ae8b7..786d8523 100644
--- a/src/pipeline.jl
+++ b/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)
-    push!(sp.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
diff --git a/test/runtests.jl b/test/runtests.jl
index eb27269a..95833810 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -38,6 +38,7 @@ end
 end
 
 for fn in (
+    "test_args.jl",
     "test_defaults.jl",
     "test_pipeline.jl",
     "test_axes.jl",
diff --git a/test/test_args.jl b/test/test_args.jl
new file mode 100644
index 00000000..49cab920
--- /dev/null
+++ b/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