Merge pull request GiovineItalia#1087 from Mattriks/issue487

Guide.colorkey with inside position

docs/src/lib/guides/guide_colorkey.md

@@ -4,18 +4,26 @@ Author = "Daniel C. Jones. Additions by Mattriks"
 
 # Guide.colorkey
 
-`Guide.colorkey` enables control of some fields of the auto-generated colorkey. Currently, you can change the colorkey title (for any plot), and the item labels (for plots with a discrete color scale). The fields can be named e.g. `Guide.colorkey(title="Group", labels=["A","B"])`, or given in order e.g. `Guide.colorkey("Group", ["A","B"])`.
+`Guide.colorkey` enables control of some fields of the auto-generated colorkey. Currently, you can change the colorkey title (for any plot), the item labels (for plots with a discrete color scale), and put the colorkey inside any plot. The fields can be named e.g. `Guide.colorkey(title="Group", labels=["A","B"], pos=[0w,0h])`, or given in order e.g. `Guide.colorkey("Group", ["A","B"], [0w,0h])`.
 
 ## Arguments
   * `title`: Legend title (for any plot)
   * `labels`: Legend item labels (for plots with a discrete color scale)
+  * `pos`: [x,y] position of the colorkey inside any plot. Setting `Guide.colorkey(pos=)` will override the `Theme(key_position=)` setting. Setting `Theme(key_position=:inside)` without setting `pos` will place the key in the lower right quadrant of the plot (see example below)
+
+## Colorkey position
+`pos` can be given in relative or absolute units (do `using Compose` before plotting):  
+* _Relative units_: e.g. [0.7w, 0.2h] will place the key in the lower right quadrant, [0.05w, -0.25h] in the upper left (see example below).  
+* _Absolute units_: e.g. [0mm, 0mm] the key is left-centered, or use the plot scales like [x,y]. For the latter, the x-position will make sense, but the key will be offset below the y-position, because of the way the key is rendered.  
+
 
 ## Examples
 
 ```@setup 1
 using RDatasets
+using Compose
 using Gadfly
-Gadfly.set_default_plot_size(14cm, 7cm)
+Gadfly.set_default_plot_size(16cm, 8cm)
 ```
 
 ```@example 1
@@ -27,3 +35,12 @@ plot(Dsleep, x=:BodyWt, y=:BrainWt, Geom.point, color=:SleepTime,
     Scale.x_log10, Scale.y_log10 )
 
 ```
+
+```@example 1
+iris = dataset("datasets","iris")
+pa = plot(iris, x=:SepalLength, y=:PetalLength, color=:Species, Geom.point,
+      Theme(key_position=:inside) )
+pb = plot(iris, x=:SepalLength, y=:PetalLength, color=:Species, Geom.point, 
+      Guide.colorkey(title="Iris", pos=[0.05w,-0.28h]) )
+hstack(pa, pb)
+```

docs/src/man/themes.md

@@ -56,8 +56,7 @@ These parameters can either be used with `Theme` or `style`
   * `point_label_font_size`: Font size used for labels. (Measure)
   * `point_label_color`: Color used for labels. (Color)
   * `key_position`: Where key should be placed relative to the plot panel. One
-    of `:left`, `:right`, `:top`, `:bottom`, or `:none`. Setting to `:none`
-    disables the key. (Symbol)
+    of `:left`, `:right`, `:top`, `:bottom`, `:inside` or `:none`. Setting to `:none` disables the key. Setting to `:inside` places the key in the lower right quadrant of the plot. (Symbol)
   * `key_title_font`: Font used for titles of keys. (String)
   * `key_title_font_size`: Font size used for key titles. (Measure)
   * `key_title_color`: Color used for key titles. (Color)

src/guide.jl

@@ -171,8 +171,9 @@ end
 immutable ColorKey <: Gadfly.GuideElement
     title::Union{AbstractString, (Void)}
     labels::Union{Vector{String}, (Void)}
+    pos::Union{Vector, (Void)}
 end
-ColorKey(;title=nothing, labels=nothing) = ColorKey(title, labels)
+ColorKey(;title=nothing, labels=nothing, pos=nothing) = ColorKey(title, labels, pos)
 
 @deprecate ColorKey(title) ColorKey(title=title)
 
@@ -400,6 +401,8 @@ function render(guide::ColorKey, theme::Gadfly.Theme,
                 aes::Gadfly.Aesthetics)
 
     (theme.key_position == :none || isempty(aes.color_key_colors)) && return PositionedGuide[]
+    gpos = guide.pos
+    (theme.key_position == :inside && gpos === nothing) &&  (gpos = [0.7w, 0.25h])
 
     used_colors = Set{Color}()
     colors = Array{Color}(0) # to preserve ordering
@@ -473,7 +476,10 @@ function render(guide::ColorKey, theme::Gadfly.Theme,
     end
 
     position = right_guide_position
-    if theme.key_position == :left
+    if gpos != nothing
+        position = over_guide_position
+        ctxs = [compose(context(), (context(gpos[1],gpos[2]), ctxs[1]))]
+    elseif theme.key_position == :left
         position = left_guide_position
     elseif theme.key_position == :right
         position = right_guide_position

src/theme.jl

@@ -175,7 +175,7 @@ end
     # Shape used in color keys for color swatches. Either :square or :circle.
     colorkey_swatch_shape, Symbol,          :square
 
-    # One of :left, :right, :top, :bottom, :none determining where color keys
+    # One of :left, :right, :top, :bottom, :inside, :none determining where color keys
     # and the like should be placed.
     key_position,          Symbol,          :right
 

test/testscripts/Guide_colorkey.jl

@@ -1,6 +1,8 @@
-using Gadfly
+using Compose, Gadfly
 
 set_default_plot_size(6inch, 3inch)
 
+srand(123)
 plot(x=rand(20), y=rand(20), color=repeat(["A","B"], inner=10),
-     Guide.colorkey(title="Species",labels=["Name1","Name2"]))
+     Guide.colorkey(title="Species", labels=["Name1","Name2"], pos=[0.85w,-0.3h])
+     )