Monday, April 7, 2008

Generic progress dialog

Quite often I have to perform long operations in an application and then I want to show a progress bar to the user that he can see that the application is working and how long it will take. My requirements for the progress bar dialog are:
  • it should be generic and therefore not be tied with the work which has to be done
  • it should not block or freeze the main application
  • the user must have the possibility to abort the operation
It turned out that it is quite challenging to meet all these requirements. With different approaches I had different problems and could not fulfill my requirements. For example there was a version where the progress dialog was not updated or the user could not abort the operation. After some trying I found a quite usable solution. The main application uses a backgroundworker to do the work; this has the advantage that the computation is done in a different thread and the backgroundwoker provides cancel and progress notification. My progress bar dialog is started also in its own thread to make sure that its graphics are not blocked and updated when needed. With this "architecture" it is even possible that the main application performs some other operations while a heavy work is done and the progress shown to the user. The progress dialog provides all its functionalities through static methods which access a "private singleton". This means that the developer never gets an instance of the progress dialog and that at most one instance of the progress dialog exists. To notify the main application about the cancel event I used an event with a delegate. Therefore the main application can do what it wants when the user presses cancel.
When the user presses cancel then a message box is shown which asks if he really wants to abort. The nice thing with this implementation is that while this message box is shown the computation goes on and is not blocked.

The following code shows the progress bar, sets the title and message, assigns a method to the cancel event and starts the computation if the background worker is not already working:
if (!this.backgroundWorker.IsBusy)
this.Enabled = false; /*lock the main application*/
ProgressDialog.SetTitle("this is the title");
ProgressDialog.SetMessage("I am the message for the very long task. Please be patient and wait...");
ProgressDialog.CancelEvent += new ProgressDialog.CancelEventHandler(pd_CancelEvent);

Important is to set the cancellation property of the background worker to true; this is best done in the designer or in the constructor of the main form:
this.backgroundWorker.WorkerSupportsCancellation = true;

The computation is done in the do_work event of the background worker. Here is important that in the loop the check for the cancel event is done because otherwise the backgroundworker will not stop on cancel. To update the progress bar it is enough to call the SetValue method of the progress dialog. This is only a very stupid operation for demonstration:
private void backgroundWorker_DoWork(object sender, DoWorkEventArgs e)
for (int i = 0; i < max; i++)
/*this check is needed in order to abort the operation if the user has clicked on cancel*/
if (this.backgroundWorker.CancellationPending)
e.Cancel = true;

ProgressDialog.SetValue(i); /*update the value*/

Another thing that I have to mention. In debug mode there occurs always an exception which says that this operations are not thread safe. Till now I did not had the time to look how I can make this code thread safe, but as soon as I have a thread safe version (if one exists) I will post it.
I finally had the time to learn how to write thread safe method calls. The code below shows how it is done. First you have to check if the mehtod was called by a Thread other than the own Thread. This does the property "InvokeRequired". If so a delegate is created and the method is called with "Invoke".
public static void SetTitle(string title)
if (instance.InvokeRequired) /*if another thread called this method*/
SetTitleCallback s = new SetTitleCallback(SetTitle);
instance.Invoke(s, title);
instance.Text = title;

You can download the full demo project here.

Finally a screenshot on how my progress bar dialog looks like:

If you have suggestions, ideas or You know how to improve this code or if You have a thread save version You are welcome to post a comment.


jeff said...

I find that I get an invocationTargetException when the job finishes and it tries to close the progress dialog. Anyone else having this problem?

Manfred said...

Hi jeff,
thanks for your comment. You are rights I also get a ThreadAbortException. I now corrected it and it should work. At least on my computer is works :-)
You find the new project on the same link.
If you find other problems, let me know about them...

Tobias said...

Hi Manfred,

thanks for that code.
Unfortunately the StartPostion = CenterParent is ignored.
Do you have an idea to work a round?