diff --git a/SpriteLibrary/SpriteDatabase.cs b/SpriteLibrary/SpriteDatabase.cs index 3954146..bdf437a 100644 --- a/SpriteLibrary/SpriteDatabase.cs +++ b/SpriteLibrary/SpriteDatabase.cs @@ -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. /// + /// + /// 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 EditorWindow. + /// + /// 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(); + /// } + /// } + /// + /// 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 ) + /// 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. + /// + /// 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. + /// + /// 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(); + /// } + /// } + /// + /// public class SpriteDatabase { /// @@ -193,7 +255,7 @@ namespace SpriteLibrary /// that you have instantiated with a Sprite Database (see ) /// 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. - /// + /// /// 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 /// - /// Load in an XML serialized item from the specified ResourceManager. You will usually make one of these by - /// creating an object and using 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 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. /// + /// + /// 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: + /// 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 + /// Here is code to create an item and save it to a file. + /// + /// MyClass MyVariable = new MyClass(); + /// MyVariable.Name = "StoreThis!"; + /// + /// SpriteDatabase.WriteToXmlFile<MyClass>("c:\xml_file.xml", MyClass); + /// + /// 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. + /// + /// MyClass MyVariable = SpriteDatabase.LoadObjectFromXmlFile<MyClass>("xml_file",Properties.Resources.ResourceManager); + /// Console.WriteLine(MyVariable.Name); + /// + /// /// The type of object to load. It could be something as simple as an int, a class, or a list of classes. /// The resource item to load. If you would access it like: properties.resources.myFile, /// the correct value to put here would be "myFile" @@ -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. /// + /// + /// 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 + /// Here is code to create an item and save it to a file. + /// + /// MyClass MyVariable = new MyClass(); + /// MyVariable.Name = "StoreThis!"; + /// + /// SpriteDatabase.WriteToXmlFile<MyClass>("c:\xml_file.xml", MyClass); + /// + /// Now that we have an XML file, we can use this code to load it. + /// + /// MyClass MyVariable = SpriteDatabase.ReadFromXmlFile<MyClass>("c:\xml_file.xml"); + /// Console.WriteLine(MyVariable.Name); + /// + /// /// The type of object being written to the file. /// The file path to write the object instance to. /// The object instance to write to the file. @@ -399,6 +501,22 @@ namespace SpriteLibrary /// Reads an object instance from an XML file. /// Object type must have a parameterless constructor. /// + /// + /// 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 . + /// + /// MyClass MyVariable = new MyClass(); + /// MyVariable.Name = "StoreThis!"; + /// + /// SpriteDatabase.WriteToXmlFile<MyClass>("c:\xml_file.xml", MyClass); + /// + /// Now that we have an XML file, we can use this code to load it. + /// + /// MyClass MyVariable = SpriteDatabase.ReadFromXmlFile<MyClass>("c:\xml_file.xml"); + /// Console.WriteLine(MyVariable.Name); + /// + /// /// The type of object to read from the file. /// The file path to read the object instance from. /// Returns a new instance of the object read from the XML file.