using System;
using System.Windows.Forms;

namespace PaintDotNet
{
    public interface IProgressEvents<TItemInfo>
    {
        /// <summary>
        /// This method is called at the very beginning of the operation.
        /// </summary>
        /// <param name="owner">
        /// If the operation has a modal window open, this represents it. Otherwise, this is null and you should 
        /// use your own current modal window.</param>
        /// <param name="callWhenUIShown">
        /// You must call this method after initializing any UI you want to display. 
        /// If you will not be displaying UI, you must call this anyway.</param>
        /// <param name="cancelSink">
        /// An object that can be used to cancel the operation at any time after callWhenUIShown is invoked, 
        /// and any time before EndOperation() is called.
        /// </param>
        /// <remarks>
        /// This method must not return until EndOperation() is called. Note that EndOperation() will
        /// be called from a separate thread. 
        /// </remarks>
        void BeginOperation(IWin32Window owner, EventHandler callWhenUIShown, ICancelable cancelSink);

        /// <summary>
        /// Called to report the total number of work items that are part of the operation.
        /// </summary>
        /// <param name="itemCount">The total number of work items that are part of the operation.</param>
        void SetItemCount(int itemCount);

        /// <summary>
        /// Called to change which work item of the operation is in progress.
        /// </summary>
        /// <param name="itemOrdinal"></param>
        /// <remarks>
        /// This method is called after BeginOperation() but before BeginItem(),
        /// or after EndItem() but before BeginItem(). 
        /// </remarks>
        void SetItemOrdinal(int itemOrdinal);

        /// <summary>
        /// Called to report information about the current work item.
        /// </summary>
        /// <param name="itemInfo">Operation-dependent information about the current work item.</param>
        void SetItemInfo(TItemInfo itemInfo);

        /// <summary>
        /// Reports the total number of work units that are involved in completing the current work item.
        /// </summary>
        /// <param name="totalWork">The total number of work units that comprise the current work item.</param>
        void SetItemWorkTotal(long totalWork);

        /// <summary>
        /// Called when a work item is starting.
        /// </summary>
        /// <param name="itemName"></param>
        void BeginItem();

        /// <summary>
        /// Reports the total amount of progress for the current work item.
        /// </summary>
        /// <param name="totalProgress">The total number of work units that have completed for the current work item.</param>
        void SetItemWorkProgress(long totalProgress);

        /// <summary>
        /// Called when there is an error while completing the current work item.
        /// </summary>
        /// <param name="ex">The exception that was encountered while completing the current work item.</param>
        /// <returns>You must return a value from the ItemFailedUserChoice enumeration.</returns>
        WorkItemFailureAction ReportItemFailure(Exception ex);

        /// <summary>
        /// Called after a work item is finished.
        /// </summary>
        void EndItem(WorkItemResult result);

        /// <summary>
        /// Called after the operation is complete.
        /// </summary>
        /// <param name="result">Indicates whether the operation finished, or was cancelled.</param>
        /// <remarks>
        /// Even if the operation finished, individual work items may not have succeeded.
        /// You will need to track the data passed to to EndItem() ReportItemError() to be able to monitor this.
        /// You must close any UI shown during BeginOperation(), and then return from that method.
        /// </remarks>
        void EndOperation(OperationResult result);
    }
}