Progress bar header and footer (#1262)

examples/Console/Progress/Program.cs

@@ -1,7 +1,9 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Threading;
 using Spectre.Console;
+using Spectre.Console.Rendering;
 
 namespace Progress;
 
@@ -22,35 +24,36 @@ public static class Program
                     new RemainingTimeColumn(),      // Remaining time
                     new SpinnerColumn(),            // Spinner
             })
+            .UseRenderHook((renderable, tasks) => RenderHook(tasks, renderable))
             .Start(ctx =>
             {
                 var random = new Random(DateTime.Now.Millisecond);
 
-                    // Create some tasks
-                    var tasks = CreateTasks(ctx, random);
+                // Create some tasks
+                var tasks = CreateTasks(ctx, random);
                 var warpTask = ctx.AddTask("Going to warp", autoStart: false).IsIndeterminate();
 
                     // Wait for all tasks (except the indeterminate one) to complete
-                    while (!ctx.IsFinished)
+                while (!ctx.IsFinished)
                 {
-                        // Increment progress
-                        foreach (var (task, increment) in tasks)
+                    // Increment progress
+                    foreach (var (task, increment) in tasks)
                     {
                         task.Increment(random.NextDouble() * increment);
                     }
 
-                        // Write some random things to the terminal
-                        if (random.NextDouble() < 0.1)
+                    // Write some random things to the terminal
+                    if (random.NextDouble() < 0.1)
                     {
                         WriteLogMessage();
                     }
 
-                        // Simulate some delay
-                        Thread.Sleep(100);
+                    // Simulate some delay
+                    Thread.Sleep(100);
                 }
 
                     // Now start the "warp" task
-                    warpTask.StartTask();
+                warpTask.StartTask();
                 warpTask.IsIndeterminate(false);
                 while (!ctx.IsFinished)
                 {
@@ -65,6 +68,35 @@ public static class Program
         AnsiConsole.MarkupLine("[green]Done![/]");
     }
 
+    private static IRenderable RenderHook(IReadOnlyList<ProgressTask> tasks, IRenderable renderable)
+    {
+        var header = new Panel("Going on a :rocket:, we're going to the :crescent_moon:").Expand().RoundedBorder();
+        var footer = new Rows(
+            new Rule(),
+            new Markup(
+                $"[blue]{tasks.Count}[/] total tasks. [green]{tasks.Count(i => i.IsFinished)}[/] complete.")
+        );
+
+        const string ESC = "\u001b";
+        string escapeSequence;
+        if (tasks.All(i => i.IsFinished))
+        {
+            escapeSequence = $"{ESC}]]9;4;0;100{ESC}\\";
+        }
+        else
+        {
+            var total = tasks.Sum(i => i.MaxValue);
+            var done = tasks.Sum(i => i.Value);
+            var percent = (int)(done / total * 100);
+            escapeSequence = $"{ESC}]]9;4;1;{percent}{ESC}\\";
+        }
+
+        var middleContent = new Grid().AddColumns(new GridColumn(), new GridColumn().Width(20));
+        middleContent.AddRow(renderable, new FigletText(tasks.Count(i => i.IsFinished == false).ToString()));
+
+        return new Rows(header, middleContent, footer, new ControlCode(escapeSequence));
+    }
+
     private static List<(ProgressTask Task, int Delay)> CreateTasks(ProgressContext progress, Random random)
     {
         var tasks = new List<(ProgressTask, int)>();

src/Spectre.Console/Extensions/Progress/ProgressExtensions.cs

@@ -34,6 +34,19 @@ public static class ProgressExtensions
         return progress;
     }
 
+    /// <summary>
+    /// Sets an optional hook to intercept rendering.
+    /// </summary>
+    /// <param name="progress">The <see cref="Progress"/> instance.</param>
+    /// <param name="renderHook">The custom render function.</param>
+    /// <returns>The same instance so that multiple calls can be chained.</returns>
+    public static Progress UseRenderHook(this Progress progress, Func<IRenderable, IReadOnlyList<ProgressTask>, IRenderable> renderHook)
+    {
+        progress.RenderHook = renderHook;
+
+        return progress;
+    }
+
     /// <summary>
     /// Sets whether or not auto refresh is enabled.
     /// If disabled, you will manually have to refresh the progress.

src/Spectre.Console/Live/Progress/Progress.cs

@@ -7,6 +7,11 @@ public sealed class Progress
 {
     private readonly IAnsiConsole _console;
 
+    /// <summary>
+    /// Gets or sets a optional custom render function.
+    /// </summary>
+    public Func<IRenderable, IReadOnlyList<ProgressTask>, IRenderable> RenderHook { get; set; } = (renderable, _) => renderable;
+
     /// <summary>
     /// Gets or sets a value indicating whether or not task list should auto refresh.
     /// Defaults to <c>true</c>.
@@ -158,7 +163,7 @@ public sealed class Progress
         if (interactive)
         {
             var columns = new List<ProgressColumn>(Columns);
-            return new DefaultProgressRenderer(_console, columns, RefreshRate, HideCompleted);
+            return new DefaultProgressRenderer(_console, columns, RefreshRate, HideCompleted, RenderHook);
         }
         else
         {

src/Spectre.Console/Live/Progress/Renderers/DefaultProgressRenderer.cs

@@ -8,11 +8,12 @@ internal sealed class DefaultProgressRenderer : ProgressRenderer
     private readonly object _lock;
     private readonly Stopwatch _stopwatch;
     private readonly bool _hideCompleted;
+    private readonly Func<IRenderable, IReadOnlyList<ProgressTask>, IRenderable> _renderHook;
     private TimeSpan _lastUpdate;
 
     public override TimeSpan RefreshRate { get; }
 
-    public DefaultProgressRenderer(IAnsiConsole console, List<ProgressColumn> columns, TimeSpan refreshRate, bool hideCompleted)
+    public DefaultProgressRenderer(IAnsiConsole console, List<ProgressColumn> columns, TimeSpan refreshRate, bool hideCompleted, Func<IRenderable, IReadOnlyList<ProgressTask>, IRenderable> renderHook)
     {
         _console = console ?? throw new ArgumentNullException(nameof(console));
         _columns = columns ?? throw new ArgumentNullException(nameof(columns));
@@ -21,6 +22,7 @@ internal sealed class DefaultProgressRenderer : ProgressRenderer
         _stopwatch = new Stopwatch();
         _lastUpdate = TimeSpan.Zero;
         _hideCompleted = hideCompleted;
+        _renderHook = renderHook;
 
         RefreshRate = refreshRate;
     }
@@ -95,13 +97,20 @@ internal sealed class DefaultProgressRenderer : ProgressRenderer
             }
 
             // Add rows
-            foreach (var task in context.GetTasks().Where(tsk => !(_hideCompleted && tsk.IsFinished)))
+            var tasks = context.GetTasks();
+
+            var layout = new Grid();
+            layout.AddColumn();
+
+            foreach (var task in tasks.Where(tsk => !(_hideCompleted && tsk.IsFinished)))
             {
                 var columns = _columns.Select(column => column.Render(renderContext, task, delta));
                 grid.AddRow(columns.ToArray());
             }
 
-            _live.SetRenderable(new Padder(grid, new Padding(0, 1)));
+            layout.AddRow(grid);
+
+            _live.SetRenderable(new Padder(_renderHook(layout, tasks), new Padding(0, 1)));
         }
     }
 

src/Spectre.Console/Widgets/ControlCode.cs

@@ -1,19 +1,28 @@
 namespace Spectre.Console;
 
-internal sealed class ControlCode : Renderable
+/// <summary>
+/// A control code.
+/// </summary>
+public sealed class ControlCode : Renderable
 {
     private readonly Segment _segment;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ControlCode"/> class.
+    /// </summary>
+    /// <param name="control">The control code.</param>
     public ControlCode(string control)
     {
         _segment = Segment.Control(control);
     }
 
+    /// <inheritdoc />
     protected override Measurement Measure(RenderOptions options, int maxWidth)
     {
         return new Measurement(0, 0);
     }
 
+    /// <inheritdoc />
     protected override IEnumerable<Segment> Render(RenderOptions options, int maxWidth)
     {
         if (options.Ansi)

src/Spectre.Console/Widgets/Rows.cs

@@ -63,7 +63,7 @@ public sealed class Rows : Renderable, IExpandable
 
                 if (last)
                 {
-                    if (!segment.IsLineBreak)
+                    if (!segment.IsLineBreak && child is not ControlCode)
                     {
                         result.Add(Segment.LineBreak);
                     }