Update plot_title (#3608)

* add the plot_title

* update plot_title for multiple subplots, fix GR warning

* update plot_title

* consistency with _subplot_defaults

Co-authored-by: Simon Christ <SimonChrist@gmx.de>
Co-authored-by: t-bltg <t-bltg@users.noreply.github.com>

src/arg_desc.jl

@@ -53,7 +53,8 @@ const _arg_desc = KW(
 :colorbar_entry              => "Bool.  Include this series in the color bar?  Set to `false` to exclude.",
 
 # plot args
-:plot_title                  => "String. Title for the whole plot (not the subplots) (Note: Not currently implemented)",
+:plot_title                  => "String. Title for the whole plot (not the subplots)",
+:plot_titlevspan             => "Number in [0,1]. Vertical span of the whole plot title (fraction of the plot height)",
 :background_color            => "Color Type.  Base color for all backgrounds.",
 :background_color_outside    => "Color Type or `:match` (matches `:background_color`).  Color outside the plot area(s)",
 :foreground_color            => "Color Type.  Base color for all foregrounds.",

src/args.jl

@@ -332,12 +332,13 @@ const _series_defaults = KW(
 const _plot_defaults = KW(
     :plot_title                  => "",
     :plot_titlefontsize          => 16,
-    :plot_title_location         => :center,           # also :left or :right
+    :plot_titlelocation          => :center,           # also :left or :right
     :plot_titlefontfamily        => :match,
     :plot_titlefonthalign        => :hcenter,
     :plot_titlefontvalign        => :vcenter,
     :plot_titlefontrotation      => 0.0,
     :plot_titlefontcolor         => :match,
+    :plot_titlevspan             => 0.05,              # vertical span of the plot title, here 5%
     :background_color            => colorant"white",   # default for all backgrounds,
     :background_color_outside    => :match,            # background outside grid,
     :foreground_color            => :auto,             # default for all foregrounds, and title color,

src/pipeline.jl

@@ -286,14 +286,24 @@ function _add_plot_title!(plt)
     plot_title = plt[:plot_title]
     if plot_title != ""
         the_layout = plt.layout
-        plt.layout = grid(2, 1, heights=(.01, .99))
+        vspan = plt[:plot_titlevspan]
+        if plt.backend isa PGFPlotsXBackend
+            # FIXME: we hit a 45pt height limit:
+            # https://github.com/pgf-tikz/pgfplots/blob/3bc2f42258fbfac9fe50b2978459da7e76fc046c/tex/generic/pgfplots/pgfplots.scaling.code.tex#L153
+            vspan = max(vspan, .16)
+        end
+        plt.layout = grid(2, 1, heights=(vspan, 1 - vspan))
+        plt.layout.grid[1, 1] = subplot = Subplot(plt.backend, parent=plt.layout[1, 1])
         plt.layout.grid[2, 1] = the_layout
-        subplot = Subplot(backend(), parent = plt.layout[1, 1])
         subplot.plt = plt
-        subplot[:title] = plot_title
+        # propagate arguments plt[:plot_titleXXX] --> subplot[:titleXXX]
+        for sym ∈ filter(x -> startswith(string(x), "plot_title"), keys(_plot_defaults))
+            subplot[Symbol(string(sym)[length("plot_") + 1:end])] = plt[sym]
+        end
+        plt[:force_minpad] = nothing, 0px, nothing, 0px
         subplot[:subplot_index] = last(plt.subplots)[:subplot_index] + 1
         subplot[:framestyle] = :none
-        plt.layout.grid[1, 1] = subplot
+        subplot[:margin] = 0px
         push!(plt.subplots, subplot)
     end
     return nothing

src/plot.jl

@@ -224,6 +224,16 @@ function prepare_output(plt::Plot)
         _update_min_padding!(sp)
     end
 
+    # spedific to :plot_title see _add_plot_title!
+    force_minpad = get(plt, :force_minpad, ())
+    if !isempty(force_minpad)
+        for i ∈ eachindex(plt.layout.grid)
+            plt.layout.grid[i].minpad = Tuple(
+                i === nothing ? j : i for (i, j) ∈ zip(force_minpad, plt.layout.grid[i].minpad)
+            )
+        end
+    end
+
     # now another pass down, to update the bounding boxes
     update_child_bboxes!(plt.layout)