| SpriteController Class |
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 picturebox, and try to avoid making and destroying
new forms with SpriteController/pictureboxes in them. It is hard to destroy them completely.
Inheritance HierarchyNamespace: SpriteLibrary
Assembly: SpriteLibrary (in SpriteLibrary.dll) Version: 1.0.0.5 (1.0.0.5)
SyntaxC#
public class SpriteController
The SpriteController type exposes the following members.
Constructors| Name | Description | |
|---|---|---|
  | SpriteController(PictureBox) |
Create a sprite controller, specifying the picturebox on which the sprites
will be displayed. You want to have the PictureBox already defined, and a background image
already set for the PictureBox.
|
| SpriteController(PictureBox, EventHandler) |
Create a sprite controller, specifying the picturebox on which the sprites
will be displayed.
|
Properties| Name | Description | |
|---|---|---|
 | BackgroundImage |
The Background Image on which the sprites are drawn. This image ends up having
sprite parts on it. The OriginalImage is the version that is clean. Use
ReplaceOriginalImage to replace the background Image.
|
| OriginalImage |
The Image from which the background is taken when we erase sprites. The BackgroundImage
is the image that contains images of the sprites as well as the background image. Use
ReplaceOriginalImage to replace this and the BackgroundImage.
|
| SpriteCount |
The count of all the sprites the controller knows about. This includes named
sprites, which may not be visible.
|
Methods| Name | Description | |
|---|---|---|
| AddSprite |
Add the specified sprite to the list of sprites we know about. You usually do not need to do this.
Sprites add themselves to the controller when you create a new sprite.
|
| AdjustPoint |
Adjust an image point so that it conforms to the picturebox.
|
| AdjustRectangle |
Adjust a rectangle that is based on the image, according to the stretch of the picturebox
|
| AllSprites |
Return a list of all sprites
|
| ChangeTickInterval |
Change the Tick Interval. By default, the spritecontroller does a tick every 10ms, which
is very fast. Some people may prefer it to happen less regularly. Must be > 5, and less than 1001
|
| CountSpritesBasedOff |
Count the number of sprites that were duplicated from the sprite with the specified name. When you use a
SpriteController.DuplicateSprite(string)
command, it creates a new sprite that is based off the named sprite. This function will count those duplicated sprites.
|
| DestroyAllSprites |
Remove all sprites (even named sprites that have not yet been displayed)
|
| DestroySprite |
Tell a sprite to destroy itself. The sprite will have Destroying property set to true from
the time you destroy it until it vanishes. Whe you destroy a sprite, it will erase itself
and remove itself from the controller. After it is destroyed, it is completely gone.
|
| DuplicateSprite(String) |
Find a sprite that has been named with the specified name. Then duplicate that sprite
|
| DuplicateSprite(Sprite) |
Make a duplicate of the specified sprite. The duplicate does not yet have a location.
|
| Equals | Determines whether the specified object is equal to the current object. (Inherited from Object.) |
 | Finalize | Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.) |
| GetHashCode | Serves as the default hash function. (Inherited from Object.) |
| GetType | Gets the Type of the current instance. (Inherited from Object.) |
| Invalidate(Boolean) |
Invalidate the entire image on which the sprites are drawn
|
| Invalidate(Rectangle, Boolean) |
Invalidate a rectangle that is specified in image coordinates
|
| IsKeyPressed |
Check to see if any keys are pressed. There is a small glitch with the
key-pressed system. If the form loses focus, and someone releases a key, the key-up is never
triggered. It is a good thing to ResetKeypressState() occasionally if you think your form may have
lost focus.
|
| IsKeyPressed(Keys) |
Check to see if the given key is pressed. There is a small glitch with the
key-pressed system. If the form loses focus, and someone releases a key, the key-up is never
triggered. It is a good thing to ResetKeypressState() occasionally if you think your form may have
lost focus.
|
| KeysPressed |
Return a list of all the keys that are currently pressed. There is a small glitch with the
key-pressed system. If the form loses focus, and someone releases a key, the key-up is never
triggered. It is a good thing to ResetKeypressState() occasionally if you think your form may have
lost focus.
|
| MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
| NameSprite |
Find the specified Sprite in the controller and change its name to the specified string.
You can do the same thing with Sprite.SetName(Name) |
| Pause |
Pause everything. It loops through all the sprites in the SpriteController and sends the specified
SpritePauseType to each one. Look at the documentation for SpritePauseType to determine which pause
type to use.
|
| PlaceSpriteBehind |
Change the display order of the sprites such that the specified sprite appears behind the other sprite.
|
| PlaceSpriteInFrontOf |
Make the sprite go in front of the specified sprite.
|
| RegisterKeyDownFunction |
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)
|
| RegisterKeyUpFunction |
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)
|
| ReplaceOriginalImage |
Notify the sprite controller that you have changed the background image on the
PictureBox. Whatever background is on the picturebox is now used to draw all the sprites on.
|
| ReplaceOriginalImage(Image) |
Replace the image on which the sprites are drawn. Use this when you move to a new playing field,
or want to have a different background
Examples
Replacing the background image is actually a lot more complex than you might imagine. Once you use the
below code, it can be done without any problem. But you need to do it this way, or it just goofs up in
a number of small ways.
You need to tell the sprite controller that you are replacing the background image,
and you need to change the image to that image as well.Because the Images are actually
pointers to memory where the image sets, changes to one image will affect the other image.This goofs
things up, so what we do is duplicate the image twice, and tell the sprite controller to use one of the
copies and then set the background to be the other one of the two copies.Finally, we tell the picturebox
to invalidate itself.That does everything that is needed.
C# void ReplaceBackground(Image NewBackground) { if (MyController == null) return; if (NewBackground == null) return; Image OneImage = new Bitmap(NewBackground); MyController.ReplaceOriginalImage(OneImage); Image TwoImage = new Bitmap(NewBackground); pb_map.BackgroundImage = TwoImage; pb_map.Invalidate(); } |
| ResetKeypressState |
Reset the keypress status. Sometimes the sprite controller misses a key being released (usually
because a window has taken priority, or something has changed). Calling this function will reset
the stored memory of whether a key has been pressed.
|
| ReturnAdjustmentRatio |
Return an adjustment ratio. This is the image-size to picture-box ratio.
It is used for calculating precise pixels or picture-box locations.
|
| ReturnPictureBoxAdjustedHeight |
Return the height of an object in picture-box terms. It is basically the virtual height
of the sprite or other item.
|
| ReturnPictureBoxAdjustedPoint |
This does the reverse of an adjusted point. It takes a point on the image and
transforms it to one on the PictureBox
|
| ReturnPictureBoxAdjustedWidth |
Return the width of an object in picture-box terms. It takes the width of a sprite or other
item that is being displayed on the screen, and calculates the width as displayed in the
picture-box (taking into consideration stretching or shrinking)
|
| ReturnPointAdjustedForImage |
This takes a point, the location on a picturebox, and returns the corresponding point on the BackgroundImage.
Picturebox locations are "sloppy"; the background image locations are very precise. Since this takes a "sloppy"
number and returns a precise number, it does some rounding to figure out where the specified location is.
|
| SoundIsFinished |
Check to see if the specified sound has finished playing
|
| SoundPlay |
Play a sound that we can check to see if it has completed.
|
| SpriteBackwards |
Change the display order of the specified sprite so it is more likely to go behind all other sprites.
|
| SpriteForwards |
Change the display order of the specified sprite so it is more likely to go in front of other sprites
|
| SpriteFromName |
Find a sprite that has a specified name. This returns the actual sprite with that name.
You usually want to use DuplicateSprite(Name) to clone the sprite and get one you can
destroy. If you destroy a named sprite without duplicating it, you may end up losing
it for the remainder of the program.
|
| SpritesAtImagePoint |
This takes a point, as as specified on the image, and returns the sprites at that point. Different
functions use different coordinates, whether based off the background image, or based off the picturebox.
This one uses the background image coordinates. Use SpritesAdPoint() if you are doing something based off
a MouseUp or MouseDown function. This is used for functions based on sprite location or based off the absoloute
location (using the background image location is much more precise than the visible location in the picturebox)
|
| SpritesAtPoint |
This takes a point, as given by the mouse-click args, and returns the sprites at that point. Different
functions use different coordinates, whether based off the background image, or based off the picturebox.
This one uses the picturebox coordinates. So you can use this directly from a MouseDown or MouseUp function.
|
| SpritesBasedOff |
Return all sprites that were based off a particular sprite name.
When you use a
SpriteController.DuplicateSprite(string)
command, it creates a new sprite that is based off the named sprite. This function returns a list of those
duplicated sprites.
|
| SpritesBasedOffAnything |
Return a list of all sprites which are not master sprites (which are duplicates of something)
|
| SpritesInImageRectangle |
Return a list of all the sprites that intersect with the given background-image-based rectangle
|
| SpritesThatHaveBeenDrawn |
Return a list of all sprites which have been drawn on the image
|
| SpriteToBack |
Change the display order of the specified sprite so it goes behind all other sprites.
|
| SpriteToFront |
Change the display order of the specified sprite so it goes in front of all other sprites.
|
| ToString | Returns a string that represents the current object. (Inherited from Object.) |
| UnPause |
un-Pause everything. This will send the specified SpritePauseType unpause command
to all sprites.
|
Events| Name | Description | |
|---|---|---|
 | DoTick |
The function called by the timer every 10 millisecods This is usually where you will do the majority of the work.
You can define this manually, or when you instantiate the SpriteController |
Fields| Name | Description | |
|---|---|---|
 | OptimizeForLargeSpriteImages |
If your sprite images need substantial growing or shrinking when displayed, you can try setting this to "true"
to see if it makes it run any faster. What it does is to resize the image once, and keep a cached copy of that
image at that size. If you use the same sprite, but with different sizes, setting this to "True" may actually slow
down the game instead of speeding it up.
|
| RandomNumberGenerator |
Since everything needs a random number generator, we make one that should be accessible throughout your program.
|
| SpriteComparisonDelegate |
Allow the sprite sort-method to be overridden.
|
Examples
A sprite controller controls animations and
can help you check for key-presses. To make a sprite controller,
you need to have one defined for your main form:
And then, when the form is created, after the InitializeComponents() function, you
need to configure the drawing area and create the sprite controller:
In this case, MainDrawingArea is the picturebox where all the sprites will be displayed.
C#
SpriteController MySpriteController;
C#
MainDrawingArea.BackgroundImage = Properties.Resources.Background;
MainDrawingArea.BackgroundImageLayout = ImageLayout.Stretch;
MySpriteController = new SpriteController(MainDrawingArea);See Also