Merge faf7846 into 22d4659

docs/src/lib/scales/scale_color_continuous.md

@@ -6,6 +6,8 @@ Author = "David Chudzicki"
 
 Create a continuous color scale that the plot will use.
 
+This can also be set as the `continuous_color_scheme` in a [`Theme`](@ref)
+
 ## Arguments
 
   * `minvalue` (optional): the data value corresponding to the bottom of the color scale (will be based on the range of the data if not specified).

docs/src/lib/scales/scale_color_discrete_hue.md

@@ -4,15 +4,16 @@ Author = "David Chudzicki"
 
 # Scale.color_discrete_hue
 
-Create a discrete color scale to be used for the plot. `Scale.discrete_color` is an
+Create a discrete color scale to be used for the plot. `Scale.color_discrete` is an
 alias for [Scale.color_discrete_hue](@ref).
 
 ## Arguments
 
-  * `levels` (optional): Explicitly set levels used by the scale. Order is
-    respected.
-  * `order` (optional): A vector of integers giving a permutation of the levels
+  * `f` (optional): A function `f(n)` that produces a vector of `n` colors. Usually [`distinguishable_colors`](https://github.com/JuliaGraphics/Colors.jl#distinguishable_colors) can be used for this, with parameters tuned to your liking.
+  * `levels` (optional, keyword): Explicitly set levels used by the scale.
+  * `order` (optional, keyword): A vector of integers giving a permutation of the levels
     default order.
+  * `preserve_order` (optional, keyword): If set to `true`, orders levels as they appear in the data
 
 ## Examples
 
@@ -21,9 +22,43 @@ using Gadfly
 srand(1234)
 ```
 
-This forces the use of a discrete scale on data that would otherwise receive a continuous scale:
+## Examples
+
+You can set a discrete color scale of your choice in a plot.
+
+```@example 1
+
+function gen_colors(n)
+  cs = distinguishable_colors(n,
+      [colorant"#FE4365", colorant"#eca25c"], # seed colors
+      lchoices=Float64[58, 45, 72.5, 90],     # lightness choices
+      transform=c -> deuteranopic(c, 0.1),    # color transform
+      cchoices=Float64[20,40],                # chroma choices
+      hchoices=[75,51,35,120,180,210,270,310] # hue choices
+  )
+
+  convert(Vector{Color}, cs)
+end
+
+plot(iris, x=:SepalLength, y=:SepalWidth, color=:Species,
+     Geom.point, Scale.color_discrete(gen_colors))
+
+```
+
+You can force the use of a discrete scale on data that would otherwise receive a continuous scale:
 
 ```@example 1
 plot(x=rand(12), y=rand(12), color=repeat([1,2,3], outer=[4]),
      Scale.color_discrete())
 ```
+
+To set a default color scale for plots, you can set it in the current [Theme](@ref) using `set_theme`, using `style` to modify the current theme.
+
+```@example 1
+Gadfly.set_theme(
+    style(
+        discrete_color_scale=Scale.color_discrete(gen_colors)
+    )
+)
+```
+

docs/src/man/themes.md

@@ -1,18 +1,29 @@
 ```@meta
-Author = "Daniel C. Jones"
+Author = "Daniel C. Jones, Shashi Gowda"
 ```
 
 # Themes
 
 Many parameters controlling the appearance of plots can be overridden by passing
-a `Theme` object to the `plot` function.
+a `Theme` object to the `plot` function. Or setting the `Theme` as the current theme using `push_theme` (see also `pop_theme` and `with_theme` below).
 
-The constructor for `Theme` takes zero or more named arguments each of which
-overrides the default theme's value.
+The constructor for `Theme` takes zero or more named arguments each of which overrides the *default* value of the field.
+
+## The Theme stack
+
+Gadfly maintains a stack of themes and applies theme values from the topmost theme in the stack. This can be useful when you want to set a theme for multiple plots and then switch back to a previous theme.
+
+`push_theme(t::Theme)` and `pop_theme()` will push and pop from this stack respectively. You can use `with_theme(f, t::Theme)` to set a theme as the current theme and call `f()`.
+
+## `style`
+
+You can use `style` to override the fields on top of the *current* theme at the top of the stack. `style(...)` returns a `Theme`. So it can be used with `push_theme` and `with_theme`.
 
 
 ## Parameters
 
+These parameters can either be used with `Theme` or `style`
+
   * `default_color`: When the color aesthetic is not bound, geometry uses this
     color for drawing. (Color)
   * `default_point_size`: Size of points in the point and boxplot geometry.
@@ -71,6 +82,8 @@ overrides the default theme's value.
   * `bar_highlight`: Color used to stroke bars in bar plots. If a function is
     given, it's used to transform the fill color of the bars to obtain a stroke
     color. (Function, Color, or Nothing)
+  * `discrete_color_scheme`: A `DiscreteColorScale` see [Scale.color_discrete_hue](@ref)
+  * `continuous_color_scheme`: A `ContinuousColorScale` see [Scale.color_continuous](@ref)
 
 ## Examples
 
@@ -82,13 +95,51 @@ srand(12345)
 ```
 
 ```@example 1
-plot(x=rand(10), y=rand(10),
-     Theme(panel_fill=colorant"black", default_color=colorant"orange"))
+
+dark_panel = Theme(
+    panel_fill=colorant"black",
+    default_color=colorant"orange"
+)
+
+plot(x=rand(10), y=rand(10), dark_panel)
+
 ```
 
 Setting the font to Computer Modern to create a LaTeX-like look, and choosing a font size:
 
 ```@example 1
+Gadfly.push_theme(dark_panel)
+
 plot(x=rand(10), y=rand(10),
-     Theme(major_label_font="CMU Serif",minor_label_font="CMU Serif",major_label_font_size=16pt,minor_label_font_size=14pt))
+     style(major_label_font="CMU Serif",minor_label_font="CMU Serif",
+           major_label_font_size=16pt,minor_label_font_size=14pt))
+
+# can plot more plots here...
+
+Gadfly.pop_theme()
+```
+
+Same effect can be had with `with_theme`
+
+```@example 1
+Gadfly.with_theme(dark_panel) do
+
+  plot(x=rand(10), y=rand(10),
+       style(major_label_font="CMU Serif",minor_label_font="CMU Serif",
+             major_label_font_size=16pt,minor_label_font_size=14pt))
+end
+```
+
+or
+
+```@example 1
+
+Gadfly.push_theme(dark_panel)
+
+Gadfly.with_theme(
+       style(major_label_font="CMU Serif",minor_label_font="CMU Serif",
+             major_label_font_size=16pt,minor_label_font_size=14pt)) do
+
+  plot(x=rand(10), y=rand(10))
+end
 ```