From fdc99a18f0a1f3160b3e11d2637a89ac419432a4 Mon Sep 17 00:00:00 2001 From: Julius Krumbiegel Date: Wed, 5 Jun 2024 20:20:02 +0200 Subject: [PATCH] Improve `linestyle` documentation with examples --- MakieCore/src/basic_plots.jl | 24 +++++++-- src/basic_recipes/makiecore_examples/lines.jl | 49 +++++++++++++++++++ src/conversions.jl | 16 ++++-- 3 files changed, 81 insertions(+), 8 deletions(-) create mode 100644 src/basic_recipes/makiecore_examples/lines.jl diff --git a/MakieCore/src/basic_plots.jl b/MakieCore/src/basic_plots.jl index 9ad23fca395..ff7575b3d24 100644 --- a/MakieCore/src/basic_plots.jl +++ b/MakieCore/src/basic_plots.jl @@ -317,7 +317,13 @@ Creates a connected line plot for each element in `(x, y, z)`, `(x, y)` or `posi color = @inherit linecolor "Sets the width of the line in screen units" linewidth = @inherit linewidth - "Sets the pattern of the line e.g. `:solid`, `:dot`, `:dashdot`. For custom patterns look at `Linestyle(Number[...])`" + """ + Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`. + These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`. + For example, `(:dot, :loose)` or `(:dashdot, :dense)`. + + For custom patterns have a look at [`Linestyle`](@ref). + """ linestyle = nothing "Sets the type of linecap used, i.e. :butt (flat with no extrusion), :square (flat with 0.5 linewidth extrusion) or :round." linecap = @inherit linecap @@ -345,7 +351,13 @@ Plots a line for each pair of points in `(x, y, z)`, `(x, y)`, or `positions`. color = @inherit linecolor "Sets the width of the line in pixel units" linewidth = @inherit linewidth - "Sets the pattern of the line e.g. `:solid`, `:dot`, `:dashdot`. For custom patterns look at `Linestyle(Number[...])`" + """ + Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`. + These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`. + For example, `(:dot, :loose)` or `(:dashdot, :dense)`. + + For custom patterns have a look at [`Linestyle`](@ref). + """ linestyle = nothing "Sets the type of linecap used, i.e. :butt (flat with no extrusion), :square (flat with 1 linewidth extrusion) or :round." linecap = @inherit linecap @@ -594,7 +606,13 @@ Plots polygons, which are defined by strokecolormap = @inherit colormap "Sets the width of the outline." strokewidth = @inherit patchstrokewidth - "Sets the pattern of the line (e.g. `:solid`, `:dot`, `:dashdot`)" + """ + Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`. + These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`. + For example, `(:dot, :loose)` or `(:dashdot, :dense)`. + + For custom patterns have a look at [`Linestyle`](@ref). + """ linestyle = nothing linecap = @inherit linecap joinstyle = @inherit joinstyle diff --git a/src/basic_recipes/makiecore_examples/lines.jl b/src/basic_recipes/makiecore_examples/lines.jl new file mode 100644 index 00000000000..dfccbdc4ef8 --- /dev/null +++ b/src/basic_recipes/makiecore_examples/lines.jl @@ -0,0 +1,49 @@ +function attribute_examples(::Type{Scatter}) + Dict( + :linestyle => [ + Example( + code = """ + linestyles = [:solid, :dot, :dash, :dashdot, :dashdotdot] + gapstyles = [:normal, :dense, :loose, 10] + fig = Figure() + with_updates_suspended(fig.layout) do + for (i, ls) in enumerate(linestyles) + for (j, gs) in enumerate(gapstyles) + title = gs === :normal ? repr(ls) : "$((ls, gs))" + ax = Axis(fig[i, j]; title, yautolimitmargin = (0.2, 0.2)) + hidedecorations!(ax) + hidespines!(ax) + linestyle = (ls, gs) + for linewidth in 1:3 + lines!(ax, 1:10, fill(linewidth, 10); linestyle, linewidth) + end + end + end + end + fig + """ + ), + Example( + code = """ + fig = Figure() + patterns = [ + [0, 1, 2], + [0, 20, 22], + [0, 2, 4, 12, 14], + [0, 2, 4, 6, 8, 10, 20], + [0, 1, 2, 4, 6, 9, 12], + [0.0, 4.0, 6.0, 9.5], + ] + ax = Axis(fig[1, 1], yautolimitmargin = (0.2, 0.2)) + for (i, pattern) in enumerate(patterns) + lines!(ax, [-i, -i], linestyle = Linestyle(pattern), linewidth = 4) + text!(ax, (1.5, -i), text = "Linestyle($pattern)", + align = (:center, :bottom), offset = (0, 10)) + end + hidedecorations!(ax) + fig + """ + ), + ], + ) +end \ No newline at end of file diff --git a/src/conversions.jl b/src/conversions.jl index 7b0812abf3d..3447c6ad8a5 100644 --- a/src/conversions.jl +++ b/src/conversions.jl @@ -927,12 +927,18 @@ end A type that can be used as value for the `linestyle` keyword argument of plotting functions to arbitrarily customize the linestyle. -The `value` is a vector of positions where the line flips from being drawn or not -and vice versa. The values of `value` are in units of linewidth. +The `value` is a vector specifying the boundaries of the dashes in the line. +Values 1 and 2 demarcate the first dash, values 2 and 3 the first gap, and so on. +This means that usually, a pattern should have an odd number of values so that there's +always a gap after a dash. -For example, with `value = [0.0, 4.0, 6.0, 9.5]` -you start drawing at 0, stop at 4 linewidths, start again at 6, stop at 9.5, -then repeat with 0 and 9.5 being treated as the same position. +Here's an example in ASCII code. If we specify `[0, 3, 6, 11, 16]` then we get the following +pattern: + +``` +# 0 3 6 11 16 3 6 11 +# --- ----- --- ----- +``` """ struct Linestyle value::Vector{Float32}