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

More changes to the documentation

This commit is contained in:
Tim Young 2017-09-25 18:41:05 -05:00
parent 2c652489a8
commit c492fa82ea
4 changed files with 119 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
SpriteLibrary/KeyMessageFilter.cs
View File

@ -8,7 +8,9 @@ using System.Windows.Forms;
namespace SpriteLibrary
{
/// <summary>
/// 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 <see cref="SpriteController.RegisterKeyDownFunction(SpriteKeyEventHandler)"/> and
/// <see cref="SpriteController.RegisterKeyUpFunction(SpriteKeyEventHandler)"/> functions.
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>

39
SpriteLibrary/Sprite.cs
View File

@ -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.
/// <para/>You want to read up on <seealso cref="SetName(string)"/> for defining named sprites (Sprite Templates),
/// <seealso cref="SpriteDatabase"/> for creating a database of sprites which are accessed on demand (this is just
/// <para/>You want to read up on <see cref="SetName(string)"/> for defining named sprites (Sprite Templates),
/// <see cref="SpriteDatabase"/> 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 <seealso cref="SpriteController.DuplicateSprite(string)"/> for how to duplicate a
/// programatically), and <see cref="SpriteController.DuplicateSprite(string)"/> for how to duplicate a
/// sprite from a sprite template.
/// </summary>
public class Sprite
@ -302,16 +302,24 @@ namespace SpriteLibrary
/// actual image size.
/// </summary>
public int VisibleWidth { get { return MySpriteController.ReturnPictureBoxAdjustedWidth(Width); } }
/// <summary>
/// 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.
/// </summary>
/// <example>
/// 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:
/// <code Lang="C#">
/// public class TankPayload : SpritePayload { public int Armor; public int Speed; }
/// public class TankPayload : SpritePayload
/// {
/// public int Armor;
/// public int Speed;
/// }
/// </code>
/// You can access the payload and retrieve the various values.
/// </summary>
/// </example>
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: <seealso cref="SpriteHitsPictureBox"/>,
/// <seealso cref="SpriteAnimationComplete"/>, and <seealso cref="SpriteHitsSprite"/> for a few examples)
/// one of the many Sprite Events. (see: <see cref="SpriteHitsPictureBox"/>,
/// <see cref="SpriteAnimationComplete"/>, and <see cref="SpriteHitsSprite"/> for a few examples)
/// </summary>
/// <param name="sender">The Sprite that triggers the event</param>
/// <param name="e">A SpriteEventArgs class which contains Sprite Event values</param>
@ -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.
/// </summary>
/// <example>
/// 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
/// }
/// </code>
/// </example>
/// </summary>
public event SpriteEventHandler SpriteAnimationComplete = delegate { };
/// <summary>
/// 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.
/// <para/>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. <seealso cref="SpriteController.DuplicateSprite(string)"/> is the function
/// duplicated every time you want one. <see cref="SpriteController.DuplicateSprite(string)"/> is the function
/// you usually use to duplicate a sprite.
/// </summary>
/// <example>
@ -671,7 +679,7 @@ namespace SpriteLibrary
/// an asteroid Sprite, and then send twenty of them bouncing around on the screen.
/// <para/>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. <seealso cref="SpriteController.DuplicateSprite(string)"/> is the function
/// duplicated every time you want one. <see cref="SpriteController.DuplicateSprite(string)"/> is the function
/// you usually use to duplicate a sprite.
/// <para/>
/// 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;
/// </code>
/// There are two related concepts. You may want to read up on <seealso cref="SpriteController.LinkControllersForSpriteTemplateSharing(SpriteController)"/>
/// to let multiple SpriteControllers look up named Sprites from each-other. You can also read up on the <seealso cref="SpriteDatabase"/>, which allows you
/// There are two related concepts. You may want to read up on <see cref="SpriteController.LinkControllersForSpriteTemplateSharing(SpriteController)"/>
/// to let multiple SpriteControllers look up named Sprites from each-other. You can also read up on the <see cref="SpriteDatabase"/>, 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.
/// </example>
@ -1394,19 +1402,20 @@ namespace SpriteLibrary
}
/// <summary>
/// Tell the sprite to kill itself. It will erase itself and then be removed from the SpriteList
/// </summary>
/// <example>
/// 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 <see cref="Sprite.Destroying"/> 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:
/// <example>
/// <code LANG="C#">
/// MySprite.Destroy();
/// MySprite = null;
/// </code>
/// </example>
/// </summary>
public void Destroy()
{
//If we are not already destroying ourselves

40
SpriteLibrary/SpriteController.cs
View File

@ -14,22 +14,22 @@ namespace SpriteLibrary
{
/// <summary>
/// SpriteLibrary is a .net graphical library for creating and controlling sprites on a PictureBox.
///
/// <para/>
/// 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.
///
/// <para/>
/// 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:
/// <see href="http://www.codeproject.com/Articles/1085446/Using-Sprites-Inside-Windows-Forms"/>
/// and
/// <see href="https://git.solidcharity.com/timy/SpriteLibrary"/>
/// and
/// <see href="http://tyounglightsys.ddns.info/SpriteLibrary"/>
/// The main places to find the SpriteLibrary and sample programs using this SpriteLibrary are here:
/// <para/><see href="http://www.codeproject.com/Articles/1085446/Using-Sprites-Inside-Windows-Forms"/>
/// <para/>and
/// <para/><see href="https://git.solidcharity.com/timy/SpriteLibrary"/>
/// <para/>and
/// <para/><see href="http://tyounglightsys.ddns.info/SpriteLibrary"/>
/// </summary>
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.
/// <para/>It is fairly simple to have multiple pictureboxes on one form. You can <seealso cref="SpriteController.LinkControllersForSpriteTemplateSharing(SpriteController)">link</seealso>
/// <para/>It is fairly simple to have multiple pictureboxes on one form. You can <see cref="SpriteController.LinkControllersForSpriteTemplateSharing(SpriteController)">link</see>
/// SpriteControllers, which allows sprite templates (Named Sprites) to be shared between controllers. You can also use
/// a <seealso cref="SpriteDatabase"/> to define sprite templates which can be used across multiple PictureBoxes.
/// a <see cref="SpriteDatabase"/> to define sprite templates which can be used across multiple PictureBoxes.
/// </summary>
/// <example>
/// 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)
/// </summary>
/// <example>
/// <code Lang="C#">
/// MyController.RegisterKeyDownFunction(GameKeyDownFunc);
///
/// void GameKeyDownFunc(object sender, KeyEventArgs e)
/// {
/// Console.WriteLine("Key Pressed: " + e.Key.ToString());
/// }
/// </code>
/// </example>
/// <param name="Func">The function to set</param>
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)
/// </summary>
/// <example>
/// <code Lang="C#">
/// MyController.RegisterKeyUpFunction(GameKeyUpFunc);
///
/// void GameKeyUpFunc(object sender, KeyEventArgs e)
/// {
/// Console.WriteLine("Key Released: " + e.Key.ToString());
/// }
/// </code>
/// </example>
/// <param name="Func">The function to set</param>
public void RegisterKeyUpFunction(SpriteKeyEventHandler Func)
{

62
SpriteLibrary/SpriteDatabase.cs
View File

@ -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")
/// </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 EditorWindow.
/// <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, "MySprites.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, "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();
/// }
/// }
/// </code>
/// </example>
/// <param name="theResourceManager">The ResourceManager for your project. Usually
/// Properties.Resources.ResourceManager</param>
/// <param name="filename">Either a path and file (like: @"c:\users\me\Desktop\myfile.xml") or