Added status reporting interface to provide a generalized interface for background processes to report their current status; tried to improve documentation of the Progression and RectanglePacker classes

git-svn-id: file:///srv/devel/repo-conversion/nusu@48 d2e56fa2-650e-0410-a79f-9358c0239efd

Source/Tracking/IStatusReporter.cs

@@ -0,0 +1,34 @@
+#region CPL License
+/*
+Nuclex Framework
+Copyright (C) 2002-2007 Nuclex Development Labs
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the IBM Common Public License as
+published by the IBM Corporation; either version 1.0 of the
+License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+IBM Common Public License for more details.
+
+You should have received a copy of the IBM Common Public
+License along with this library
+*/
+#endregion
+
+using System;
+using System.Collections.Generic;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Interface for processes that report their status</summary>
+  interface IStatusReporter {
+
+    /// <summary>Triggered when the status of the process changes</summary>
+    event EventHandler<StatusReportEventArgs> StatusChanged;
+
+  }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/Progression.cs

@@ -86,7 +86,7 @@ namespace Nuclex.Support.Tracking {
         //
         // We can *not* optimize this lock away since we absolutely must not create
         // two doneEvents -- someone might call .WaitOne() on the first one when only
-        // the second one is assigned to this.doneEvent and thus gets set in the end.
+        // the second one is references by this.doneEvent and thus gets set in the end.
         if(this.doneEvent == null) {
 
           lock(this) {

Source/Tracking/StatusReportEventArgs.cs

@@ -0,0 +1,51 @@
+#region CPL License
+/*
+Nuclex Framework
+Copyright (C) 2002-2007 Nuclex Development Labs
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the IBM Common Public License as
+published by the IBM Corporation; either version 1.0 of the
+License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+IBM Common Public License for more details.
+
+You should have received a copy of the IBM Common Public
+License along with this library
+*/
+#endregion
+
+using System;
+using System.Collections.Generic;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Event arguments for reporting a status to the subscriber</summary>
+  public class StatusReportEventArgs : EventArgs {
+
+    /// <summary>Initializes a new status report event arguments container</summary>
+    /// <param name="status">Status to report to the event's subscribers</param>
+    public StatusReportEventArgs(string status) {
+      this.status = status;
+    }
+
+    /// <summary>The currently reported status</summary>
+    /// <remarks>
+    ///   The contents of this string are up to the publisher of the event to
+    ///   define. Though it is recommended to report the status as a human-readable
+    ///   string, these strings might not in all cases be properly localized or
+    ///   suitable for display in a GUI.
+    /// </remarks>
+    public string Status {
+      get { return this.status; }
+    }
+
+    /// <summary>Reported status</summary>
+    private string status;
+
+  }
+
+} // namespace Nuclex.Support.Tracking