Table of Contents
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Events
Part of the power of the sprite library is the event system. An event is triggered by something in the program; two sprites collide, someone clicks on a sprite, or something like that. (search the internet for “C# event” to read up on this concept if it is new to you) You can create an event and attach it to a sprite, or the sprite controller, and then have your code run when the event occurs.
An example is if you have an explosion sprite, and want the sprite to be destroyed once the explosion has completed. You can add an event to SpriteAnimationComplete, and tell the sprite to animate once. Then, when the sprite has finished with its animation, the code you have created will execute.
How events work
The sprite-library is always checking for things, like sprites colliding, sprites exiting the bounds of the picture-box, sprites being destroyed, and the like. When the sprite-controller finds that something has happened, it will try to execute the code associated with that event. If no such code exists, the sprite controller continues on.
When to use events
You want to use events whenever you want something triggered instead of happening at a set time.
For example:
You can take a torpedo and send it one direction. You can have it set to explode when it hits something (SpriteHitsSprite).
You can take a ball and have it “bounce” every time it hits the bounds of the picture-box. Set an event for when it hits the edge (SpriteHitsPictureBox), check to see what direction it had been moving, and change the direction accordingly.
You can take a sprite and tell it to MoveTo a bunch of places, and then have it run some code when it has reached it’s end-point (SpriteArrivedAtEndPoint). You may want to do this if you are having an adventurer jump over something to trigger the fact that he just landed.
You can tell a sprite to do something when a sprite has finished animating. This is excellent for an explosion that you want to have disappear once the explosion animation has completed. For this to work you want to set the sprite to AnimateOnce, and then have a SpriteAnimationComplete event.
One not-so-obvious use is the CheckBeforeMove event; you can use this to adjust the position of a sprite that is automatically moving, or to check to see if a sprite has collided with something in particular. In one of my demos (RunningDemo), I use this to see if the sprite is standing on the ground, or if it needs to fall. The CheckBeforeMove event happens when the sprite thinks it knows where it is supposed to move to, but sends the location to the event. You can change it and even cancel the move event (make the movement stop).
How to add an event
Events can be added to sprites at any time.
ExplosionSprite.SpriteAnimationComplete += ExplosionCompletes;
public void ExplosionCompletes(object sender, EventArgs e)
{
Sprite tSprite = (Sprite)sender;
tSprite.Destroy();
}
In this example, ExplosionSprite is the name of the sprite, and we are telling the sprite to destroy itself once the sprite has finished animating. You can add the event to the sprite when you first create the sprite and name it (see the section on naming sprites). Events are duplicated, along with all the properties, when a sprite is duplicated from a named sprite. It usually makes most sense to put the event on the named sprite, so you do not need to do it over and over as you create and destroy sprites later on.
If you add events to a sprite that is based off a named sprite, the named sprite is not changed, and that event only occurs on that one sprite.
You do not need to remove events from sprites when destroying sprites. Those are properly cleaned up for you.