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