Modal Wait Dialogue with BackgroundWorker

VB version here.

This demo provides a dialogue that you can display modally over another form while that form does some background work. You basically write a normal DoWork event handler for a BackgroundWorker, as well as optional ProgresssChanged and RunWorkerCompleted event handlers, and pass them to the dialogue for it to use as handlers for the events of its own BackgroundWorker. That means that your form creates and displays the dialogue, the dialogue then kicks off a BackgroundWorker and it invokes methods in your form to do the work. That way, this same dialogue can be used for any work you like without change.

The dialogue displays a Marquee ProgressBar by default and no Cancel button. If you provide a handler for the ProgressChanged event, it will display a Continuous ProgressBar so the actual progress can be displayed. Note that the Maximum of that ProgressBar is 100 so you must provide a genuine percentage when you call ReportProgress. If you set SupportsCancellation to True, the dialogue will also display a Cancel button. As always, it's up to you to process the cancellation request in your DoWork event handler.

This attached solution was created in VS 2019 and targets .NET Framework 4.8. It contains both C# and VB version of the demo. If you're using an earlier version, you should still just be able to add the forms as existing items to a project of your own, as long as you're not using too-old a version.

For those who would like to see the code without having to download the solution, here you go:

csharp Code:

using System.ComponentModel;
using System.Drawing;
using System.Windows.Forms;
 
namespace Wunnell.Demo.BackgroundWorkerForm.CS
{
    public partial class BackgroundWorkerForm : Form
    {
#region Fields
 
        private readonly DoWorkEventHandler onDoWork;
        private readonly ProgressChangedEventHandler onProgressChanged;
        private readonly RunWorkerCompletedEventHandler onRunWorkerCompleted;
 
#endregion Fields
 
#region Constructors
 
        /// <summary>
        /// Creates a new instance of the <see cref="BackgroundWorkerForm"/> class.
        /// </summary>
        /// <remarks>
        /// Parameterless constructor is private to ensure handlers are provided for <see cref="BackgroundWorker"/>.
        /// </remarks>
        public BackgroundWorkerForm()
        {
            InitializeComponent();
        }
 
        /// <summary>
        /// Creates a new instance of the <see cref="BackgroundWorkerForm" /> class.
        /// </summary>
        /// <param name="onDoWork">
        /// Handler for the <see cref="BackgroundWorker.DoWork">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        public BackgroundWorkerForm(DoWorkEventHandler onDoWork)
            : this()
        {
            this.onDoWork = onDoWork;
 
            // AddHandler is used for local event handlers so that remote event handlers can be registered first and thus executed first.
 
            // Remote event handlers
            backgroundWorker1.DoWork += onDoWork;
 
            // Local event handlers
            backgroundWorker1.RunWorkerCompleted += backgroundWorker1_RunWorkerCompleted;
        }
 
        /// <summary>
        /// Creates a new instance of the <see cref="BackgroundWorkerForm" /> class.
        /// </summary>
        /// <param name="onDoWork">
        /// Handler for the <see cref="BackgroundWorker.DoWork">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        /// <param name="onProgressChanged">
        /// Handler for the <see cref="BackgroundWorker.ProgressChanged">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        public BackgroundWorkerForm(DoWorkEventHandler onDoWork, ProgressChangedEventHandler onProgressChanged)
            : this()
        {
            this.onDoWork = onDoWork;
            this.onProgressChanged = onProgressChanged;
 
            // AddHandler is used for local event handlers so that remote event handlers can be registered first and thus executed first.
 
            // Remote event handlers
            backgroundWorker1.DoWork += onDoWork;
            backgroundWorker1.ProgressChanged += onProgressChanged;
 
            // Local event handlers
            backgroundWorker1.ProgressChanged += backgroundWorker1_ProgressChanged;
            backgroundWorker1.RunWorkerCompleted += backgroundWorker1_RunWorkerCompleted;
 
            // A ProgressChanged handler has been provided so the ProgressBar will be updated explicitly based on the BackgroundWorker.
            backgroundWorker1.WorkerReportsProgress = true;
            progressBar1.Style = ProgressBarStyle.Continuous;
        }
 
        /// <summary>
        /// Creates a new instance of the <see cref="BackgroundWorkerForm" /> class.
        /// </summary>
        /// <param name="onDoWork">
        /// Handler for the <see cref="BackgroundWorker.DoWork">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        /// <param name="onRunWorkerCompleted">
        /// Handler for the <see cref="BackgroundWorker.RunWorkerCompleted">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        public BackgroundWorkerForm(DoWorkEventHandler onDoWork, RunWorkerCompletedEventHandler onRunWorkerCompleted)
            : this()
        {
            this.onDoWork = onDoWork;
            this.onRunWorkerCompleted = onRunWorkerCompleted;
 
            // AddHandler is used for local event handlers so that remote event handlers can be registered first and thus executed first.
 
            // Remote event handlers
            backgroundWorker1.DoWork += onDoWork;
            backgroundWorker1.RunWorkerCompleted += onRunWorkerCompleted;
 
            // Local event handlers
            backgroundWorker1.RunWorkerCompleted += backgroundWorker1_RunWorkerCompleted;
        }
 
        /// <summary>
        /// Creates a new instance of the <see cref="BackgroundWorkerForm" /> class.
        /// </summary>
        /// <param name="onDoWork">
        /// Handler for the <see cref="BackgroundWorker.DoWork">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        /// <param name="onProgressChanged">
        /// Handler for the <see cref="BackgroundWorker.ProgressChanged">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        /// <param name="onRunWorkerCompleted">
        /// Handler for the <see cref="BackgroundWorker.RunWorkerCompleted">RunWorkerCompleted</see> event of a <see cref="BackgroundWorker"/>.
        /// </param>
        public BackgroundWorkerForm(
            DoWorkEventHandler onDoWork,
            ProgressChangedEventHandler onProgressChanged,
            RunWorkerCompletedEventHandler onRunWorkerCompleted)
            : this()
        {
            this.onDoWork = onDoWork;
            this.onProgressChanged = onProgressChanged;
            this.onRunWorkerCompleted = onRunWorkerCompleted;
 
            // AddHandler is used for local event handlers so that remote event handlers can be registered first and thus executed first.
 
            // Remote event handlers
            backgroundWorker1.DoWork += onDoWork;
            backgroundWorker1.ProgressChanged += onProgressChanged;
            backgroundWorker1.RunWorkerCompleted += onRunWorkerCompleted;
 
            // Local event handlers
            backgroundWorker1.ProgressChanged += backgroundWorker1_ProgressChanged;
            backgroundWorker1.RunWorkerCompleted += backgroundWorker1_RunWorkerCompleted;
 
            // A ProgressChanged handler has been provided so the ProgressBar will be updated explicitly based on the BackgroundWorker.
            backgroundWorker1.WorkerReportsProgress = true;
            progressBar1.Style = ProgressBarStyle.Continuous;
        }
 
#endregion Constructors
 
#region Properties
 
        public bool SupportsCancellation
        {
            set
            {
                backgroundWorker1.WorkerSupportsCancellation = value;
 
                // If the worker can be cancelled, show the Cancel button and make the form big enough to see it.
                cancelWorkButton.Visible = value;
                ClientSize = new Size(284,
                                      value ? 76 : 47);
            }
        }
 
#endregion Properties
 
#region Methods
 
        private void BackgroundWorkerForm_Shown(object sender, System.EventArgs e)
        {
            // Start the background work when the form is displayed.
            backgroundWorker1.RunWorkerAsync();
        }
 
        private void cancelWorkButton_Click(object sender, System.EventArgs e)
        {
            // Disable the button to prevent another click.
            cancelWorkButton.Enabled = false;
 
            // Cancel the background work.
            backgroundWorker1.CancelAsync();
        }
 
        private void backgroundWorker1_ProgressChanged(object sender, ProgressChangedEventArgs e)
        {
            // Update the ProgressBar.
            progressBar1.Value = e.ProgressPercentage;
        }
 
        private void backgroundWorker1_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e)
        {
            // Close the form when the work is done.
            Close();
        }
 
        private void BackgroundWorkerForm_FormClosing(object sender, FormClosingEventArgs e)
        {
            // Remote event handlers.
 
            if (onDoWork != null)
            {
                backgroundWorker1.DoWork -= onDoWork;
            }
 
            if (onProgressChanged != null)
            {
                backgroundWorker1.ProgressChanged -= onProgressChanged;
            }
 
            if (onRunWorkerCompleted != null)
            {
                backgroundWorker1.RunWorkerCompleted -= onRunWorkerCompleted;
            }
 
            // Local event handlers
            backgroundWorker1.ProgressChanged -= backgroundWorker1_ProgressChanged;
            backgroundWorker1.RunWorkerCompleted -= backgroundWorker1_RunWorkerCompleted;
        }
 
#endregion Methods
    }
}

csharp Code:

using System.ComponentModel;
using System.Threading;
using System.Windows.Forms;
 
namespace Wunnell.Demo.BackgroundWorkerForm.CS
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }
 
        // This method will be executed by the BackgroundWorker in the dialogue.
        private void BackgroundWorkerForm_DoWork(object sender, DoWorkEventArgs e)
        {
            var worker = (BackgroundWorker)sender;
 
            for (var i = 0; i <= 100; i++)
            {
                if (worker.CancellationPending)
                {
                    e.Cancel = true;
 
                    break;
                }
 
                if (reportProgressCheckBox.Checked)
                {
                    worker.ReportProgress(i);
                }
 
                Thread.Sleep(100);
            }
        }
 
        // This method will be executed by the BackgroundWorker in the dialogue.
        private void BackgroundWorkerForm_ProgressChanged(object sender, ProgressChangedEventArgs e)
        {
            statusLabel.Text = (e.ProgressPercentage / 100.0).ToString("p0");
        }
 
        // This method will be executed by the BackgroundWorker in the dialogue.
        private void BackgroundWorkerForm_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e)
        {
            statusLabel.Text = e.Cancelled
                                   ? "Operation cancelled"
                                   : "Operation complete";
        }
 
        private void runButton_Click(object sender, System.EventArgs e)
        {
            // Display the dialogue to initiate the background work.
            using (var waitDialogue = GetWaitDialogue())
            {
                waitDialogue.ShowDialog();
            }
        }
 
        private BackgroundWorkerForm GetWaitDialogue()
        {
            var dialogue = new BackgroundWorkerForm();
 
            // Only provide a ProgressChanged handler if the corresponding CheckBox is checked.
            if (reportProgressCheckBox.Checked)
            {
                dialogue = new BackgroundWorkerForm(BackgroundWorkerForm_DoWork,
                                                    BackgroundWorkerForm_ProgressChanged,
                                                    BackgroundWorkerForm_RunWorkerCompleted);
            }
            else
            {
                dialogue = new BackgroundWorkerForm(BackgroundWorkerForm_DoWork,
                                                    BackgroundWorkerForm_RunWorkerCompleted);
            }
 
            // Only display a Cancel button if the corresponding CheckBox is checked.
            dialogue.SupportsCancellation = allowCancellationCheckBox.Checked;
 
            return dialogue;
        }
    }
}