using System;

namespace Toolbox.Docking.Api.Control
{
    /// <summary>
    /// Provides basic workflow control as well as 
    /// access to Toolbox services. 
    /// </summary>
    public interface ITbInitTask :  IDisposable
    {
        #region Progress
        /// <summary>
        /// Upper bound for progress. 
        /// </summary>
        int MaxProgress { get; }
        /// <summary>
        /// Current progress position. 
        /// </summary>
        int ProgressLevel { get; }
        /// <summary>
        /// Returns whether the progress is a meaningful one or an indefinite(rolling) type.
        /// </summary>
        bool MeaningfulProgress { get; }
        /// <summary>
        /// Call this to signify that an item is done and to update the task progress (increment ProgressLevel).
        /// </summary>
        void WorkItemDone();

        #endregion

        #region information
        /// <summary>
        /// Time stamp for the task start.
        /// </summary>
        DateTime StartedAt { get; }

        /// <summary>
        /// Caption for the Task. This is used for UI purposes.
        /// </summary>
        string Caption { get; }

        /// <summary>
        /// Status for the Task. This is used for UI purposes.
        /// </summary>
        string Status { get; set; }

        #endregion

        /// <summary>
        /// Flow control token. 
        /// </summary>
        ITbCancellationToken TbToken{ get; }

        /// <summary>
        /// Log exceptions that might have been thrown during a task's execution.
        /// </summary>
        /// <param name="exception">
        /// The logged exception.
        /// </param>
        void LogException(Exception exception);

        /// <summary>
        /// A catalog of available Toolbox objects and services.
        /// </summary>
        ITbObjectCatalog ObjectCatalog { get; }

        /// <summary>
        /// Creates a sub-task. Tasks should be broken down in smaller tasks in order to better 
        /// inform the user how a task progresses.
        /// </summary>
        /// <param name="subTaskCaption">The caption for the sub-task.</param>
        /// <param name="subTaskMaxProgress">The number of items for the task.</param>
        /// <param name="meaningfulProgress">Specify whether this will be a meaningful progress or an infinite progress.</param>
        /// <returns>
        /// The resulting sub-task.
        /// </returns>
        ITbInitTask CreateSubTask(string subTaskCaption, int subTaskMaxProgress, bool meaningfulProgress);
    }
}