Provided a common class for observable collections similar to what the .NET Framework 3.0 offers; ParentingCollection no longer requires the parent type to be a reference type; Laid the foundation for a new progress tracking framework that can be used to drive progress bars, loading screens and such

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

Nuclex.Support (PC).csproj

@@ -65,6 +65,10 @@
     <Reference Include="System.Xml" />
   </ItemGroup>
   <ItemGroup>
+    <Compile Include="Source\Collections\ObservableCollection.cs">
+      <XNAUseContentPipeline>false</XNAUseContentPipeline>
+      <Name>ObservableCollection</Name>
+    </Compile>
     <Compile Include="Source\Collections\UnintrusivePriorityQueue.cs">
       <XNAUseContentPipeline>false</XNAUseContentPipeline>
       <Name>UnintrusivePriorityQueue</Name>
@@ -139,6 +143,10 @@
       <XNAUseContentPipeline>false</XNAUseContentPipeline>
       <Name>Progression</Name>
     </Compile>
+    <Compile Include="Source\Tracking\ProgressionCollection.cs">
+      <XNAUseContentPipeline>false</XNAUseContentPipeline>
+      <Name>ProgressionCollection</Name>
+    </Compile>
     <Compile Include="Source\Tracking\ProgressUpdateEventArgs.cs">
       <XNAUseContentPipeline>false</XNAUseContentPipeline>
       <Name>ProgressUpdateEventArgs</Name>

Source/Collections/ObservableCollection.cs

@@ -0,0 +1,109 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+
+namespace Nuclex.Support.Collections {
+
+  /// <summary>Generic collection of progressions</summary>
+  public class ObservableCollection<ItemType> : Collection<ItemType> {
+
+    #region class ItemEventArgs
+
+    /// <summary>Arguments class for events that need to pass a progression</summary>
+    public class ItemEventArgs : EventArgs {
+
+      /// <summary>Initializes a new event arguments supplier</summary>
+      /// <param name="item">Item to be supplied to the event handler</param>
+      public ItemEventArgs(ItemType item) {
+        this.item = item;
+      }
+
+      /// <summary>Obtains the collection item the event arguments are carrying</summary>
+      public ItemType Item {
+        get { return this.item; }
+      }
+
+      /// <summary>Item that's passed to the event handler</summary>
+      private ItemType item;
+
+    }
+
+    #endregion // class ItemEventArgs
+
+    /// <summary>Raised when an item has been added to the collection</summary>
+    public event EventHandler<ItemEventArgs> ItemAdded;
+    /// <summary>Raised when an item is removed from the collection</summary>
+    public event EventHandler<ItemEventArgs> ItemRemoved;
+    /// <summary>Raised the collection is about to be cleared</summary>
+    public event EventHandler Clearing;
+
+    /// <summary>Removes all elements from the Collection</summary>
+    protected override void ClearItems() {
+      OnClearing();
+
+      base.ClearItems();
+    }
+
+    /// <summary>
+    ///   Inserts an element into the ProgressionCollection at the specified index
+    /// </summary>
+    /// <param name="index">
+    ///   The object to insert. The value can be null for reference types.
+    /// </param>
+    /// <param name="item">The zero-based index at which item should be inserted</param>
+    protected override void InsertItem(int index, ItemType item) {
+      base.InsertItem(index, item);
+
+      OnAdded(item);
+    }
+
+    /// <summary>
+    ///   Removes the element at the specified index of the ProgressionCollection
+    /// </summary>
+    /// <param name="index">The zero-based index of the element to remove</param>
+    protected override void RemoveItem(int index) {
+      ItemType item = base[index];
+
+      base.RemoveItem(index);
+
+      OnRemoved(item);
+    }
+
+    /// <summary>Replaces the element at the specified index</summary>
+    /// <param name="index">
+    ///   The new value for the element at the specified index. The value can be null
+    ///   for reference types
+    /// </param>
+    /// <param name="item">The zero-based index of the element to replace</param>
+    protected override void SetItem(int index, ItemType item) {
+      ItemType oldItem = base[index];
+
+      base.SetItem(index, item);
+
+      OnRemoved(oldItem);
+      OnAdded(item);
+    }
+
+    /// <summary>Fires the 'ItemAdded' event</summary>
+    /// <param name="item">Item that has been added to the collection</param>
+    protected virtual void OnAdded(ItemType item) {
+      if(ItemAdded != null)
+        ItemAdded(this, new ItemEventArgs(item));
+    }
+
+    /// <summary>Fires the 'ItemRemoved' event</summary>
+    /// <param name="item">Item that has been removed from the collection</param>
+    protected virtual void OnRemoved(ItemType item) {
+      if(ItemRemoved != null)
+        ItemRemoved(this, new ItemEventArgs(item));
+    }
+
+    /// <summary>Fires the 'Clearing' event</summary>
+    protected virtual void OnClearing() {
+      if(Clearing != null)
+        Clearing(this, EventArgs.Empty);
+    }
+
+  }
+
+} // namespace Nuclex.Support.Collections

Source/Collections/Parentable.cs

@@ -5,7 +5,7 @@ namespace Nuclex.Support.Collections {
 
   /// <summary>Base class for objects that can be parented to an owner</summary>
   /// <typeparam name="ParentType">Type of the parent object</typeparam>
-  public class Parentable<ParentType> where ParentType : class {
+  public class Parentable<ParentType> {
 
     /// <summary>Assigns a new parent to this instance</summary>
     internal void SetParent(ParentType parent) {

Source/Collections/ParentingCollection.cs

@@ -15,8 +15,7 @@ namespace Nuclex.Support.Collections {
   /// <typeparam name="ParentType">Type of the parent object to assign to items</typeparam>
   /// <typeparam name="ItemType">Type of the items being managed in the collection</typeparam>
   public class ParentingCollection<ParentType, ItemType> : Collection<ItemType>
-    where ItemType : Parentable<ParentType>
-    where ParentType : class {
+    where ItemType : Parentable<ParentType> {
 
     /// <summary>Reparents all elements in the collection</summary>
     /// <param name="parent">New parent to take ownership of the items</param>
@@ -30,7 +29,7 @@ namespace Nuclex.Support.Collections {
     /// <summary>Clears all elements from the collection</summary>
     protected override void ClearItems() {
       for(int index = 0; index < Count; ++index)
-        base[index].SetParent(null);
+        base[index].SetParent(default(ParentType));
 
       base.ClearItems();
     }
@@ -46,7 +45,7 @@ namespace Nuclex.Support.Collections {
     /// <summary>Removes an element from the collection</summary>
     /// <param name="index">Index of the element to remove</param>
     protected override void RemoveItem(int index) {
-      base[index].SetParent(null);
+      base[index].SetParent(default(ParentType));
       base.RemoveItem(index);
     }
 
@@ -70,7 +69,7 @@ namespace Nuclex.Support.Collections {
       if(disposeItems) {
 
         // Have the items do their cleanup work
-        Reparent(null);
+        Reparent(default(ParentType));
 
         // Dispose of all the items in the collection that implement IDisposable
         foreach(ItemType item in this) {

Source/Tracking/IAbortable.cs

@@ -0,0 +1,15 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Interface for abortable processes</summary>
+  public interface IAbortable {
+
+    /// <summary>Aborts the running process. Can be called from any thread.</summary>
+    void AsyncAbort();
+
+  }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/MultiProgression.cs

@@ -0,0 +1,12 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Nuclex.Support.Tracking {
+
+  public class MultiProgression<ProgressionType> : Progression
+    where ProgressionType : Progression {
+
+  }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/Operation.cs

@@ -0,0 +1,50 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Base class for observable operations running in the background</summary>
+  public abstract class Operation : Progression {
+
+    /// <summary>Possible outcomes of an operation</summary>
+    public enum Outcomes {
+      /// <summary>The operation has not ended yet</summary>
+      Pending,
+      /// <summary>The operation has succeeded</summary>
+      Success,
+      /// <summary>The operation has failed</summary>
+      Failure,
+    }
+/*
+    /// <summary>Begins executing the operation</summary>
+    public abstract void BeginExecute();
+
+    public virtual void Execute() {
+      try {
+        BeginExecute();
+        this.outcome = EndExecute();
+      }
+      catch(Exception exception) {
+         this.outcome = Outcomes.Failure;
+      }
+    }
+
+    /// <summary>Ends the </summary>
+    public virtual Outcomes EndExecute() {
+      WaitHandle.WaitOne();
+
+      return this.outcome;
+    }
+
+    /// <summary>The Outcome of the operation when it has finished</summary>
+    public Outcomes Outcome {
+      get { return this.outcome; }
+    }
+
+    /// <summary>Outcome of the operation</summary>
+    protected Outcomes outcome;
+*/
+  }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/ProgressUpdateEventArgs.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Event arguments for a progress update notification</summary>
+  public class ProgressUpdateEventArgs : EventArgs {
+
+    /// <summary>Initializes the progress update informations</summary>
+    /// <param name="progress">Achieved progress ranging from 0.0 to 1.0</param>
+    public ProgressUpdateEventArgs(float progress) {
+      this.progress = progress;
+    }
+
+    /// <summary>Currently achieved progress</summary>
+    public float Progress {
+      get { return this.progress; }
+    }
+
+    /// <summary>Achieved progress</summary>
+    protected float progress;
+
+  }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/Progression.cs

@@ -0,0 +1,128 @@
+using System;
+using System.Threading;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Base class for actions that give an indication of their progress</summary>
+  /// <remarks>
+  ///   <para>
+  ///     By encapsulating long-running operations which will ideally be running in
+  ///     a background thread in a class that's derived from Progression you can wait
+  ///     for the completion of the operation and receive feedback on the achieved
+  ///     progress. This is useful for displaying a progress bar, loading screen or
+  ///     some means of entertaining the user while he waits for the operation to
+  ///     complete. It is also possible to register callbacks which will be fired once
+  ///     the progression has ended.
+  ///   </para>
+  ///   <para>
+  ///     This class deliberately does not provide an Execute() or similar method to
+  ///     clearly seperate the initiation of an operation from just monitoring it.
+  ///     By omitting an Execute() method, it also becomes possible to construct a
+  ///     progression just-in-time when it is explicitely asked for.
+  ///   </para>
+  /// </remarks>
+  public abstract class Progression {
+
+    #region class EndedDummyProgression
+
+    /// <summary>Dummy progression which always is in the 'ended' state</summary>
+    internal class EndedDummyProgression : Progression {
+
+      /// <summary>Initializes a new ended dummy progression</summary>
+      public EndedDummyProgression() {
+        OnAsyncEnded();
+      }
+
+    }
+
+    #endregion // class EndedDummyProgression
+
+    /// <summary>A dummy progression that's always in the 'ended' state</summary>
+    /// <remarks>
+    ///   Useful if an operation is already complete when it's being asked for or
+    ///   when a progression that's lazily created is accessed after the original
+    ///   operation has ended already.
+    /// </remarks>
+    public static readonly Progression EndedDummy = new EndedDummyProgression();
+
+    /// <summary>will be triggered to report when progress has been achieved</summary>
+    public event EventHandler<ProgressUpdateEventArgs> AsyncProgressUpdated;
+
+    /// <summary>Will be triggered when the progression has ended</summary>
+    public event EventHandler AsyncEnded;
+
+    /// <summary>Whether the progression has ended already</summary>
+    public virtual bool Ended {
+      get { return ended; }
+    }
+
+    /// <summary>WaitHandle that can be used to wait for the progression to end</summary>
+    public WaitHandle WaitHandle {
+      get {
+        lock(this) {
+
+          // The WaitHandle will only be created when someone asks for it!
+          if(this.doneEvent == null)
+            this.doneEvent = new ManualResetEvent(this.ended);
+
+        }
+
+        return this.doneEvent;
+      }
+    }
+
+    /// <summary>Fires the progress update event</summary>
+    /// <param name="progress">Progress to report (ranging from 0.0 to 1.0)</param>
+    /// <remarks>
+    ///   Informs the observers of this progression about the achieved progress.
+    /// </remarks>
+    protected virtual void OnAsyncProgressUpdated(float progress) {
+      OnAsyncProgressUpdated(new ProgressUpdateEventArgs(progress));
+    }
+
+    /// <summary>Fires the progress update event</summary>
+    /// <param name="eventArguments">Progress to report (ranging from 0.0 to 1.0)</param>
+    /// <remarks>
+    ///   Informs the observers of this progression about the achieved progress.
+    ///   Allows for classes derived from the Progression class to easily provide
+    ///   a custom event arguments class that has been derived from the
+    ///   Progression's ProgressUpdateEventArgs class.
+    /// </remarks>
+    protected virtual void OnAsyncProgressUpdated(ProgressUpdateEventArgs eventArguments) {
+      EventHandler<ProgressUpdateEventArgs> copy = AsyncProgressUpdated;
+      if(copy != null)
+        copy(this, eventArguments);
+    }
+
+    /// <summary>Fires the AsyncEnded event</summary>
+    /// <remarks>
+    ///   This event should be fired by the implementing class when its work is completed.
+    ///   It's of no interest to this class whether the outcome of the process was successfull
+    ///   or not, the outcome and results of the process taking place need to be communicated
+    ///   seperately.
+    /// </remarks>
+    protected virtual void OnAsyncEnded() {
+      lock(this) {
+        ended = true;
+
+        if(this.doneEvent != null)
+          this.doneEvent.Set();
+      }
+
+      EventHandler copy = AsyncEnded;
+      if(copy != null)
+        copy(this, EventArgs.Empty);
+    }
+
+    /// <summary>Event that will be set when the progression is completed</summary>
+    /// <remarks>
+    ///   This event is will only be created when it is specifically asked for using
+    ///   the WaitHandle property.
+    /// </remarks>
+    private volatile ManualResetEvent doneEvent;
+    /// <summary>Whether the operation has completed yet</summary>
+    private volatile bool ended;
+
+  }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/ProgressionCollection.cs

@@ -0,0 +1,16 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+
+using Nuclex.Support.Collections;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Non-generic version of the progression collection</summary>
+  public class ProgressionCollection : ProgressionCollection<Progression> { }
+
+  /// <summary>Generic collection of progressions</summary>
+  public class ProgressionCollection<ProgressionType>
+    : ObservableCollection<Progression> where ProgressionType : Progression { }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/ThreadedMethodOperation.cs

@@ -0,0 +1,10 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Nuclex.Support.Tracking {
+
+  public class ThreadedMethodOperation : Operation {
+  }
+
+} // namespace Nuclex.Support.Tracking