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

Nuclex.Support (PC).csproj

@@ -241,6 +241,10 @@
       <XNAUseContentPipeline>false</XNAUseContentPipeline>
       <Name>ObservedWeightedProgression</Name>
     </Compile>
+    <Compile Include="Source\Tracking\IStatusReporter.cs">
+      <XNAUseContentPipeline>false</XNAUseContentPipeline>
+      <Name>IStatusReporter</Name>
+    </Compile>
     <Compile Include="Source\Tracking\ProgressionTracker.cs">
       <XNAUseContentPipeline>false</XNAUseContentPipeline>
       <Name>ProgressionTracker</Name>
@@ -275,6 +279,10 @@
       <Name>SetProgression.Test</Name>
       <DependentUpon>SetProgression.cs</DependentUpon>
     </Compile>
+    <Compile Include="Source\Tracking\StatusReportEventArgs.cs">
+      <XNAUseContentPipeline>false</XNAUseContentPipeline>
+      <Name>StatusReportEventArgs</Name>
+    </Compile>
     <Compile Include="Source\Tracking\WeightedProgression.cs">
       <XNAUseContentPipeline>false</XNAUseContentPipeline>
       <Name>WeightedProgression</Name>

Source/Packing/CygonRectanglePacker.cs

@@ -28,14 +28,14 @@ namespace Nuclex.Support.Packing {
   /// <summary>Packer using a custom algorithm by Markus 'Cygon' Ewald</summary>
   /// <remarks>
   ///   <para>
-  ///     Algorithm conceived by Markus Ewald (cygon at nuclex dot org), thought
+  ///     Algorithm conceived by Markus Ewald (cygon at nuclex dot org), though
   ///     I'm quite sure I'm not the first one to come up with it :)
   ///   </para>
   ///   <para>
   ///     The algorithm always places rectangles as low as possible in the packing
-  ///     area. So, for any new rectangle that is to be added into the packing area,
+  ///     area. So, for any new rectangle that is to be added, the packer has to
-  ///     the packer has to determine the X coordinate at which the rectangle can have
+  ///     determine the X coordinate at which the rectangle can have the lowest
-  ///     the lowest overall height without intersecting any other rectangles.
+  ///     overall height without intersecting any other rectangles.
   ///   </para>
   ///   <para>
   ///     To quickly discover these locations, the packer uses a sophisticated

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