/* $Id: spritesequence.hpp,v 1.5.4.1 2006/01/20 11:23:31 chfreund Exp $ */

#ifndef  SPRITE_SEQUENCE_CLASS_DEFINED
#define  SPRITE_SEQUENCE_CLASS_DEFINED

/**********************************************************/

#include  <SDL.h>
#include  "string.hpp"
#include  "settingdefs.hpp"
#include  "pvector_t.hpp"
 
using namespace std;

/**********************************************************/

//! a vector of sprites

/*! This class is designed to represent animation sequences
 *  consisting of sprites.
 *  <br><br><br>
 *  <b>SYNTAX of the configuration file</b>
 *  <table border="0">
 *    <tr>
 *    <td><b>frames</b></td>
 *    <td>Name of the frame files. Only ONE string. It is formated like
 *        a format string used as parameter for the C-function printf.</td>
 *    </tr><tr>
 *    <td><b>indices</b></td>
 *    <td>Lower and upper bound for frame files. Two integers. These
 *        bounds will be used to create the acctual file names in
 *        combination with the string "frames". The ordering of the
 *        frames will be numerical one using these bounds.</td>
 *    </tr><tr>
 *    <td><b>colorkey</b></td>
 *    <td>colorkey in format RGB (optional). Transparent color.</td>
 *    </tr><tr>
 *    <td><b>alpha</b></td>
 *    <td>alpha value (optional). One value [0-255]. Constant alpha
 *        value for the whole image. Not necessary, if PNG format
 *        with built in alpha channel is used.</td>
 *    </tr><tr>
 *    <td><b>hotspot</b></td>
 *    <td>hot spot (optional). Two integers = (x,y)</td>
 *    </tr>
 *  </table>
 *  <br>
 *  example to load the pictures test003.bmp, test004.bmp, and test005.bmp:
 *  <br><br>
 *  \code
 *  frames   = test%03d.bmp
 *  indices  = 3, 5
 *  colorkey = 0
 *  alpha    = 100
 *  hotspot  = 20, 25
 *  \endcode
 */
template <class T>
class SpriteSequence : public PointerVector<T>,
                       public SpriteSequenceSettingDefs
{
	public:

		//! constructor for an empty sprite sequence

		/*! This constructor creates an empty sprite sequence.
		 *  \param size optionally the number of sprites in the
		 *         sequence can be passed to the constructor. It
		 *         will simply be passed to the constructor of the
		 *         base class PointerVector.
		 */
		SpriteSequence( const int size = -1 );
		//! destructor (will also delete all sprites)
		~SpriteSequence();

	 // setting access for the whole sequence
	 	//! sets the hot spot for all sprites in the sequence
		void setHotSpot( const int x, const int y );
		//! sets the color key for all sprites in the sequence
		bool setColorKey( const Uint8 red, const Uint8 green,
		                  const Uint8 blue );
		//! sets the alpha channel for all sprites in the sequence
		bool setAlphaValue( const Uint8 alpha );

		//! Draws frame [i] at point (x,y) on the surface "background".

		/*! In debug mode an error message is printed, if the frame [i]
		 *  does not exist.
		 *  \return the function returns the index of the next frame in
		 *          the sequence, i.e. 0, if i is the last frame in the
		 *          sequence. This might be usefull for example for
		 *          animations, shown in a loop.
		 */
		int  draw( SDL_Surface* background,
		           int i, const int x, const int y ) const;

		//! Loads a sequence from files specified in a configuration file.
		 
		/*! Loads a sequence from files specified in configuration file
		 *  "configfile", that is placed in the directory with the full
		 *  path "path". "section" is the name of the section the reading
		 *  of the configuration file should be restricted to. For details
		 *  about the syntax of the configuration file see below and the
		 *  documenation of class SettingDataBase.
		 *  \param path full path of the directory, the configuration file
		 *              is located in
		 *  \param configfile name of the configuration file
		 *  \param optional section name, the reading is restricted to
		 *         (see description of the file format and the documentation
		 *         of class SettingDataBase).
		 *  \return size of the sequence after the call
		 */
		int  load( const char* const path,
		           const char* const configfile,
		           const char* const section = NULL );

		//! Loads a sequence from files.

		/*! Loads a sequence from files, whose path contained in "settings"
		 *  start at "path". When passed to this function, "settings"
		 *  already must have passed SettingDataBase::finalCheck. This
		 *  reading of settings and final check is encapsulated in
		 *  SpriteSequence::readSettings.
		 *  \return size of the sequence after the call
		 */
		int  load( const char* const path,
		           const SettingDataBase& settings );
		
		//! reads the settings
		
		/*! Reads the settings for the sequence from a configuration file
		 *  with the name "configfile" into the class "settings". Reading
		 *  might be restricted to a section in the file, using "section"
		 *  (see also documentation of SettingDataBase::restrictToSection)
		 *  \return true, if "settings" can be used to load the sequence;
		 *          false, otherwise
		 */
		bool readSettings( const char* const configfile,
		                   SettingDataBase&  settings,
		                   const char* const section = NULL );

		
		const char* SettingID( const int i ) const;
		
	protected:
};

/**********************************************************/

#endif // SPRITE_SEQUENCE_CLASS_DEFINED