Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

XFuConfigurationData.h

Go to the documentation of this file.
00001 /*! \file
00002  * X-Forge Util <br>
00003  * Copyright 2000-2003 Fathammer Ltd
00004  *
00005  * $Id: XFuConfigurationData.h,v 1.17 2003/08/12 13:33:52 lars Exp $
00006  * $Date: 2003/08/12 13:33:52 $
00007  * $Revision: 1.17 $
00008  */
00009 
00010 #ifndef XFUCONFIGURATIONDATA_H_INCLUDED
00011 #define XFUCONFIGURATIONDATA_H_INCLUDED
00012 
00013 
00014 #include <xfutil/XFuConfiguration.h>
00015 
00016 class XFcGLResourceSurface;
00017 class XFuPrinter;
00018 
00019 
00020 //! Defines audio info flags for configuration data audio properties.
00021 /*! Audio properties' audio info flags determine which optional fields
00022  *  have been filled with data read from the configuration data file.
00023  */
00024 enum XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS
00025 {
00026     XFUCDAIF_NONE           = 0x00,     //!< No optional fields present.
00027     XFUCDAIF_SAMPLING_RATE  = 0x01,     //!< Sampling rate field.
00028     XFUCDAIF_VOLUME         = 0x02,     //!< Volume field.
00029     XFUCDAIF_PANNING        = 0x04,     //!< Panning field.
00030     XFUCDAIF_PRIORITY       = 0x08,     //!< Priority field.
00031     XFUCDAIF_LOOPING        = 0x10,     //!< Looping field.
00032     XFUCDAIF_LOOPSTART      = 0x20,     //!< Loop start field.
00033     XFUCDAIF_LOOPEND        = 0x40,     //!< Loop end field.
00034 };
00035 
00036 
00037 //! Sound sample configuration data type.
00038 /*! \sa XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS
00039  */
00040 class XFuConfigurationDataSoundInfo
00041 {
00042 
00043 public:
00044 
00045     CHAR *mFilename;            //!< Filename of the sound sample.
00046     FLOAT32 mSamplingRate;      //!< Sampling rate.
00047     REAL mVolume;               //!< Volume (1.0=original volume).
00048     REAL mPanning;              //!< Panning [0..1].
00049     UINT16 mPriority;           //!< Priority.
00050     INT mLooping;               //!< Non-zero if the sample is looping.
00051     INT32 mLoopStart;           //!< Loop start point.
00052     INT32 mLoopEnd;             //!< Loop end point.
00053     UINT32 mFlags;              //!< Flags, see XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS.
00054 
00055     XFuConfigurationDataSoundInfo() :
00056         mFilename(NULL), mSamplingRate(0.0f), mVolume(REALi(0)), mPanning(REALi(0)),
00057         mPriority(0), mLooping(0), mLoopStart(0), mLoopEnd(0), mFlags(0) {}
00058 
00059     virtual ~XFuConfigurationDataSoundInfo()
00060     {
00061         delete[] mFilename;
00062         mFilename = NULL;
00063     }
00064 
00065 };
00066 
00067 
00068 //! Music configuration data type.
00069 /*! \sa XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS
00070  */
00071 class XFuConfigurationDataMusicInfo
00072 {
00073 
00074 public:
00075 
00076     CHAR *mFilename;            //!< Filename of the sound sample.
00077     FLOAT32 mSamplingRate;      //!< Sampling rate.
00078     INT m16Bit;                 //!< Non-zero if 16 bit mixing requested, otherwise 8 bit.
00079     INT mStereo;                //!< Non-zero if stereo requested, otherwise mono.
00080     REAL mVolume;               //!< Volume (1.0=original volume).
00081     UINT16 mPriority;           //!< Priority.
00082     UINT32 mFlags;              //!< Flags, see XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS.
00083 
00084     XFuConfigurationDataMusicInfo() :
00085         mFilename(NULL), mSamplingRate(0.0f), m16Bit(0), mStereo(0),
00086         mVolume(REALi(0)), mPriority(0), mFlags(0) {}
00087 
00088     virtual ~XFuConfigurationDataMusicInfo()
00089     {
00090         delete[] mFilename;
00091         mFilename = NULL;
00092     }
00093 
00094 };
00095 
00096 
00097 //! Configured data container.
00098 /*!
00099  * Reads and parses a set of configuration data keys from a file.
00100  * The format of the configuration file is such that there is one property
00101  * on each row in a text file. Each property is a pair of a key and a value,
00102  * delimited by a '=' char, for example:
00103  * \code fileName = HelloWorld.xff \endcode
00104  *
00105  * Optionally the key can also have a type prefix which is delimited from the
00106  * rest of the key with a ':' (colon) char, for example:
00107  * \code image : cursor = arrow.tga \endcode
00108  * Recognized builtin types are parsed when the configuration file is processed.
00109  * For some types the data is also loaded at the same time. Note that for
00110  * recognized types the key is reformatted to use the short form before adding
00111  * to the data container, which affects only fetching of data with regular
00112  * get-method instead of a type specific getType-style method. If multiple keys
00113  * refer to exact same value which results in loading of a resource, the
00114  * resource is loaded only once so that the same loaded resource is shared
00115  * between the keys.
00116  *
00117  * Builtin types have getType-style methods which can be used to read the
00118  * data easily by the key omitting the type prefix. Builtin types also have
00119  * both long and short forms of the type, so the previous example could be
00120  * also written:
00121  * \code i:cursor = arrow.tga \endcode
00122  *
00123  * Leading and trailing spaces are trimmed. Lines starting with character '#'
00124  * are treated as comment lines and are ignored. Optional parts of
00125  * value strings can be omitted.
00126  *
00127  * Recognized builtin types:
00128  * <table><tr>
00129  * <th>Long Type<th>Short<br>Type<th>Value String Format and Description
00130  *
00131  * <tr><td>\c image <td>\c i
00132  *   <td>Value string: <tt>filename,type</tt>
00133  *   \li filename - filename of image which is loaded as a XFcGLResourceSurface
00134  *                  when the configuration file is processed.
00135  *   \li type - optional image format as a number (see XFCGFXFORMAT).
00136  *
00137  *   Example:
00138  *   \code
00139  *   image:menu.cursor = arrow.tga
00140  *   i:splash = splash.tga \endcode
00141  *
00142  * <tr><td>\c printer <td>\c p
00143  *   <td>Value string: <tt>filename,spacing,type,colorkey</tt>
00144  *   \li filename - filename where to load the printer font image from.
00145  *   \li spacing - default spacing for the printer.
00146  *   \li type - 0:standard printer (XFuPrinter), 1:RLE sprite printer (XFuRLESpritePrinter).
00147  *   \li colorkey - optional color key, hex strings can be used with 0x or # prefix.
00148  *
00149  *   Example:
00150  *   \code
00151  *   printer:menu.printer = smallfont.tga,0,1,#0000ff
00152  *   p:digitprinter = digits.tga,2,0 \endcode
00153  *
00154  * <tr><td>\c sound <td>\c s
00155  *   <td>Value string: <tt>filename,samplingrate,volume,panning,priority,looping,loopstart,loopend</tt>
00156  *   \li filename - filename of a sound sample.
00157  *   \li samplingrate - optional sampling rate as a real number (-1 = default).
00158  *   \li volume - optional volume as a real number (1.0 = original volume, -1 = default).
00159  *   \li panning - optional panning as a real number [0..1] (-1 = default).
00160  *   \li priority - optional priority as an integer [0..65535] (-1 = default).
00161  *   \li looping - optional looping flag, 0:no looping, 1:looping.
00162  *   \li loopstart - optional loop start point as an integer.
00163  *   \li loopend - optional loop end point as an integer.
00164  *
00165  *   Example:
00166  *   \code
00167  *   sound:menu.select = menuselect.wav
00168  *   s:menu.move = menumove.wav,-1,0.5 \endcode
00169  *
00170  * <tr><td>\c music <td>\c m
00171  *   <td>Value string: <tt>filename,samplingrate,chanmode,bitmode,volume,priority</tt>
00172  *   \li filename - filename of the music data.
00173  *   \li samplingrate - sampling rate for mixing the music as a real number.
00174  *   \li chanmode - channel mode, 0:mono, 1:stereo.
00175  *   \li bitmode - bits to use, 0:8 bits, 1:16 bits.
00176  *   \li volume - optional volume as a real number (1.0 = original volume, -1 = default).
00177  *   \li priority - optional priority as an integer [0..65535].
00178  *
00179  *   Example:
00180  *   \code
00181  *   music:menumusic = menu.xm,16000,0,0,0.3,0
00182  *   music:gamemusic = game.xm,8000,0,0,0.15,0 \endcode
00183  *
00184  * </table>
00185  *
00186  * \note XFuConfigurationData object owns all objects it has loaded, so you shouldn't
00187  *       delete manually any objects you access via this class.
00188  * \todo Type handler registration interface.
00189  *
00190  * \sa getImage
00191  * \sa XFcGLResourceSurface
00192  * \sa getPrinter
00193  * \sa XFuPrinter
00194  * \sa XFuRLESpritePrinter
00195  * \sa getRectangle
00196  * \sa XFcRectangle
00197  * \sa getSound
00198  * \sa XFuConfigurationDataSoundInfo
00199  * \sa getMusic
00200  * \sa XFuConfigurationDataMusicInfo
00201  * \sa XFuConfiguration
00202  * \sa XFcAudio
00203  */
00204 class XFuConfigurationData : public XFuConfiguration
00205 {
00206 
00207 public:
00208 
00209     //! Static constructor.
00210     /*! \return new configuration data object if successful, or NULL if unsuccessful.
00211      */
00212     static XFuConfigurationData * create();
00213 
00214     //! Static constructor.
00215     /*! \param aFilename filename of configuration data to load.
00216      * \return new configuration data object if successful, or NULL if unsuccessful.
00217      */
00218     static XFuConfigurationData * create(const CHAR *aFilename);
00219 
00220     //! Static constructor.
00221     /*! \param aFile open file pointing to configuration data to load.
00222      * \return new configuration data object if successful, or NULL if unsuccessful.
00223      * \note Configuration data is assumed to continue to end of the file.
00224      */
00225     static XFuConfigurationData * create(XFcFile *aFile);
00226     
00227     //! Virtual destructor.
00228     virtual ~XFuConfigurationData();
00229 
00230     //! Returns the value of a property as a string, or NULL if not found.
00231     /*! \param aKey key of the property to return.
00232      */
00233     virtual CHAR * get(const CHAR *aKey);
00234 
00235     //! Returns a configuration data image by key, or NULL if not found.
00236     /*! \param aKey key of the image omitting the type prefix and delimiter.
00237      * \return pointer to the image surface, or NULL if not found.
00238      */
00239     virtual XFcGLResourceSurface * getImage(const CHAR *aKey);
00240 
00241     //! Returns a configuration data printer by key, or NULL if not found.
00242     /*! \param aKey key of the printer omitting the type prefix and delimiter.
00243      * \return pointer to the printer, or NULL if not found.
00244      */
00245     virtual XFuPrinter * getPrinter(const CHAR *aKey);
00246 
00247     //! Returns a configuration data sound info by key, or NULL if not found.
00248     /*! \param aKey key of the sound omitting the type prefix and delimiter.
00249      * \return pointer to sound info, or NULL if not found.
00250      */
00251     virtual XFuConfigurationDataSoundInfo * getSound(const CHAR *aKey);
00252 
00253     //! Returns a configuration data music info by key, or NULL if not found.
00254     /*! \param aKey key of the music omitting the type prefix and delimiter.
00255      * \return pointer to music info, or NULL if not found.
00256      */
00257     virtual XFuConfigurationDataMusicInfo * getMusic(const CHAR *aKey);
00258 
00259     //! Gets a property value by key, and then parses and returns the value as a rectangle.
00260     /*!
00261      * Rectangle value string format: <tt>x,y,width,height</tt>.
00262      *   \li x - X-component of the rectangle as an integer.
00263      *   \li y - optional Y-component of the rectangle as an integer.
00264      *   \li width - optional width of the rectangle as an integer.
00265      *   \li height - optional height of the rectangle as an integer.
00266      *
00267      *   Example:
00268      *   \code
00269      *   rectangle:laptime.position = 10,10
00270      *   r:viewport = 4,4,160,120 \endcode
00271      *
00272      * \param aDest returned rectangle, if successful.
00273      * \param aKey key of the property value to be parsed.
00274      * \return 1 if successful (rectangle was found), or 0 if unsuccessful.
00275      */
00276     virtual INT getRectangle(XFcRectangle &aDest, const CHAR *aKey);
00277 
00278     //! Sets the value of a property.
00279     /*! If the key contains a type prefix delimited by ':' character from the
00280      *  rest of the key, and the type is a recognized builtin type, the value
00281      *  is parsed and possibly loaded according to the type. Properties with
00282      *  recognized builtin types can be accessed with type specific
00283      *  getType-style method. If the possible type prefix is unrecognized then
00284      *  the value must be accessed with get-method.
00285      * \param aKey full key of the property to set value for.
00286      * \param aValue value of the property.
00287      */
00288     virtual void put(const CHAR *aKey, const CHAR *aValue);
00289 
00290     //! Loads new configuration file and merges its data to the current set.
00291     /*! \param aFilename filename of the configuration data file to load.
00292      * \return 1 if successful, 0 if unsuccessful (e.g. file not found).
00293      */
00294     virtual INT load(const CHAR *aFilename);
00295 
00296     //! Loads new configuration file and merges its data to the current set.
00297     /*! \param aFile open file pointing to the configuration data to load.
00298      * \return 1 if successful, 0 if unsuccessful (e.g. file not found).
00299      * \note Configuration data is assumed to continue to end of the file.
00300      */
00301     virtual INT load(XFcFile *aFile);
00302     
00303     //! Parses a rectangle value string.
00304     /*! \return rectangle filled with available values, or an empty rectangle (0,0,0,0) if unsuccessful.
00305      */
00306     static XFcRectangle parseRectangleString(const CHAR *aValue);
00307 
00308     //! Sets deferred loading mode status.
00309     /*! When deferred loading mode is enabled, all recognized object types held
00310      *  by this configuration data container are loaded only when an object is
00311      *  requested for the first time. By default deferred loading is disabled
00312      *  and all recognized types are loaded on load of a configuration file.
00313      *  Deferred loading must be enabled before calling load.
00314      */
00315     void setDeferredLoadingEnabled(INT aEnabled);
00316 
00317 protected:
00318 
00319     //! Internal image container type.
00320     /*! \internal */
00321     typedef XFcHashtable<XFuStringKey, XFcGLResourceSurface *> ImageSet;
00322     //! Internal printer container type.
00323     /*! \internal */
00324     typedef XFcHashtable<XFuStringKey, XFuPrinter *> PrinterSet;
00325     //! Internal sound info container type.
00326     /*! \internal */
00327     typedef XFcHashtable<XFuStringKey, XFuConfigurationDataSoundInfo *> SoundSet;
00328     //! Internal music info container type.
00329     /*! \internal */
00330     typedef XFcHashtable<XFuStringKey, XFuConfigurationDataMusicInfo *> MusicSet;
00331 
00332     //! Protected constructor.
00333     XFuConfigurationData();
00334 
00335     //! Initializes a newly constructed object.
00336     /*! \return 1 if successful, 0 if unsuccessful.
00337      */
00338     INT init();
00339 
00340     //! Adds and possibly loads a new image to the internal image container.
00341     void addImage(const CHAR *aValue);
00342     //! Adds and possibly loads a new printer to the internal printer container.
00343     void addPrinter(const CHAR *aValue);
00344     //! Adds a new sound to the internal sound container.
00345     void addSound(const CHAR *aValue);
00346     //! Adds a new music to the internal music container.
00347     void addMusic(const CHAR *aValue);
00348 
00349     //! Loads a new image to the internal image container.
00350     void loadImage(ImageSet::iterator &aIterator);
00351     //! Loads a new printer to the internal printer container.
00352     void loadPrinter(PrinterSet::iterator &aIterator);
00353 
00354     //! Allocates and returns a new key with a specified prefix char.
00355     CHAR * makePrefixedKey(const CHAR aPrefix, const CHAR *aKey);
00356 
00357     //! Non-zero if deferred loading is enabled.
00358     INT mDeferredLoadingEnabled;
00359 
00360     ImageSet *mImages;          //!< Internal image container.
00361     PrinterSet *mPrinters;      //!< Internal printer container.
00362     SoundSet *mSounds;          //!< Internal sound container.
00363     MusicSet *mMusics;          //!< Internal music container.
00364 
00365 };
00366 
00367 
00368 #endif // !XFUCONFIGURATIONDATA_H_INCLUDED
00369 

   
X-Forge Documentation
Confidential
Copyright © 2002-2003 Fathammer
   
Documentation generated
with doxygen
by Dimitri van Heesch