Some SpriteEventHandler examples

SpriteLibrary/Sprite.cs

@@ -324,7 +324,9 @@ namespace SpriteLibrary
         /// <summary>
         /// 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
+        /// 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)
         /// </summary>
         /// <param name="sender">The Sprite that triggers the event</param>
         /// <param name="e">A SpriteEventArgs class which contains Sprite Event values</param>
@@ -338,21 +340,112 @@ namespace SpriteLibrary
         /// This happens when the sprite hits the border of the picture-box.  
         /// Useful for when you want to have shots explode when they hit the side.
         /// </summary>
+        /// <example>
+        /// Here is an example of us defining a Sprite.  We retrieve a named Sprite and set the function on the
+        /// master template to call the SpriteBounces function whenever the Sprite hits the picturebox.
+        /// <para/>You only need to add the function once, if you are putting it on the Named Sprite.  After
+        /// that time, all the sprites duplicated from the template will have this function set for them.
+        /// <code Lang="C#">
+        /// public void DefineSprite()
+        /// {
+        ///     Sprite mySprite = MySpriteController.SpriteFromName("Ball");
+        ///     mySprite.SpriteHitsPictureBox += SpriteBounces;
+        /// }
+        /// 
+        /// public void SpriteBounces(object sender, EventArgs e)
+        /// {
+        ///    Sprite me = (Sprite)sender;
+        ///    int degrees = (int)me.GetSpriteDegrees();
+        ///    if (Math.Abs(degrees) > 120)
+        ///    {
+        ///        me.SetSpriteDirectionDegrees(0);//go right
+        ///    }
+        ///    else
+        ///    {
+        ///        me.SetSpriteDirectionDegrees(180); //go back left
+        ///    }
+        /// }
+        /// </code>
+        /// </example>
         public event SpriteEventHandler SpriteHitsPictureBox = delegate { };
         /// <summary>
         /// This happens when the sprite has exited the picture box.  Useful when you want to 
-        /// keep sprites from traveling on forever after exiting.
+        /// keep sprites from traveling on forever after exiting.  For example, you may want to
+        /// destroy the sprite now that it is no longer visible.
         /// </summary>
         public event SpriteEventHandler SpriteExitsPictureBox = delegate { };
         /// <summary>
         /// Only used when you tell an animation to animate once.  At the end of the animation, 
-        /// this function fires off.
+        /// 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.
+        /// <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.
+        /// Because it is an "explosion", we want to destroy the sprite once it has finished.  We do not want the
+        /// Sprite to explode over and over and over, we do it once, and then it is done.
+        /// <para/>You only need to add the function once, if you are putting it on the Named Sprite.  After
+        /// that time, all the sprites duplicated from the template will have this function set for them.
+        /// <code Lang="C#">
+        /// public void DefineSprite()
+        /// {
+        ///     Sprite mySprite = MySpriteController.SpriteFromName("Explosion");
+        ///     mySprite.SpriteAnimationComplete += SpriteDoneAnimating;
+        /// }
+        /// 
+        /// public void MakeAnExplosion(Point Where)
+        /// {
+        ///     Sprite mySprite = MySpriteController.DuplicateSprite("Explosion");
+        ///     mySprite.PutBaseImageLocation(Where);
+        ///     mySprite.AnimateOnce();
+        /// }
+        /// 
+        /// public void SpriteDoneAnimating(object sender, EventArgs e)
+        /// {
+        ///    Sprite me = (Sprite)sender;
+        ///    me.Destroy();
+        /// }
+        /// </code>
+        /// </example>
         /// </summary>
         public event SpriteEventHandler SpriteAnimationComplete = delegate { };
         /// <summary>
         /// This happens when two sprites hit each-other.  The SpriteEventArgs that is returned 
         /// contains the sprite that this sprite hits.
         /// </summary>
+        /// <example>
+        ///
+        /// <code Lang="C#">
+        /// public void DefineSprite()
+        /// {
+        ///     Sprite mySprite = MySpriteController.SpriteFromName("Monster");
+        ///     mySprite.SpriteHitsSprite += MonsterHitBySprite;
+        /// }
+        /// 
+        /// public void MonsterHitBySprite(object sender, SpriteEventArgs e)
+        /// {
+        ///    Sprite me = (Sprite)sender;
+        ///    //Check to see if we got hit by a "shot" sprite
+        ///    if (e.TargetSprite.SpriteOriginName == "Shot")
+        ///    {
+        ///        //we got shot.  DIE!
+        ///        Sprite nSprite = MySpriteController.DuplicateSprite("Explosion");
+        ///        nSprite.PutBaseImageLocation(me.BaseImageLocation);  //put the explosion where the "hit" sprite is
+        ///        nSprite.SetSize(me.GetSize); //Use the size of the sprite that got hit.
+        ///        nSprite.AnimateOnce(0); //Animate once.  Hopefully the explosion destroys itself when the animation ends
+        ///        
+        ///        //Play a boob sound
+        ///        SoundPlayer newPlayer = new SoundPlayer(Properties.Resources.Boom);
+        ///        newPlayer.Play();
+        ///
+        ///        //destroy the sprite that got hit
+        ///        me.Destroy();
+        ///        //destroy the "shot" sprite that hit us
+        ///        e.TargetSprite.Destroy();
+        ///    }
+        ///}        
+        /// </code>
+        /// </example>
         public event SpriteEventHandler SpriteHitsSprite = delegate { };
         /// <summary>
         /// This event fires off before a sprite is drawn. Use it if you have constraints.  You