timy/SpriteLibrary
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

SpriteDatabase better documentation of XML Write functions

Browse Source
This commit is contained in:
Tim Young 2017-09-25 15:14:21 -05:00
parent 265f8c1a70
commit 8ceea4fa76
1 changed files with 124 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
SpriteLibrary/SpriteDatabase.cs
View File

@ -23,8 +23,70 @@ namespace SpriteLibrary
/// Store Sprite information in a database. You can preload your database with sprite definitions, and then
/// create the sprites as needed. This can drastically reduce the initial load time of a game or something.
/// Though, what it really does is spread out the load time. It still takes the same amount of time to
/// load all the sprites, it just loads them on-demand. Using a dictionary often hides any load time issues.
/// load all the sprites, it just loads them on-demand. Using a SpriteDatabase often hides any load time issues.
/// </summary>
/// <example>
/// This is an example of how to use a SpriteDatabase.
/// When you begin developing your project, you want to start by creating a SpriteDatabase and pointing
/// it to a file, and then opening up an <see cref="SpriteDatabase.OpenEditWindow(int)">EditorWindow.</see>
/// <code lang="C#">
/// public partial class MyGameForm : Form
/// {
/// SpriteController mySpriteController = null;
/// SpriteDatabase mySpriteDatabase = null;
///
/// public MyGameForm()
/// {
/// InitializeComponent();
/// MainDrawingArea.BackgroundImage = Properties.Resources.Background;
/// MainDrawingArea.BackgroundImageLayout = ImageLayout.Stretch;
///
/// string Desktop = Environment.GetFolderPath(Environment.SpecialFolder.Desktop);
/// string MyFile = Path.Combine(Desktop, "myFile.xml");
/// mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, MyFile);
///
/// mySpriteController = new SpriteController(MainDrawingArea, mySpriteDatabase);
///
/// mySpriteDatabase.OpenEditWindow();
/// mySpriteDatabase.Save();
/// }
/// }
/// </code>
/// The Editor Window will let you find the sprites that are contained in the various images you have
/// as resources in your program, and it will save a file with those sprite templates. Any SpriteController
/// that you have instantiated with a Sprite Database (see <see cref="SpriteController(PictureBox, SpriteDatabase)"/>)
/// will now be able to create named sprites from the templates defined in the database. After the first use, the
/// named sprites will be accessible from within that controller just like any other named sprites.
/// <para/>
/// After you have created your SpriteDatabase file, you will want to add your file to your program resources.
/// Then, you will change the SpriteDatabase to use the resource instead of a file. If we named the file
/// "MySpriteDatabase.xml", and it got added to your resources with the name "MySpriteDatabase", you would
/// pass "MySpriteDatabase" to the database instantiation.
/// <code lang="C#">
/// public partial class MyGameForm : Form
/// {
/// SpriteController mySpriteController = null;
/// SpriteDatabase mySpriteDatabase = null;
///
/// public MyGameForm()
/// {
/// InitializeComponent();
/// MainDrawingArea.BackgroundImage = Properties.Resources.Background;
/// MainDrawingArea.BackgroundImageLayout = ImageLayout.Stretch;
///
/// //string Desktop = Environment.GetFolderPath(Environment.SpecialFolder.Desktop);
/// //string MyFile = Path.Combine(Desktop, "myFile.xml");
/// //mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, MyFile);
/// mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, "MySpriteDatabase");
///
/// mySpriteController = new SpriteController(MainDrawingArea, mySpriteDatabase);
///
/// //mySpriteDatabase.OpenEditWindow();
/// //mySpriteDatabase.Save();
/// }
/// }
/// </code>
/// </example>
public class SpriteDatabase
{
/// <summary>
@ -193,7 +255,7 @@ namespace SpriteLibrary
/// that you have instantiated with a Sprite Database (see <see cref="SpriteController(PictureBox, SpriteDatabase)"/>)
/// will now be able to create named sprites from the templates defined in the database. After the first use, the
/// named sprites will be accessible from within that controller just like any other named sprites.
///
/// <para/>
/// After you have created your SpriteDatabase file, you will want to add your file to your program resources.
/// Then, you will change the SpriteDatabase to use the resource instead of a file. If we named the file
/// "MySpriteDatabase.xml", and it got added to your resources with the name "MySpriteDatabase", you would
@ -341,11 +403,32 @@ namespace SpriteLibrary
#region Generic XML Funcs
/// <summary>
/// Load in an XML serialized item from the specified ResourceManager. You will usually make one of these by
/// creating an object and using <see cref="WriteToXmlFile{T}(string, T)"/> SpriteDatabase.WriteToXmlFile to
/// save it to a file on your desktop. Then you can drag and drop that file into your project and then use this
/// LoadObjectFromXmlFile function.
/// Load in an XML serialized item from the specified ResourceManager. You will usually make an XML file by
/// creating an object (as a variable) and using <see cref="WriteToXmlFile{T}(string, T)"/> to
/// serialize it and save it to a file on your desktop. Then you can drag and drop that file into your project and then use this
/// LoadObjectFromXmlFile function. You can google XML Serialization for more information.
/// </summary>
/// <example>
/// XML Serialization takes an object (a class, a variable, or whatever) and will store any public values in XML.
/// You can choose to save the resulting XML as a string, or to save it to a file. This function Loads it from a
/// resource file (one which has been added to Properties.Resources.) The corresponding write function:
/// <see cref="WriteToXmlFile{T}(string, T)"/> writes to a file that is outside of Properties.Resources; the
/// resources of a program are read-only. Once you write to a file, you can drag the resulting XML into your project
/// and load it from there. If you want to load from an XML file that is not a resource, use <see cref="ReadFromXmlFile{T}(string)"/>
/// <para/>Here is code to create an item and save it to a file.
/// <code Lang="C#">
/// MyClass MyVariable = new MyClass();
/// MyVariable.Name = "StoreThis!";
///
/// SpriteDatabase.WriteToXmlFile&lt;MyClass&gt;("c:\xml_file.xml", MyClass);
/// </code>
/// Now that we have an XML file, we drag that file into our project so that it shows up in our Properties.Resources
/// and then we can use this code to load it.
/// <code Lang="C#">
/// MyClass MyVariable = SpriteDatabase.LoadObjectFromXmlFile&lt;MyClass&gt;("xml_file",Properties.Resources.ResourceManager);
/// Console.WriteLine(MyVariable.Name);
/// </code>
/// </example>
/// <typeparam name="T">The type of object to load. It could be something as simple as an int, a class, or a list of classes.</typeparam>
/// <param name="XMLResourceToLoad">The resource item to load. If you would access it like: properties.resources.myFile,
/// the correct value to put here would be "myFile"</param>
@ -376,6 +459,25 @@ namespace SpriteLibrary
/// If there are public properties/variables that you do not want written to the file, decorate them with the [XmlIgnore] attribute.
/// Object type must have a parameterless constructor.
/// </summary>
/// <example>
/// XML Serialization takes an object (a class, a variable, or whatever) and will store any public values in XML.
/// You can choose to save the resulting XML as a string, or to save it to a file. This function
/// writes to a file that is outside of Properties.Resources; the
/// resources of a program are read-only. Once you write to a file, you can drag the resulting XML into your project
/// and load it from there. If you want to load from an XML file that is not a resource, use <see cref="ReadFromXmlFile{T}(string)"/>
/// <para/>Here is code to create an item and save it to a file.
/// <code Lang="C#">
/// MyClass MyVariable = new MyClass();
/// MyVariable.Name = "StoreThis!";
///
/// SpriteDatabase.WriteToXmlFile&lt;MyClass&gt;("c:\xml_file.xml", MyClass);
/// </code>
/// Now that we have an XML file, we can use this code to load it.
/// <code Lang="C#">
/// MyClass MyVariable = SpriteDatabase.ReadFromXmlFile&lt;MyClass&gt;("c:\xml_file.xml");
/// Console.WriteLine(MyVariable.Name);
/// </code>
/// </example>
/// <typeparam name="T">The type of object being written to the file.</typeparam>
/// <param name="filePath">The file path to write the object instance to.</param>
/// <param name="objectToWrite">The object instance to write to the file.</param>
@ -399,6 +501,22 @@ namespace SpriteLibrary
/// Reads an object instance from an XML file.
/// <para>Object type must have a parameterless constructor.</para>
/// </summary>
/// <example>
/// XML Serialization takes an object (a class, a variable, or whatever) and will store any public values in XML.
/// You can choose to save the resulting XML as a string, or to save it to a file. This function
/// reads in a file that probably has been written by <see cref="SpriteDatabase.WriteToXmlFile{T}(string, T)"/>.
/// <code Lang="C#">
/// MyClass MyVariable = new MyClass();
/// MyVariable.Name = "StoreThis!";
///
/// SpriteDatabase.WriteToXmlFile&lt;MyClass&gt;("c:\xml_file.xml", MyClass);
/// </code>
/// Now that we have an XML file, we can use this code to load it.
/// <code Lang="C#">
/// MyClass MyVariable = SpriteDatabase.ReadFromXmlFile&lt;MyClass&gt;("c:\xml_file.xml");
/// Console.WriteLine(MyVariable.Name);
/// </code>
/// </example>
/// <typeparam name="T">The type of object to read from the file.</typeparam>
/// <param name="filePath">The file path to read the object instance from.</param>
/// <returns>Returns a new instance of the object read from the XML file.</returns>