//------------------------------------------------------------------------------------
// <copyright file="BackgroundWorkerEx.cs" company="Citect"
//      Copyright (C) 2008 Citect Australia Pty Ltd
//      All rights reserved
// </copyright>
//------------------------------------------------------------------------------------
using System;
using System.Collections;
using System.Collections.Generic;
using System.Text;
using System.ComponentModel;
using System.Threading;

namespace Utilities
{
	/// <summary>
	/// Extended BackgroundWorker class that supports automatic progress tracking and reporting.
	/// </summary>
	public class BackgroundWorkerEx : BackgroundWorker
	{
		#region EventArgs

		/// <summary>
		/// Event args for the LogUpdated event.
		/// </summary>
		public class LogUpdatedEventArgs : EventArgs
		{
			private string _logTextToAppend;

			/// <summary>
			/// The log text to append.
			/// </summary>
			public string LogTextToAppend
			{
				get { return _logTextToAppend; }
			}

			public LogUpdatedEventArgs(string logTextToAppend)
			{
				_logTextToAppend = logTextToAppend;
			}
		}

		/// <summary>
		/// Event args for the ReportError event.
		/// </summary>
		public class ReportErrorEventArgs : EventArgs
		{
			private string _errorText;

			/// <summary>
			/// The log text to append.
			/// </summary>
			public string ErrorText
			{
				get { return _errorText; }
			}

			public ReportErrorEventArgs(string errorText)
			{
				_errorText = errorText;
			}
		}

		#endregion // EventArgs

		/// <summary>
		/// Keeps track of a sequence of operations specified by an initial number of steps, and
		/// updated when steps are completed.  
		/// </summary>
		private class Sequence
		{
			#region Private Fields -------------------------------------------------------

			private long totalSteps;
			private long stepsComplete;

			#endregion // Private Fields

			#region Constructors ---------------------------------------------------------

			/// <summary>
			/// Constructor for a new Sequence.
			/// </summary>
			/// <param name="totalSteps">The total number of steps involved in completing this sequence.</param>
			public Sequence(long totalSteps)
			{
				this.totalSteps = totalSteps;
				stepsComplete = 0;
			}

			#endregion // Constructors

			#region Properties -----------------------------------------------------------

			/// <summary>
			/// The current progress of this sequence.
			/// </summary>
			public int Progress
			{
				get
				{
					int progress = 100; // be consistent with IsComplete property (treat 0 total steps as complete)

					if (totalSteps > 0 && stepsComplete < totalSteps)
					{
						progress = (int)(100.0 / totalSteps * stepsComplete);
					}

					return progress;
				}
			}

			/// <summary>
			/// Returns whether all the steps in the sequence have been completed.
			/// </summary>
			public bool IsComplete
			{
				get
				{
					return (stepsComplete == totalSteps);
				}
			}

			/// <summary>
			/// The total number of steps required to complete this sequence.
			/// </summary>
			public long TotalSteps
			{
				get
				{
					return totalSteps;
				}
			}

			#endregion // Properties

			#region Public Methods -------------------------------------------------------

			/// <summary>
			/// Notifies the sequence that a single new step has been completed.
			/// </summary>
			public void StepCompleted()
			{
				StepsCompleted(1);
			}

			/// <summary>
			/// Notifies the sequence that one or more new steps have just been completed.
			/// </summary>
			/// <param name="numStepsJustCompleted">The number of new steps completed.</param>
			public void StepsCompleted(long numStepsJustCompleted)
			{
				if (stepsComplete + numStepsJustCompleted <= totalSteps)
				{
					stepsComplete += numStepsJustCompleted;	// normal case
				}
				else if (stepsComplete + numStepsJustCompleted > totalSteps)
				{
					stepsComplete = totalSteps;	// don't let us go past 100%
				}
				else if (stepsComplete + numStepsJustCompleted < 0)
				{
					stepsComplete = 0;	// don't let us go lower than 0%
				}
			}

			#endregion // Public Methods
		};

		#region Private Fields -------------------------------------------------------

		/// <summary>
		/// Stack to keep track of multiple sequences involved in this operation.
		/// </summary>
		private Stack<Sequence> operationStack;

		/// <summary>
		/// Stack to keep track of progress descriptions throughout this operation.
		/// </summary>
		private Stack<string> messageStack;

		/// <summary>
		/// Used to allow pausing/suspending and resuming of the worker thread.
		/// </summary>
		private ManualResetEvent locker;

		/// <summary>
		/// Flag indicating whether the worker thread is paused.
		/// </summary>
		private bool isPaused;

		#endregion // Private Fields

		#region Events

		/// <summary>
		/// Event handler to notify when the log is being updated.
		/// </summary>
		public event EventHandler<LogUpdatedEventArgs> LogUpdated;

		/// <summary>
		/// Event handler to notify when an error occurs.
		/// </summary>
		public event EventHandler<ReportErrorEventArgs> ReportError;

		/// <summary>
		/// Raises the LogUpdated event.
		/// </summary>
		/// <param name="e">An System.EventArgs that contains the event data.</param>
		//protected virtual void UpdateLog(LogUpdatedEventArgs e);

		#endregion // Events

		#region Constructors ---------------------------------------------------------

		/// <summary>
		/// Constructor for a new BackgroundWorkerEx.
		/// </summary>
		public BackgroundWorkerEx()
		{
			operationStack = new Stack<Sequence>();
			messageStack = new Stack<string>();
			locker = new ManualResetEvent(true);
		}

		#endregion // Constructors

		#region Properties -----------------------------------------------------------

		/// <summary>
		/// Flag indicating whether the worker thread is paused.
		/// </summary>
		public bool IsPaused
		{
			get { return isPaused; }
		}

		#endregion // Properties

		#region Public Methods -------------------------------------------------------

		/// <summary>
		/// Pauses the worker thread.
		/// </summary>
		public void Pause()
		{
			if (!IsPaused)
			{
				isPaused = true;
				locker.Reset();
			}
		}

		/// <summary>
		/// Resumes the worker thread.
		/// </summary>
		public void Resume()
		{
			if (IsPaused)
			{
				isPaused = false;
				locker.Set();
			}
		}

		/// <summary>
		/// Suspends the worker thread if the thread owner has requested it to pause.
		/// </summary>
		/// <remarks>This should only be called by the background worker thread itself.</remarks>
		public void PauseIfRequired()
		{
			locker.WaitOne();
		}

		/// <summary>
		/// Changes the progress bar style.
		/// </summary>
		/// <param name="style"></param>
		public void SetProgressStyle(bool progressIsIndeterminate)
		{
			base.ReportProgress(0, progressIsIndeterminate);
		}

		/// <summary>
		/// Method to notify that the log is to be updated.
		/// </summary>
		/// <param name="logText">New log text</param>
		public void UpdateLog(string logText)
		{
			if (LogUpdated != null)
			{
				LogUpdated(this, new LogUpdatedEventArgs(logText));
			}
		}

		/// <summary>
		/// Method to notify that an error occurred.
		/// </summary>
		/// <param name="errorText">Error text</param>
		public void NotifyError(string errorText)
		{
			if (ReportError != null)
			{
				ReportError(this, new ReportErrorEventArgs(errorText));
			}
		}

		/// <summary>
		/// Initiates the start of a new sequence within this operation.
		/// </summary>
		/// <param name="totalSteps">The total number of steps involved in this new sequence.</param>
		public void StartSequence(long totalSteps)
		{
			operationStack.Push(new Sequence(totalSteps));
			ReportSequencedProgress();
		}

		/// <summary>
		/// Causes the current sequence progress to go to 100% and therefore be removed from the stack
		/// of sequences involved in this operation.  
		/// </summary>
		public void StopSequence()
		{
			if (operationStack.Count > 0)
			{
				operationStack.Pop();

				if (GetProgress() == 100)
				{
					ReportSequencedProgress();
				}
			}
		}

		/// <summary>
		/// Signals that a step in the currently executing sequence has just been completed.
		/// </summary>
		public void StepCompleted()
		{
			StepsCompleted(1);
		}

		/// <summary>
		/// Signals that one or more steps in the currently executing sequence have just been completed.  
		/// </summary>
		/// <param name="numStepsJustCompleted"></param>
		public void StepsCompleted(int numStepsJustCompleted)
		{
			if (operationStack.Count > 0)
			{
				Sequence currentSequence = operationStack.Pop();
				currentSequence.StepsCompleted(numStepsJustCompleted);
				operationStack.Push(currentSequence);

				ReportSequencedProgress();
			}
		}

		/// <summary>
		/// Adds a new message onto the message stack.
		/// </summary>
		/// <param name="message">The progress message to be appended.</param>
		public void PushMessage(string message)
		{
			messageStack.Push(message);
			ReportSequencedProgress();
		}

		/// <summary>
		/// Removes the last message from the message stack.  
		/// </summary>
		public void PopMessage()
		{
			if (messageStack.Count > 0)
			{
				messageStack.Pop();
				ReportSequencedProgress();
			}
		}

		#endregion // Public Methods

		#region Private Methods ------------------------------------------------------

		/// <summary>
		/// Asks the task's background worker to update the UI's progress bar and message.  
		/// </summary>
		private void ReportSequencedProgress()
		{
			int progress = GetProgress();
			string message = GetMessage();

			base.ReportProgress(progress, message);
		}

		/// <summary>
		/// Retrieves the current overall progress of this operation, taking in account the progress
		/// of all sub-sequences.  
		/// </summary>
		/// <returns>An integer between 0 and 100.</returns>
		private int GetProgress()
		{
			float progress = 0.0f;

			Sequence[] operationArray = operationStack.ToArray();

			if (operationArray.Length > 0)
			{
				// go through backwards to calculate the current progress
				progress = operationArray[operationArray.Length - 1].Progress;

				for (int sequenceNum = operationArray.Length - 2; sequenceNum >= 0; sequenceNum--)
				{
					progress += operationArray[sequenceNum].Progress / operationArray[sequenceNum + 1].TotalSteps;
				}
			}

			return Convert.ToInt32(progress);
		}

		/// <summary>
		/// Retrieves the current progress message for this operation, taking into account the progress
		/// messages of all sub-sequences.  These are combined from left to right as they were pushed onto
		/// the message stack.  
		/// </summary>
		/// <returns>A string with the complete progress message</returns>
		private string GetMessage()
		{
			string message = "";

			string[] messageArray = messageStack.ToArray();

			// go through backwards to build the message string
			for (int messageNum = messageArray.Length - 1; messageNum >= 0; messageNum--)
			{
				message += messageArray[messageNum];
			}

			return message;
		}

		#endregion // Private Methods
	}
}