TimeProgressBar - Display time progress

• Download project - 28.3 KB  

Introduction

The TimeProgressBar allows you to display the time of a session. While ProgressBar control can be used for this task, I wanted a control that will display more information about the progress - the time passed since the start of the session, the time left to the end of the session and the percent of passed time from the total time of the session.

Using the Control

The control displays a progress bar. This bar is colored with TimeMainColor and represents the total time of the session. The progress is indicated by a indicator rectangle which is colored with TimePassColor. This rectangle is overlapped with the progress bar and located in the its left side. The size of this rectangle will be determined by the percent of passed time from the total time of the session (i.e : if 60% of session has passed, the indicator rectangle width will be 60% of the width of the main rectangle).

The control also displays three properties the session:

• In the left, the time passed since the start of the session
• In the center, the percent of passed time from the total time of the session
• In the right, the time left to the end of the session

The TimeInside property determines where those properties will be displayed. If true, the times will be displayed inside the progress bar. otherwise, times will displayed outside the progress bar.

To start monitor the progress of a new session, use one of the Start methods.

• The Start(TimeSpan duration) will monitor the time progress of the session from the time of its invocation until the duration time has passed.
• The Start(DateTime startTime,DateTime endTime) will display progress of a session that start in startTime and ends in endTime.

To display the progress of the session and update the control properties (TimeLeft,TimeLeftPercent, TimePass,TimePassPercent), the Update method should be called. The control will call it each second if AutoUpdate is true. Otherwise the user is responsible for updating the contol.

The following events will be raised by the control:

• The OnStart event is raised when the session has started
• The OnTick event is raised when the session has not ended yet and control has been updated. If AutoUpdate is true this event is raised each second.
• The OnEnd event is raised when the session has ended

Please note that those events will call the intrested parties in different thread from the gui thread so if you want to update the gui controls, you should use the Invoke method.

The Demo programs

The AutoUpdate demo program

This demo program show how to use the control with the default values (AutoUpdate is true). When the form is loaded, we will connect the event handlers. and set the session time to 20 seconds :

    //-------------------------------------------------------------------------
    protected override void OnLoad(EventArgs e) {
      base.OnLoad(e);
      winTimeProgresBar.OnStart += new EventHandler(this.winTimeProgresBar_OnStart);
      winTimeProgresBar.OnTick  += new EventHandler(this.winTimeProgresBar_OnTick);
      winTimeProgresBar.OnEnd   += new EventHandler(this.winTimeProgresBar_OnEnd);

      winTimeProgresBar.Start(new TimeSpan(0,0,20));
    }

The handlers will display the appreciate message about the event. Please note that Invoke is used as the handlers will not be called in the GUI thread.

    //-------------------------------------------------------------------------
    private void winTimeProgresBar_OnStart(object sender,EventArgs e) {
      Invoke(new AppendTextProc(AppendText),"OnStart");
    }
    //-------------------------------------------------------------------------
    private void winTimeProgresBar_OnEnd(object sender,EventArgs e) {
      Invoke(new AppendTextProc(AppendText), "OnEnd");
    }
    //-------------------------------------------------------------------------
    private void winTimeProgresBar_OnTick(object sender,EventArgs e) {
      Invoke(new AppendTextProc(AppendText),"OnTick");
    }    
    //-------------------------------------------------------------------------
    private delegate void AppendTextProc(string msg);
    private void AppendText(string prefix) {
      string ss = string.Format("{0,-8} : {1:D2}%\r\n",prefix,winTimeProgresBar.TimePassPercent);
      winText.AppendText(ss);
    }
    //-------------------------------------------------------------------------

The NoAutoUpdate demo program

While setting AutoUpdate to true is convenient, sometimes you may want that the other source will be responsible for updating the control. In this case, we should set AutoUpdate to false. In this demo, we will create a new timer the will responsible for updating the control.

    //-------------------------------------------------------------------------
    protected override void OnLoad(EventArgs e) {
      base.OnLoad(e);
      winTimeProgresBar.OnStart += new System.EventHandler(this.winTimeProgresBar_OnStart);
      winTimeProgresBar.OnTick  += new System.EventHandler(this.winTimeProgresBar_OnTick);
      winTimeProgresBar.OnEnd   += new System.EventHandler(this.winTimeProgresBar_OnEnd);
      winTimeProgresBar.AutoUpdate = false;
      winTimeProgresBar.Start(new TimeSpan(0,0,20));
    }

The handlers will display the appreciate message about the event. The OnStart handler will create the timer. The timer will be destroyed by OnEnd handler.

    //-------------------------------------------------------------------------
    private void winTimeProgresBar_OnStart(object sender,EventArgs e) {
      Invoke(new AppendTextProc(AppendText),"OnStart");
      _timer = new System.Threading.Timer(
        _ => winTimeProgresBar.Update() , null, new TimeSpan(),new TimeSpan(0,0,1)
      );
    }
    //-------------------------------------------------------------------------
    private void winTimeProgresBar_OnEnd(object sender,EventArgs e) {
      Invoke(new AppendTextProc(AppendText), "OnEnd");
      _timer.Dispose();
    }
    //-------------------------------------------------------------------------
    private void winTimeProgresBar_OnTick(object sender,EventArgs e) {
      Invoke(new AppendTextProc(AppendText),"OnTick");
    }
    //-------------------------------------------------------------------------
    private delegate void AppendTextProc(string msg);
    private void AppendText(string prefix) {
      string ss = string.Format("{0,-8} : {1:D2}%\r\n",prefix,winTimeProgresBar.TimePassPercent);
      winText.AppendText(ss);
    }
    //-------------------------------------------------------------------------

History

• Version 1 [06.2012]