universaleditor/editor-legacy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added comments and documentation

Browse Source
This commit is contained in:
Michael Becker 2014-12-01 15:33:39 -05:00
parent d413f9f415
commit 66fa80b1c0
6 changed files with 219 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
CSharp/Libraries/UniversalEditor.Core/Accessor.cs
View File

@ -7,25 +7,51 @@ using System.Diagnostics;
namespace UniversalEditor
{
/// <summary>
/// Provides the ability to access a <see cref="DataFormat" />-agnostic stream. <see cref="CustomOption" />s for
/// import and export may be used to allow the interactive user to specify <see cref="Accessor" />-specific
/// parameters.
/// </summary>
[DebuggerNonUserCode()]
public abstract class Accessor : References<AccessorReference>
{
/// <summary>
/// Creates or returns an existing <see cref="ReferencedBy" /> object referring to this <see cref="References" /> object.
/// </summary>
/// <returns>A <see cref="ReferencedBy" /> object that can be used to create additional instances of this <see cref="References" /> object.</returns>
public virtual AccessorReference MakeReference()
{
return new AccessorReference(this.GetType());
}
/// <summary>
/// Creates a new instance of this <see cref="Accessor" /> and initializes the associated
/// <see cref="Reader" /> and <see cref="Writer" />.
/// </summary>
public Accessor()
{
mvarReader = new Reader(this);
mvarWriter = new Writer(this);
}
/// <summary>
/// Gets or sets the length of the data being accessed, if possible.
/// </summary>
public abstract long Length { get; set; }
/// <summary>
/// Gets the position within the underlying stream, if possible.
/// </summary>
/// <returns>The position within the underlying stream</returns>
protected abstract long GetPosition();
/// <summary>
/// Gets or sets the position within the underlying stream, if possible.
/// </summary>
public virtual long Position { get { return GetPosition(); } set { Seek(value, SeekOrigin.Begin); } }
/// <summary>
/// Determines how many bytes are remaining to be read from the underlying stream, if possible.
/// </summary>
public long Remaining
{
get
@ -36,13 +62,45 @@ namespace UniversalEditor
}
}
public void Seek(int length, SeekOrigin position)
/// <summary>
/// Sets the position within the underlying stream based on the given relative position and origin.
/// </summary>
/// <param name="offset">The location within the underlying stream relative to the given <see cref="SeekOrigin" />.</param>
/// <param name="origin">The reference point from where to seek.</param>
public void Seek(int offset, SeekOrigin origin)
{
Seek((long)length, position);
Seek((long)offset, origin);
}
public abstract void Seek(long length, SeekOrigin position);
/// <summary>
/// Sets the position within the underlying stream based on the given relative position and origin.
/// </summary>
/// <param name="offset">The location within the underlying stream relative to the given <see cref="SeekOrigin" />.</param>
/// <param name="origin">The reference point from where to seek.</param>
public abstract void Seek(long offset, SeekOrigin origin);
/// <summary>
/// Reads the specified amount of bytes from the underlying stream into the specified buffer starting at the
/// specified offset.
/// </summary>
/// <param name="buffer">The buffer into which to read data.</param>
/// <param name="start">The position in the buffer from which to start copying data.</param>
/// <param name="count">The number of bytes to read from the underlying stream.</param>
/// <returns>
/// The number of bytes actually read from the underlying stream. This may differ from the requested amount
/// due to encountering the end of stream or a network connection error.
/// </returns>
protected internal abstract int ReadInternal(byte[] buffer, int start, int count);
/// <summary>
/// Writes the specified amount of bytes to the underlying stream from the specified buffer starting at the
/// specified offset.
/// </summary>
/// <param name="buffer">The buffer from which to write data.</param>
/// <param name="start">The position in the buffer from which to start copying data.</param>
/// <param name="count">The number of bytes to write to the underlying stream.</param>
/// <returns>
/// The number of bytes actually written to the underlying stream. This may differ from the requested amount
/// due to lack of disk space or a network connection error.
/// </returns>
protected internal abstract int WriteInternal(byte[] buffer, int start, int count);
internal virtual void FlushInternal()
@ -50,8 +108,14 @@ namespace UniversalEditor
}
private bool mvarIsOpen = false;
/// <summary>
/// Determines whether this <see cref="Accessor" /> is currently open.
/// </summary>
public bool IsOpen { get { return mvarIsOpen; } protected set { mvarIsOpen = value; } }
/// <summary>
/// Opens this <see cref="Accessor" />.
/// </summary>
public void Open()
{
if (mvarIsOpen) return;
@ -59,6 +123,10 @@ namespace UniversalEditor
OpenInternal();
mvarIsOpen = true;
}
/// <summary>
/// Closes this <see cref="Accessor" />, making the underlying stream available to be re-opened by another
/// <see cref="Accessor" />.
/// </summary>
public void Close()
{
if (!mvarIsOpen) return;
@ -67,7 +135,13 @@ namespace UniversalEditor
mvarIsOpen = false;
}
/// <summary>
/// The internal implementation of the <see cref="Open" /> command.
/// </summary>
protected abstract void OpenInternal();
/// <summary>
/// The internal implementation of the <see cref="Close" /> command.
/// </summary>
protected abstract void CloseInternal();
private Encoding mvarDefaultEncoding = Encoding.Default;
@ -77,18 +151,35 @@ namespace UniversalEditor
public Encoding DefaultEncoding { get { return mvarDefaultEncoding; } set { mvarDefaultEncoding = value; } }
private Reader mvarReader = null;
/// <summary>
/// A <see cref="Reader" /> which reads from the underlying stream of this <see cref="Accessor" />.
/// </summary>
public Reader Reader { get { return mvarReader; } }
private Writer mvarWriter = null;
/// <summary>
/// A <see cref="Reader" /> which writes to the underlying stream of this <see cref="Accessor" />.
/// </summary>
public Writer Writer { get { return mvarWriter; } }
/// <summary>
/// The title of this <see cref="Accessor" />.
/// </summary>
public virtual string Title
{
get { return String.Empty; }
}
/// <summary>
/// Gets the file name without path information for this <see cref="Accessor" />, if applicable.
/// </summary>
/// <returns>A <see cref="String" /> containing the file name without path information for this <see cref="Accessor" />, if applicable.</returns>
public virtual string GetFileTitle()
{
return String.Empty;
}
/// <summary>
/// Gets the file name including path information for this <see cref="Accessor" />, if applicable.
/// </summary>
/// <returns>A <see cref="String" /> containing the file name including path information for this <see cref="Accessor" />, if applicable.</returns>
public virtual string GetFileName()
{
return String.Empty;

17
CSharp/Libraries/UniversalEditor.Core/AccessorReference.cs
View File

@ -31,10 +31,20 @@ namespace UniversalEditor
private string mvarTitle = String.Empty;
public string Title { get { return mvarTitle; } set { mvarTitle = value; } }
/// <summary>
/// Determines if this <see cref="ReferencedBy" /> object should be filtered by the given criteria.
/// </summary>
/// <param name="filter">The filter that determines whether this object should be displayed in a list of <see cref="ReferencedBy" /> objects.</param>
/// <returns>True if this object should appear in the list; false otherwise.</returns>
public bool ShouldFilterObject(string filter)
{
return mvarTitle.ToLower().Contains(filter.ToLower());
}
/// <summary>
/// Gets the detail fields that are shown in lists of this <see cref="ReferencedBy" /> object in details view.
/// </summary>
/// <returns>An array of <see cref="String" />s that are shown in detail columns of lists of this <see cref="ReferencedBy" /> object.</returns>
public string[] GetDetails()
{
return new string[] { mvarTitle };
@ -56,12 +66,17 @@ namespace UniversalEditor
/// </summary>
public CustomOption.CustomOptionCollection ExportOptions { get { return mvarExportOptions; } }
private CustomOption.CustomOptionCollection mvarImportOptions = new CustomOption.CustomOptionCollection();/// <summary>
private CustomOption.CustomOptionCollection mvarImportOptions = new CustomOption.CustomOptionCollection();
/// <summary>
/// A collection of <see cref="CustomOption" />s that are applied to the <see cref="Accessor" />
/// when it is being used to open or import a file.
/// </summary>
public CustomOption.CustomOptionCollection ImportOptions { get { return mvarImportOptions; } }
/// <summary>
/// Creates an instance of an <see cref="Accessor" /> from the <see cref="Type" /> described in this <see cref="AccessorReference" />.
/// </summary>
/// <returns>An <see cref="Accessor" /> instance from the <see cref="Type" /> described in this <see cref="AccessorReference" />.</returns>
public Accessor Create()
{
if (mvarAccessorType == null && mvarAccessorTypeName != null)

41
CSharp/Libraries/UniversalEditor.Core/Checksum/ChecksumModule.cs
View File

@ -5,13 +5,27 @@ using System.Text;
namespace UniversalEditor.Checksum
{
/// <summary>
/// Provides the minimal functionality required to create a checksum calculation module.
/// </summary>
public abstract class ChecksumModule
{
/// <summary>
/// The name of this checksum calculation module.
/// </summary>
public abstract string Name { get; }
private long mvarValue = 0;
/// <summary>
/// The current value of the checksum being calculated.
/// </summary>
public virtual long Value { get { return mvarValue; } protected set { mvarValue = value; } }
/// <summary>
/// Calculates the checksum based on the given input.
/// </summary>
/// <param name="input">The array of bytes used as input to the checksum calculation routine.</param>
/// <returns>A <see cref="Int64" /> that represents the checksum of the given input.</returns>
public long Calculate(byte[] input)
{
Reset();
@ -30,19 +44,26 @@ namespace UniversalEditor.Checksum
/// <summary>
/// Updates the checksum with the bytes taken from the array.
/// </summary>
/// <param name="buffer">
/// buffer an array of bytes
/// </param>
/// <param name="buffer">The array of bytes used as input to the checksum calculation routine.</param>
public void Update(byte[] buffer)
{
if (buffer == null)
{
throw new ArgumentNullException("buffer");
}
if (buffer == null) throw new ArgumentNullException("buffer");
Update(buffer, 0, buffer.Length);
}
public abstract void Update(byte[] buffer, int offset, int count);
public abstract void Update(int value);
/// <summary>
/// Updates the checksum with a count of <see cref="count" /> bytes taken from the array beginning at offset
/// <see cref="offset" />.
/// </summary>
/// <param name="buffer">The array of bytes used as input to the checksum calculation routine.</param>
/// <param name="offset">The offset into <see cref="buffer" /> from which calculation starts.</param>
/// <param name="count">The number of bytes to use in the checksum calculation.</param>
public abstract void Update(byte[] buffer, int offset, int count);
/// <summary>
/// Calculates the checksum based on the given input.
/// </summary>
/// <param name="input">The <see cref="Int32" /> value used as input to the checksum calculation routine.</param>
public abstract void Update(int input);
}
}

20
CSharp/Libraries/UniversalEditor.Core/Common/Path.cs
View File

@ -4,8 +4,18 @@ using System.Text;
namespace UniversalEditor.Common
{
/// <summary>
/// Provides common path operations.
/// </summary>
public static class Path
{
/// <summary>
/// Generates an absolute path from the given relative (or absolute) path and a parent path.
/// </summary>
/// <param name="sourcePath">The relative (or absolute) path to make absolute.</param>
/// <param name="parentPath">The parent path of the given relative path.</param>
/// <returns>A concatenation of the source path and the parent path if the source path is relative; otherwise,
/// just the source path.</returns>
public static string MakeAbsolutePath(string sourcePath, string parentPath = null)
{
string result;
@ -26,8 +36,18 @@ namespace UniversalEditor.Common
return result;
}
/// <summary>
/// Generates a relative path from the specified absolute (or relative) path and parent directory name.
/// </summary>
/// <param name="FileName">The absolute (or relative) path to make relative.</param>
/// <param name="DirectoryName">The parent path for the relative path.</param>
/// <returns>A substring of the relative path minus the parent path if the absolute path starts with the
/// parent path; otherwise, the relative (or absolute) path.</returns>
public static string MakeRelativePath(string FileName, string DirectoryName)
{
// This only goes "down" the folder hierarchy (e.g. C:/path/to/parent with C:/path as the parent becomes
// to/parent). Should we bother implementing "up" the hierarchy (will take some psychic powers) to allow
// us to use dot-dot paths (../../some/other/folder)?
if (FileName.StartsWith(DirectoryName))
{
return FileName.Substring(DirectoryName.Length);

36
CSharp/Libraries/UniversalEditor.Core/ProgressEvent.cs
View File

@ -6,24 +6,48 @@ using System.Text;
namespace UniversalEditor
{
/// <summary>
/// A delegate for the event that is raised when progress is made during an asynchronous operation.
/// </summary>
/// <param name="sender">The control firing this event.</param>
/// <param name="e">A <see cref="ProgressEventArgs" /> that contains additional information about this event.</param>
public delegate void ProgressEventHandler(object sender, ProgressEventArgs e);
/// <summary>
/// Event arguments for the event that is raised when progress is made during an asynchronous operation.
/// </summary>
public class ProgressEventArgs : CancelEventArgs
{
private long mvarTotal = 0;
/// <summary>
/// The total possible amount of progress represented by this progress event.
/// </summary>
public long Total { get { return mvarTotal; } }
private long mvarCurrent = 0;
/// <summary>
/// The current amount of progress completed.
/// </summary>
public long Current { get { return mvarCurrent; } }
/// <summary>
/// The amount of progress remaining.
/// </summary>
public long Remaining { get { return mvarTotal - mvarCurrent; } }
private string mvarMessage = String.Empty;
/// <summary>
/// The progress message
/// </summary>
public string Message { get { return mvarMessage; } }
public ProgressEventArgs(long current, long total)
{
mvarCurrent = current;
mvarTotal = total;
}
public ProgressEventArgs(long current, long total, string message)
/// <summary>
/// Creates a new instance of the <see cref="ProgressEventArgs" /> event arguments for the event that is
/// raised when progress is made during an asynchronous operation.
/// </summary>
/// <param name="current">The current amount of progress completed.</param>
/// <param name="total">The total possible amount of progress represented by this progress event.</param>
/// <param name="message">The progress message</param>
public ProgressEventArgs(long current, long total, string message = "")
{
mvarCurrent = current;
mvarTotal = total;

31
CSharp/Libraries/UniversalEditor.Core/References.cs
View File

@ -5,15 +5,40 @@ using System.Text;
namespace UniversalEditor
{
/// <summary>
/// Defines an object that references a <see cref="T:ReferencedBy`1" /> object.
/// </summary>
/// <typeparam name="TRef">The <see cref="T:ReferencedBy`1" /> object referenced by this <see cref="T:References`1" /> object.</typeparam>
public interface References<TRef>
{
/// <summary>
/// Creates or returns an existing <see cref="T:ReferencedBy`1" /> object referring to this <see cref="T:References`1" /> object.
/// </summary>
/// <returns>A <see cref="T:ReferencedBy`1" /> object that can be used to create additional instances of this <see cref="T:References`1" /> object.</returns>
TRef MakeReference();
}
/// <summary>
/// Defines an object that is referenced by the given <see cref="T:References`1" /> object.
/// </summary>
/// <typeparam name="TObj">The <see cref="T:References`1" /> object which references this <see cref="T:ReferencedBy`1" /> object.</typeparam>
public interface ReferencedBy<TObj>
{
{
/// <summary>
/// Creates an instance of this <see cref="T:ReferencedBy`1" /> object from the <see cref="Type" /> described in the associated <see cref="T:References`1" /> object.
/// </summary>
/// <returns>An instance of this <see cref="T:ReferencedBy`1" /> object created from the <see cref="Type" /> described in the associated <see cref="T:References`1" /> object.</returns>
TObj Create();
string[] GetDetails();
/// <summary>
/// Gets the detail fields that are shown in lists of this <see cref="T:ReferencedBy`1" /> object in details view.
/// </summary>
/// <returns>An array of <see cref="String" />s that are shown in detail columns of lists of this <see cref="T:ReferencedBy`1" /> object.</returns>
string[] GetDetails();
/// <summary>
/// Determines if this <see cref="T:ReferencedBy`1" /> object should be filtered by the given criteria.
/// </summary>
/// <param name="filter">The filter that determines whether this object should be displayed in a list of <see cref="T:ReferencedBy`1" /> objects.</param>
/// <returns>True if this object should appear in the list; false otherwise.</returns>
bool ShouldFilterObject(string filter);
}
}