Graphics Magician: GMSpriteList

The GMSpriteList Object

The GMSpriteList is a container that manages your GMSprites. You can put all your GMSprites in a sprite list, and then instead of looping and telling each individual sprite to move, you can just tell the sprite list to move ALL its sprites. The GMSpriteList also lets you assign a "z-order", or foreground to background value, for each of your sprites. When you use the GMSpriteList to move the sprites they are automatically drawn to appear in that order. Sprites can easily be added in any order to the list, and any sprite can be deleted at any time, and the z-order is maintained for you.

GMSpriteList Functions

Sample Programs

SpriteList with Behavior and Move() function
Cycling one-by-one through a SpriteList with data values
SpriteList, Behavior, and Sound - Using Behavior return values
A Simple Screen Saver
(examples use critters.zip and planets.zip)

Constructor

The constructor takes no parameters. It simply creates an empty GMSpriteList container. Use the Add function to add GMSprites to the container.

void Add(GMSprite* pSprite[, unsigned int zorder])
void Add(GMSprite& Sprite[, unsigned int zorder])

This function adds a GMSprite to the GMSpriteList. Most of the time you will use a GMSpriteList to manage a set of GMSprites from creation to deletion. As such, you will almost always create the GMSprites at the same time that you add them to the GMSpriteList. Do so like this:

 GMSpriteList listofsprites;
 .
 .
 listofsprites.Add(new GMSprite(Machine,filename));

Replace filename above with anything that you'd normally use to initialize a GMSprite. You can use either version of the GMSprite constructor.

Only send a pointer if the GMSprite is created within the parameter list of the Add function as above. If you send a pointer, the GMSpriteList assumes management of that pointer and will release its memory when the GMSpriteList is released.

If the GMSprite has been created prior to Adding it to the GMSpriteList, just send the name of the GMSprite by reference.

The second and optional parameter to the Add function is zorder. The "z" pertains to the z-axis, which is usually considered the depth (front to back) in animation. What happens is that this value determines the order in which the sprites in the list are drawn. The last ones drawn will appear to be in front of the of the others, or in the foreground. Sprites with high zorder values will be drawn first, and appear to be in the back. Low zorder values will appear to be in the front. zorder can be from 0 to about 4 billion. 0 is in front. If zorder is not given, the default value assigned is 10.

void Move()

This calls the GMSprite Move function for every sprite in the GMSpriteList. The sprites are drawn according to their zorder, as explained above.

void Reset()
GMSprite* GetNext()
GMSprite* GetPrevious()

You can cycle through the sprites in the GMSpriteList under control of your program. Reset goes to the beginning/end of the list (depending on whether you follow with GetNext or GetPrevious). GetNext and GetPrevious return a pointer to the next GMSprite in the list. GetNext goes forward (highest zorder to lowest, or background to foreground) and GetPrevious goes backward (lowest zorder to highest). Remember that these functions return pointers, so you can't use the dot operator with the result, you should use the arrow operator (->) to de-reference the pointer. Create a loop using one of the next two functions...

BOOL ReachedEnd()
BOOL ReachedStart()

Used with GetNext or GetPrevious, these functions will tell you when you've reached the end or beginning of the list. Here's a sample loop using these functions. The following instructions are similar to the code for the GMSpriteList's Move function described above:

 listofsprites.Reset();
 while ( ! listofsprites.ReachedEnd() ) // while NOT reached end
     listofsprites.GetNext() -> Move(); // get the next sprite and move it

Note: The above loop is just an example of cycling through a GMSpriteList. You can accomplish the same task of the above loop with the one command:

 listofsprites.Move();

GMSprite* Newest()

This returns a pointer to the sprite most recently added to the the list. This can be used to call one of the modifier functions for the sprite immediately after creating it and adding it to the sprite list. For example:

 listofsprites.Add(new GMSprite(bitmap,behavior)); // create a new sprite
 listofsprites.Newest() -> SetPosition(200,150); // and set its position to 200,150

void HoldPlace()
void RestorePlace()

These functions remember a specific sprite in the list and let you return to it after cycling through more of the list. Call the HoldPlace function to remember the current sprite. Later, call the RestorePlace function to go back to that same sprite. These functions work kind of like a bookmark.

void DeleteFirst()
void DeleteLast()
void DeleteCurrent()
void Delete(GMSprite* pSprite)

These functions let you delete sprites from the list. They delete the very first one in the list, the last one in the list, the current sprite in the list, or the sprite whose address you send, respectively. These calls remove the sprites from memory, so be VERY careful if you have used pointer variables to try to remember a specific sprite outside of the context of the GMSpriteList. If you try to use a sprite that way after it's been deleted from the list, your program will crash and die an ugly death.

unsigned int Count()

This returns the number of sprites that are stored in the sprite list. Here's an alternate version to a loop given above:

 listofsprites.Reset();
 for (int i = 0; i < listofsprites.Count(); i++) // loop through all the sprites
       listofsprites.GetNext() -> Move(); // get the next sprite and move it

Note: The above loop is just an example of cycling through a GMSpriteList. You can accomplish the same task of the above loop with the one command:

 listofsprites.Move();