using System;
using System.Collections.Generic;
using Nuclex.Support.Tracking;
namespace Nuclex.Support.Services.ProgressTracking {
/// Allows application-wide tracking of progress
interface IProgressTrackingService {
/// Tracks the progress of the specified transaction
///
/// Transaction whose progress will be tracked
///
///
/// Identifier unique to the tracked background process. Can be null.
///
///
///
/// Using the process identifier allows you to track the progress of multiple
/// transactions that are working independently of each other. This could,
/// for example, result in multiple progress bars being displayed in a GUI.
/// The global progress always is a combination of all transactions tracked
/// by the service.
///
///
/// A good analogy for this might be a download manager which uses several
/// threads to download multiple sections of a file at the same time. You
/// want a progress bar per file, but not one for each downloading thread.
/// Specifying the name object as a process identifer, all transactions
/// belonging to the same file would be merged into a single progress source.
///
///
/// The process identifier can be a string or any object. Note however that
/// as common practice, this object's ToString() method should return
/// something reasonable, like "Downloading xy.txt". Localization can be
/// achieved by implementing an interface (eg. ILocalizableToString) which
/// provides a string and some parameters - or you could return the already
/// translated versions of the string if you prefer to have localized versions
/// of internal assemblies.
///
///
void Track(Transaction transaction, object processIdentifier);
/// Tracks the progress of the specified transaction
///
/// Transaction whose progress will be tracked
///
///
/// Tracks the transaction as if it was added with the process identifier
/// set to null.
///
void Track(Transaction transaction);
/// Stops tracking the specified transaction
/// Transaction that will no longer be tracked
///
/// Untracking a transaction is optional. The service will automatically
/// remove finished transactions from its list of tracked transactions. Calling
/// this method is only required if you drop a transaction in a way that
/// prevents its AsyncEnded event from being fired (eg. by not executing it
/// at all, dispite adding it to the progress tracking service).
///
void Untrack(Transaction transaction);
}
} // namespace Nuclex.Support.DependencyInjection.ProgressTracking