Add an order option to layer. Fixes #267

doc/index.md

@@ -193,6 +193,16 @@ You can also pass different data frames to each layers:
 layer(another_dataframe, x="col1", y="col2", Geom.point)
 ```
 
+Ordering of layers can be controlled with the `order` keyword. A higher order
+number will cause a layer to be drawn on top of any layers with a lower number.
+If not specifiel, default order for a layer is 0.
+
+```.{julia execute="false"}
+plot(layer(x=rand(10), y=rand(10), Geom.point, order=1),
+     layer(x=rand(10), y=rand(10), Geom.line, order=2))
+```
+
+
 # Stacking
 
 Plots can also be stacked horizontally with ``hstack`` or vertically with ``vstack``. This allows more customization in regards to tick marks, axis labeling, and other plot details than is available with ``subplot_grid``.

src/Gadfly.jl

@@ -84,9 +84,10 @@ type Layer <: Element
     statistic::StatisticElement
     geom::GeometryElement
     theme::Union(Nothing, Theme)
+    order::Int
 
     function Layer()
-        new(nothing, Dict(), Stat.nil(), Geom.nil(), nothing)
+        new(nothing, Dict(), Stat.nil(), Geom.nil(), nothing, 0)
     end
 
     function Layer(lyr::Layer)
@@ -104,11 +105,15 @@ end
 
 
 
-function layer(data_source::AbstractDataFrame, elements::ElementOrFunction...;
-               mapping...)
+function layer(data_source::Union(AbstractDataFrame, Nothing),
+               elements::ElementOrFunction...; mapping...)
+    mapping = Dict{Symbol, Any}(mapping)
     lyr = Layer()
     lyr.data_source = data_source
     lyr.mapping = clean_mapping(mapping)
+    if haskey(mapping, :order)
+        lyr.order = mapping[:order]
+    end
     lyrs = Layer[lyr]
     for element in elements
         add_plot_element(lyrs, element)
@@ -118,13 +123,7 @@ end
 
 
 function layer(elements::ElementOrFunction...; mapping...)
-    lyr = Layer()
-    lyr.mapping = clean_mapping(mapping)
-    lyrs = Layer[lyr]
-    for element in elements
-        add_plot_element(lyrs, element)
-    end
-    lyrs
+    return layer(nothing, elements...; mapping...)
 end
 
 
@@ -267,6 +266,11 @@ end
 function clean_mapping(mapping)
     cleaned = Dict{Symbol, AestheticValue}()
     for (key, val) in mapping
+        # skip the "order" pesudo-aesthetic, used to order layers
+        if key == :order
+            continue
+        end
+
         if haskey(aesthetic_aliases, key)
             key = aesthetic_aliases[key]
         elseif !in(key, Aesthetics.names)
@@ -739,7 +743,7 @@ function render_prepared(plot::Plot,
                    for layer in plot.layers]
 
     compose!(plot_context,
-             [render(layer.geom, theme, aes, data, scales)
+             [compose(context(order=layer.order), render(layer.geom, theme, aes, data, scales))
               for (layer, aes, data, theme) in zip(plot.layers, layer_aess, layer_datas, themes)]...)
 
     # V. Guides

test/layer_order.jl

@@ -0,0 +1,7 @@
+
+using Gadfly
+
+plot(layer(x=1:10, y=1:10, Geom.point, Theme(default_color=color("orange"))),
+     layer(x=collect(1:10) .+ 0.1, y=collect(1:10) .+ 0.1, Geom.point,
+           Theme(default_color=color("blue")), order=1))
+

test/runtests.jl

@@ -83,6 +83,7 @@ tests = [
     ("single_boxplot",                        6inch, 3inch),
     ("subplot_scales",                        6inch, 3inch),
     ("issue509",                              6inch, 3inch),
+    ("layer_order",                           6inch, 3inch)
 ]