Enhances a standard ProgressBar with progress messages that appear sequentially beneath the bar, to provide useful feedback during a lengthy operation.

For a list of all members of this type, see ProgressBarMessager Members.

System.Object
   MarshalByRefObject
      Component
         Control
            ScrollableControl
               ContainerControl
                  UserControl
                     ProgressBarMessager

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Remarks

This control is composed of a standard ProgressBar, a Cancel button that allows the user to signal to your application to cancel the lengthy operation being monitored, and a panel that displays a message corresponding to each step of the ProgressBar. Typical operation should first invoke Reset() followed by a call to ReportInitialMessage() with your first message. This displays your initial message just below the ProgressBar with a small green arrow preceding it, indicating it is the current step being executed. Subsequent messageses should be sent to the PerformStep() method. The first such message changes the arrow in front of the first message to a check and optionally adds an elapsed time for that step. It then displays the second message with an arrow indicating that it is now the step being executed. Subsequent calls to PerformStep() repeat this process. Completion of your final step should be indicated by passing a null to PerformStep().

As you add messages the message panel (and therefore the ProgressBarMessager) expands vertically to contain a property-selectable number of messages (10 by default). Messages beyond that count cause the panel to effectively scroll messages.

The Cancel button provides a simple mechanism for the user to signal to you to cancel the lengthy operation in progress. All it does, though, is set the Cancelled property. It is up to your code to poll it and take appropriate action.

Since CleanCode 0.9.21.

Example

Here is a complete example to wire up the ProgressBarMessager on a dedicated form. Some key points of the sample code:

• The form title is set to the IDLE_TITLE when idle, and the RUN_TITLE during execution. The idle state is entered in 3 conditions: at startup, upon your indication of a final step (PerformStep(null)), or upon the user pressing Cancel.
• The form is centered on top of the parent window upon initial display as long as the user has not manually moved it; see ProgressBarForm_VisibleChanged.
• If the user presses the Cancel button a CancelledException is thrown that you need to handle; see UpdateProgress.
• The exposed methods of this form are: ReportInitialMessage, UpdateProgress, and FinishLastMessage. You must wire these up to your main application.
• The code insures this form is the top window once it opens; see ReportInitialMessage.

public partial class ProgressBarForm : Form
{

[DllImport("user32.dll")]
public static extern bool SetForegroundWindow(IntPtr hWnd);

private const string RUN_TITLE = "Processing... please wait";
private const string IDLE_TITLE = "My Progress Monitor";

private Form parent;

public ProgressBarForm(Form parent)
{
    InitializeComponent();
    this.parent = parent;
    progressBarMessager.Reset();
    Text = IDLE_TITLE;
}

private void ProgressBarForm_VisibleChanged(object sender, EventArgs e)
{
    if (Visible && !movedByUser)
    {
        Move -= new EventHandler(ProgressBarForm_Move);
        Location = new Point(
            Math.Max(0, (parent.Location.X + (parent.Width - Width) / 2)),
            Math.Max(0, (parent.Location.Y + (parent.Height - Height) / 2)));
        Move += new EventHandler(ProgressBarForm_Move);
        Refresh();
    }
}

private void ProgressBarForm_Move(object sender, EventArgs e)
{
    movedByUser = true;
}

public void ReportInitialMessage(string message)
{
    progressBarMessager.Reset();
    Text = RUN_TITLE;
    if (!Visible) { Show(); }
    // Also need to bring it to the foreground if buried!
    SetForegroundWindow(Handle);
    progressBarMessager.ReportInitialMessage(message);
    Refresh();
}

public void UpdateProgress(string message)
{
    Application.DoEvents();
    if (progressBarMessager.Cancelled)
    {
        Hide();
        Text = IDLE_TITLE;
        throw new CancelledException();
    }
    progressBarMessager.PerformStep(message);
    Refresh();
}

public void FinishLastMessage()
{
    Application.DoEvents();
    progressBarMessager.PerformStep(null);
    Refresh();
    Hide();
    Text = IDLE_TITLE;
}

}

public class CancelledException : ApplicationException
{
    // Use the default ApplicationException constructors
    public CancelledException() : base() { }
    public CancelledException(string s) : base(s) { }
    public CancelledException(string s, Exception ex) : base(s, ex) { }
}

Requirements

Namespace: CleanCodeControls.Forms

Assembly: CleanCodeControls (in CleanCodeControls.dll)

See Also

ProgressBarMessager Members | CleanCodeControls.Forms Namespace

---