Changeset 8165 for trunk/sources/HeuristicLab.MainForm/3.3/Interfaces

Timestamp:

06/29/12 23:12:32 (12 years ago)

Author:

abeham

Message:

#1762: Some changes to progress handling, see the ticket for more details

File:

• trunk/sources/HeuristicLab.MainForm/3.3/Interfaces/IProgress.cs (modified) (1 diff)

trunk/sources/HeuristicLab.MainForm/3.3/Interfaces/IProgress.cs

@@ -21 +21 @@
 
 using System;
+using HeuristicLab.Common;
 
 namespace HeuristicLab.MainForm {
-  public interface IProgress {
-    string Status { get; set; }
-    double ProgressValue { get; set; }
+  public enum ProgressState { Started = 1, Canceled = 2, Finished = 3 };
 
-    void Finish();
-    void SignalSuccessfulCancelation();
+  public interface IProgress : IContent {
+    /// <summary>
+    /// Gets the currently associated status text with the progress.
+    /// </summary>
+    string Status { get; }
+    /// <summary>
+    /// Gets the currently associated progress value in the range (0;1].
+    ///  Values outside this range are permitted and need to be handled in some feasible manner.
+    /// </summary>
+    double ProgressValue { get; }
+    /// <summary>
+    /// Gets the current state of the progress. Every progress starts in state
+    /// Started and then becomes either Canceled or Finished.
+    /// If it is reused it may be Started again.
+    /// </summary>
+    ProgressState ProgressState { get; }
+    /// <summary>
+    /// Returns whether the operation can be canceled or not.
+    /// This can change during the course of the progress.
+    /// </summary>
+    bool CanBeCanceled { get; }
 
-    bool CancelRequested { get; set; }
+    /// <summary>
+    /// Requests the operation behind the process to cancel.
+    /// Check the !ProgressState property when the cancellation succeeded.
+    /// The corresponding event will also notify of a success.
+    /// </summary>
+    /// <exception cref="NotSupportedException">Thrown when cancellation is not supported.</exception>
+    /// <param name="timeoutMs">The operation is given a certain timeout to cancel. If the operation doesn't cancel in this time it will be forcibly closed.</param>
+    void Cancel(int timeoutMs);
 
-    event EventHandler Finished;
+    /// <summary>
+    /// The status text changed.
+    /// </summary>
     event EventHandler StatusChanged;
+    /// <summary>
+    /// The value of the progress changed. This is the (0;1] progress value from starting to finish. Values outside this range are permitted and need to be handled in some feasible manner.
+    /// </summary>
     event EventHandler ProgressValueChanged;
-    event EventHandler Canceled;
+    /// <summary>
+    /// The state of the progress changed. The handler is supposed to query the ProgressState property.
+    /// </summary>
+    event EventHandler ProgressStateChanged;
+    /// <summary>
+    /// The progress' ability to cancel changed.
+    /// </summary>
+    event EventHandler CanBeCanceledChanged;
+    /// <summary>
+    /// A cancelation is requested with a certain timeout (in ms) in which it should occur gracefully. If the timeout is surpassed, it should be forcibly canceled.
+    /// </summary>
+    event EventHandler<EventArgs<int>> CancelRequested;
   }
 }