diff --git a/SpriteLibrary/KeyMessageFilter.cs b/SpriteLibrary/KeyMessageFilter.cs index cbc2ad6..6d2ec57 100644 --- a/SpriteLibrary/KeyMessageFilter.cs +++ b/SpriteLibrary/KeyMessageFilter.cs @@ -8,7 +8,9 @@ using System.Windows.Forms; namespace SpriteLibrary { /// - /// This is a delegate for a keypress event. + /// This is a delegate for a keypress event. You do not need to use this directly. This is defined so you + /// can use the and + /// functions. /// /// /// diff --git a/SpriteLibrary/Sprite.cs b/SpriteLibrary/Sprite.cs index 4c6ced7..528d03b 100644 --- a/SpriteLibrary/Sprite.cs +++ b/SpriteLibrary/Sprite.cs @@ -39,10 +39,10 @@ namespace SpriteLibrary /// A Sprite is an animated image that has a size, position, rotation, and possible vector /// It tracks where in the animation sequence it is, can report colisions, etc. This SpriteController /// draws, moves, and deals with most graphical aspects of the sprites for you. - /// You want to read up on for defining named sprites (Sprite Templates), - /// for creating a database of sprites which are accessed on demand (this is just + /// You want to read up on for defining named sprites (Sprite Templates), + /// for creating a database of sprites which are accessed on demand (this is just /// another way of creating Named Sprites, except you can store them in a database instead of making them - /// programatically), and for how to duplicate a + /// programatically), and for how to duplicate a /// sprite from a sprite template. /// public class Sprite @@ -302,16 +302,24 @@ namespace SpriteLibrary /// actual image size. /// public int VisibleWidth { get { return MySpriteController.ReturnPictureBoxAdjustedWidth(Width); } } - /// + /// A SpritePayload is an object that can be placed along with a Sprite which can hold custom data. For example, + /// you may want to use it to hold information pertaining to how much damage a particular sprite has taken. Each + /// Sprite should have its own Payload, so you can track specific information about the individual sprite. + /// + /// /// A Sprite can hold a payload. Use this to store extra information about the various Sprites. Health, Armor, /// Shoot time, etc. But, to store information in the payload, you need to make a new class of SpritePayload. The syntax /// for doing so is: /// - /// public class TankPayload : SpritePayload { public int Armor; public int Speed; } + /// public class TankPayload : SpritePayload + /// { + /// public int Armor; + /// public int Speed; + /// } /// /// You can access the payload and retrieve the various values. - /// + /// public SpritePayload payload = null; //The user can put anything they want here. //We changed the payload from being an object. The Object was too vague. By making it a defined type, //It helps with some level of type protection. @@ -325,8 +333,8 @@ namespace SpriteLibrary /// A delegate that has a SpriteEventArgs instead of EventArgs. Used for most /// of the Sprite events. This allows us to pass more information from sprite events than /// a basic EventArgs allows for. You will see this mainly when you are creating a function for - /// one of the many Sprite Events. (see: , - /// , and for a few examples) + /// one of the many Sprite Events. (see: , + /// , and for a few examples) /// /// The Sprite that triggers the event /// A SpriteEventArgs class which contains Sprite Event values @@ -379,6 +387,7 @@ namespace SpriteLibrary /// this function fires off. In the AdvDemo example, the dragon sprite has multiple /// animations. At the end of each of them, the game randomly chooses which animation /// to show next. And, it even chooses, every once in a while, to breathe fire. + /// /// /// Here is an example of us defining an explosion Sprite. We retrieve a named Sprite and set the function on the /// master template to call the SpriteDoneAnimating function whenever the Sprite animation has finished. @@ -407,7 +416,6 @@ namespace SpriteLibrary /// } /// /// - /// public event SpriteEventHandler SpriteAnimationComplete = delegate { }; /// /// This happens when two sprites hit each-other. The SpriteEventArgs that is returned @@ -662,7 +670,7 @@ namespace SpriteLibrary /// an asteroid Sprite, and then send twenty of them bouncing around on the screen. /// The best way to do this is to create a "Named Sprite", which you use as a template. From that point onward, /// you create a duplicate of that sprite. So the Named Sprite never gets used, it sits there as something that gets - /// duplicated every time you want one. is the function + /// duplicated every time you want one. is the function /// you usually use to duplicate a sprite. /// /// @@ -671,7 +679,7 @@ namespace SpriteLibrary /// an asteroid Sprite, and then send twenty of them bouncing around on the screen. /// The best way to do this is to create a "Named Sprite", which you use as a template. From that point onward, /// you create a duplicate of that sprite. So the Named Sprite never gets used, it sits there as something that gets - /// duplicated every time you want one. is the function + /// duplicated every time you want one. is the function /// you usually use to duplicate a sprite. /// /// This example shows how we create a "Named Sprite", which we do not put on the screen. But instead, we @@ -689,8 +697,8 @@ namespace SpriteLibrary /// NewSprite.MoveTo(TargetSprite); /// NewSprite.MovementSpeed = speed; /// - /// There are two related concepts. You may want to read up on - /// to let multiple SpriteControllers look up named Sprites from each-other. You can also read up on the , which allows you + /// There are two related concepts. You may want to read up on + /// to let multiple SpriteControllers look up named Sprites from each-other. You can also read up on the , which allows you /// to define NamedSprites in a database; the SpriteControllers can access the database instead of needing to do an /// initial "new Sprite(....);" to create your Sprite Template. /// @@ -1394,19 +1402,20 @@ namespace SpriteLibrary } /// + /// Tell the sprite to kill itself. It will erase itself and then be removed from the SpriteList + /// + /// /// Tell the sprite to kill itself. It will erase itself and then /// be removed from the spritelist. Then it will be gone forever. Sort-of. You see, so long as /// you still have a variable that has the sprite, that variable will still be able to reference /// the Sprite. The value will say that it is trying to be destroyed, /// but you can still accidentally do something. You really want to set your variables to null once /// you destroy something: - /// /// /// MySprite.Destroy(); /// MySprite = null; /// /// - /// public void Destroy() { //If we are not already destroying ourselves diff --git a/SpriteLibrary/SpriteController.cs b/SpriteLibrary/SpriteController.cs index 6db46f8..6d2e81b 100644 --- a/SpriteLibrary/SpriteController.cs +++ b/SpriteLibrary/SpriteController.cs @@ -14,22 +14,22 @@ namespace SpriteLibrary { /// /// SpriteLibrary is a .net graphical library for creating and controlling sprites on a PictureBox. - /// + /// /// A sprite is an animated image that can be moved around on a /// picturebox. You can give the sprite an initial location, and either move it around manually or give it /// specific movement controls. - /// + /// /// To use this library, you will need to add a reference to it in your project. You will also need a reference to /// "Windows Base." /// In the solution explorer, if you right-click your project and go to "add", and then "reference" and click /// "WindowsBase" towards the bottom. /// On that same window, on the left, click "browse." Then, click the "Browse..." button and find the sprite-library dll. - /// The main places to find the SpriteLibrary and sample programs using this SpriteLibrary are here: - /// - /// and - /// - /// and - /// + /// The main places to find the SpriteLibrary and sample programs using this SpriteLibrary are here: + /// + /// and + /// + /// and + /// /// internal class NamespaceDoc { @@ -96,9 +96,9 @@ namespace SpriteLibrary /// A sprite controller is the main heart of the sprite class. Each SpriteController manages one picturebox. /// If at all possible, try to keep each game in one form, and try to avoid making and destroying /// new forms with SpriteController/pictureboxes in them. It is hard to destroy them completely. - /// It is fairly simple to have multiple pictureboxes on one form. You can link + /// It is fairly simple to have multiple pictureboxes on one form. You can link /// SpriteControllers, which allows sprite templates (Named Sprites) to be shared between controllers. You can also use - /// a to define sprite templates which can be used across multiple PictureBoxes. + /// a to define sprite templates which can be used across multiple PictureBoxes. /// /// /// A sprite controller controls animations and @@ -1301,6 +1301,16 @@ namespace SpriteLibrary /// If you want to have a KeyDown function that is triggered by a keypress function, add the event here. /// The event should have the parameters (object sender, KeyEventArgs e) /// + /// + /// + /// MyController.RegisterKeyDownFunction(GameKeyDownFunc); + /// + /// void GameKeyDownFunc(object sender, KeyEventArgs e) + /// { + /// Console.WriteLine("Key Pressed: " + e.Key.ToString()); + /// } + /// + /// /// The function to set public void RegisterKeyDownFunction(SpriteKeyEventHandler Func) { @@ -1311,6 +1321,16 @@ namespace SpriteLibrary /// If you want to have a KeyUp function that is triggered by a keypress function, add the event here. /// The event should have the parameters (object sender, KeyEventArgs e) /// + /// + /// + /// MyController.RegisterKeyUpFunction(GameKeyUpFunc); + /// + /// void GameKeyUpFunc(object sender, KeyEventArgs e) + /// { + /// Console.WriteLine("Key Released: " + e.Key.ToString()); + /// } + /// + /// /// The function to set public void RegisterKeyUpFunction(SpriteKeyEventHandler Func) { diff --git a/SpriteLibrary/SpriteDatabase.cs b/SpriteLibrary/SpriteDatabase.cs index bdf437a..9a0ebaf 100644 --- a/SpriteLibrary/SpriteDatabase.cs +++ b/SpriteLibrary/SpriteDatabase.cs @@ -106,6 +106,68 @@ namespace SpriteLibrary /// can be the string name of a resource (the filename without the extension. If your file is accessed /// by Properties.Resources.MySprites, the "filename" would be "MySprites") /// + /// + /// 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, "MySprites.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, "MySprites.xml"); + /// //mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, MyFile); + /// mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, "MySprites"); + /// + /// mySpriteController = new SpriteController(MainDrawingArea, mySpriteDatabase); + /// + /// //mySpriteDatabase.OpenEditWindow(); + /// //mySpriteDatabase.Save(); + /// } + /// } + /// + /// /// The ResourceManager for your project. Usually /// Properties.Resources.ResourceManager /// Either a path and file (like: @"c:\users\me\Desktop\myfile.xml") or