Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 11, 2010, 12:34:00 AM (15 years ago)
Author:
landauf
Message:

merged doc branch back to trunk

Location:
code/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • code/trunk

  • code/trunk/src/libraries/core/ConfigFileManager.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Config ConfigFile
     32    @brief Declaration of ConfigFileManager and its helper classes, used to load and save config files.
     33*/
     34
    2935#ifndef _ConfigFileManager_H__
    3036#define _ConfigFileManager_H__
    … …  
    4652    // ConfigFileEntry //
    4753    /////////////////////
     54    /**
     55        @brief This class represents an entry in the config file.
     56
     57        This class is pure virtual. Use one of the derived classes to define the type of the entry.
     58    */
    4859    class _CoreExport ConfigFileEntry
    4960    {
    5061        public:
     62            /// Destructor
    5163            virtual ~ConfigFileEntry() {};
     64
     65            /// Changes the value of the entry.
    5266            virtual void setValue(const std::string& value) = 0;
     67            /// Returns the value of the entry.
    5368            virtual const std::string& getValue() const = 0;
     69
     70            /// Returns the name of the entry
    5471            virtual const std::string& getName() const = 0;
     72
     73            /// Changes the comment of the entry (will be placed after the value)
    5574            virtual void setComment(const std::string& comment) = 0;
     75
     76            /// Returns the index of the entry in a vector (used only if it is a vector)
    5677            virtual unsigned int getIndex() const { return 0; }
     78
     79            /// Defines if this entry is treated as string which means some special treatment of special characters.
    5780            virtual void setString(bool bString) = 0;
     81
     82            /// Returns the line as it will be stored in the config file.
    5883            virtual const std::string& getFileEntry() const = 0;
    5984    };
    … …  
    6388    // ConfigFileEntryValue //
    6489    //////////////////////////
     90    /**
     91        @brief This class represents a normal value in the config file.
     92    */
    6593    class _CoreExport ConfigFileEntryValue : public ConfigFileEntry
    6694    {
    6795        public:
     96            /**
     97                @brief Constructor: Initializes the entry.
     98
     99                @param name                 The name of the entry
     100                @param value                The value of the entry
     101                @param bString              If true, the value is treated as string which means some special treatment of special characters.
     102                @param additionalComment    An optional comment that will be placed behind the value in the config file
     103            */
    68104            inline ConfigFileEntryValue(const std::string& name, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    69105                : name_(name)
    … …  
    73109                { this->update(); }
    74110
     111            /// Destructor
    75112            inline virtual ~ConfigFileEntryValue() {}
    76113
    … …  
    92129                { return this->fileEntry_; }
    93130
     131            /// Returns the "key" of the value (in this case it's just the name of the entry, but for vectors it's different)
    94132            inline virtual const std::string& getKeyString() const
    95133                { return this->name_; }
    … …  
    98136            virtual void update();
    99137
    100             const std::string name_;
    101             std::string value_;
    102             std::string additionalComment_;
    103             std::string fileEntry_;
    104             bool bString_;
     138            const std::string name_;            ///< The name of the value
     139            std::string value_;                 ///< The value
     140            std::string additionalComment_;     ///< The additional comment
     141            std::string fileEntry_;             ///< The string as it will be stored in the config file
     142            bool bString_;                      ///< If true, the value is treated as string which means some special treatment of special characters.
    105143    };
    106144
    … …  
    109147    // ConfigFileEntryVectorValue //
    110148    ////////////////////////////////
     149    /**
     150        @brief Subclass of ConfigFileEntryValue, represents an element of a vector.
     151    */
    111152    class _CoreExport ConfigFileEntryVectorValue : public ConfigFileEntryValue
    112153    {
    113154        public:
     155            /**
     156                @brief Constructor: Initializes the entry.
     157
     158                @param name                 The name of the vector
     159                @param index                The index of the element in the vector
     160                @param value                The value of the element
     161                @param bString              If true, the value is treated as string which means some special treatment of special characters.
     162                @param additionalComment    An optional comment that will be placed behind the value in the config file
     163            */
    114164            inline ConfigFileEntryVectorValue(const std::string& name, unsigned int index, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    115165                : ConfigFileEntryValue(name, value, bString, additionalComment)
    … …  
    117167                { this->update(); /*No virtual calls in base class ctor*/ }
    118168
     169            /// Destructor
    119170            inline ~ConfigFileEntryVectorValue() {}
    120171
    … …  
    122173                { return this->index_; }
    123174
     175            /// Returns the "key" of the value (the name of the vector plus the index of the element)
    124176            inline const std::string& getKeyString() const
    125177                { return this->keyString_; }
    … …  
    128180            void update();
    129181
    130             unsigned int index_;
    131             std::string keyString_;
     182            unsigned int index_;        ///< The index of the element in the vector
     183            std::string keyString_;     ///< The full name of the entry (the name of the vector plus the index of the element)
    132184    };
    133185
    … …  
    136188    // ConfigFileEntryComment //
    137189    ////////////////////////////
     190    /**
     191        @brief This class represents a line in the config file which contains only a comment.
     192    */
    138193    class _CoreExport ConfigFileEntryComment : public ConfigFileEntry
    139194    {
    140195        public:
     196            /// Constructor: Initializes the object.
    141197            inline ConfigFileEntryComment(const std::string& comment) : comment_(comment) {}
     198
     199            /// Destructor
    142200            inline virtual ~ConfigFileEntryComment() {}
    143201
    … …  
    159217                { return this->comment_; }
    160218
    161             inline virtual const std::string& getKeyString() const
    162                 { return BLANKSTRING; }
    163 
    164219        private:
    165             std::string comment_;
     220            std::string comment_;   ///< The comment
    166221    };
    167222
    … …  
    170225    // ConfigFileSection //
    171226    ///////////////////////
     227    /**
     228        @brief Represents a section in a config file.
     229
     230        A section has a name and a list of config values.
     231    */
    172232    class _CoreExport ConfigFileSection
    173233    {
    … …  
    176236
    177237        public:
     238            /**
     239                @brief Constructor: Initializes the section.
     240
     241                @param name The name of the section
     242                @param additionalComment An additional comment placed after the title of the section in the config file
     243            */
    178244            inline ConfigFileSection(const std::string& name, const std::string& additionalComment = "")
    179245                : name_(name)
    … …  
    183249            ~ConfigFileSection();
    184250
     251            /// Returns the name of the section.
    185252            inline const std::string& getName() const
    186253                { return this->name_; }
    187254
     255            /// Changes the comment which is placed after the title of the section in the config file.
    188256            inline void setComment(const std::string& comment)
    189257                { this->additionalComment_ = comment; }
    190258
     259            /**
     260                @brief Stores a value in the section. If the entry doesn't exist, it's created.
     261
     262                @param name     The name of the entry
     263                @param value    The new value
     264                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     265            */
    191266            inline void setValue(const std::string& name, const std::string& value, bool bString)
    192267                { this->getOrCreateEntry(name, value, bString)->setValue(value); }
     268            /**
     269                @brief Returns the value of a given entry in the section. Returns a blank string if the value doesn't exist.
     270
     271                @param name     The name of the entry
     272                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     273            */
    193274            inline const std::string& getValue(const std::string& name, bool bString)
    194275            {
    … …  
    196277                if (entry)
    197278                {
    198                     entry->setString(bString);
     279                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
    199280                    return entry->getValue();
    200281                }
    201282                return BLANKSTRING;
    202283            }
     284            /**
     285                @brief Returns the value of a given entry in the section. If it doesn't exist, the entry is created using the fallback value.
     286
     287                @param name     The name of the entry
     288                @param fallback The value that will be used if the entry doesn't exist
     289                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     290            */
    203291            inline const std::string& getOrCreateValue(const std::string& name, const std::string& fallback, bool bString)
    204292                { return this->getOrCreateEntry(name, fallback, bString)->getValue(); }
    205293
     294            /**
     295                @brief Stores the value of an element of a vector in the section. If the entry doesn't exist, it's created.
     296
     297                @param name     The name of the vector
     298                @param index    The index of the element in the vector
     299                @param value    The new value
     300                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     301            */
    206302            inline void setValue(const std::string& name, unsigned int index, const std::string& value, bool bString)
    207303                { this->getOrCreateEntry(name, index, value, bString)->setValue(value); }
     304            /**
     305                @brief Returns the value of a given element of a vector in the section. Returns a blank string if the value doesn't exist.
     306
     307                @param name     The name of the vector
     308                @param index    The index of the element in the vector
     309                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     310            */
    208311            inline const std::string& getValue(const std::string& name, unsigned int index, bool bString)
    209312            {
    … …  
    211314                if (entry)
    212315                {
    213                     entry->setString(bString);
     316                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
    214317                    return entry->getValue();
    215318                }
    216319                return BLANKSTRING;
    217320            }
     321            /**
     322                @brief Returns the value of a given element of a vector in the section. If it doesn't exist, the entry is created using the fallback value.
     323
     324                @param name     The name of the vector
     325                @param index    The index of the element in the vector
     326                @param fallback The value that will be used if the entry doesn't exist
     327                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     328            */
    218329            inline const std::string& getOrCreateValue(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    219330                { return this->getOrCreateEntry(name, index, fallback, bString)->getValue(); }
    … …  
    225336
    226337        private:
     338            /// Returns the list of entries in this section.
    227339            std::list<ConfigFileEntry*>& getEntries()
    228340                { return this->entries_; }
     341            /// Returns the begin-iterator of the list of entries in this section.
    229342            std::list<ConfigFileEntry*>::const_iterator getEntriesBegin() const
    230343                { return this->entries_.begin(); }
     344            /// Returns the end-iterator of the list of entries in this section.
    231345            std::list<ConfigFileEntry*>::const_iterator getEntriesEnd() const
    232346                { return this->entries_.end(); }
    … …  
    236350
    237351            ConfigFileEntry* getEntry(const std::string& name) const;
     352            /**
     353                @brief Returns the entry with given name. If it doesn't exist, the entry is created using the fallback value.
     354
     355                @param name     The name of the entry
     356                @param fallback The value that will be used if the entry doesn't exist
     357                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     358            */
    238359            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, const std::string& fallback, bool bString)
    239360                { return (*this->getOrCreateEntryIterator(name, fallback, bString)); }
     361
    240362            ConfigFileEntry* getEntry(const std::string& name, unsigned int index) const;
     363            /**
     364                @brief Returns the entry that contains an element of a vector with given name. If it doesn't exist, the entry is created using the fallback value.
     365
     366                @param name     The name of the entry
     367                @param index    The index of the element in the vector
     368                @param fallback The value that will be used if the entry doesn't exist
     369                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     370            */
    241371            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    242372                { return (*this->getOrCreateEntryIterator(name, index, fallback, bString)); }
    243373
    244             std::string name_;
    245             std::string additionalComment_;
    246             std::list<ConfigFileEntry*> entries_;
    247             bool bUpdated_;
     374            std::string name_;                      ///< The name of the section
     375            std::string additionalComment_;         ///< The additional comment which is placed after the title of the section in the config file
     376            std::list<ConfigFileEntry*> entries_;   ///< The list of entries in this section
     377            bool bUpdated_;                         ///< True if an entry is created
    248378    };
    249379
    … …  
    252382    // ConfigFile //
    253383    ////////////////
     384    /**
     385        @brief This class represents a config file, which is stored on the hard-disk and contains config values in different sections.
     386
     387        It provides an interface to manipulate the sections and values.
     388    */
    254389    class _CoreExport ConfigFile
    255390    {
    … …  
    263398            virtual void clear();
    264399
     400            /// Returns the file-name of this config file
    265401            inline const std::string& getFilename()
    266402                { return this->filename_; }
    267403
     404            /**
     405                @brief Stores a value in the config file. If the entry or its section doesn't exist, it's created.
     406
     407                @param section  The name of the section
     408                @param name     The name of the entry
     409                @param value    The new value
     410                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     411            */
    268412            inline void setValue(const std::string& section, const std::string& name, const std::string& value, bool bString)
    269413            {
    … …  
    271415                this->save();
    272416            }
     417            /**
     418                @brief Returns the value of a given entry in the config file. Returns a blank string if the value doesn't exist.
     419
     420                @param section  The name of the section
     421                @param name     The name of the entry
     422                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     423            */
    273424            inline const std::string& getValue(const std::string& section, const std::string& name, bool bString)
    274425            {
    … …  
    276427                return (sectionPtr ? sectionPtr->getValue(name, bString) : BLANKSTRING);
    277428            }
    278             const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString);
    279 
     429            /**
     430                @brief Returns the value of a given entry in the config file. If it doesn't exist, the entry is created using the fallback value.
     431
     432                @param section  The name of the section
     433                @param name     The name of the entry
     434                @param fallback The value that will be used if the entry doesn't exist
     435                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     436            */
     437            inline const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString)
     438            {
     439                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, fallback, bString);
     440                this->saveIfUpdated();
     441                return output;
     442            }
     443
     444            /**
     445                @brief Stores the value of an element of a vector in the config file. If the entry or its section doesn't exist, it's created.
     446
     447                @param section  The name of the section
     448                @param name     The name of the vector
     449                @param index    The index of the element in the vector
     450                @param value    The new value
     451                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     452            */
    280453            inline void setValue(const std::string& section, const std::string& name, unsigned int index, const std::string& value, bool bString)
    281454            {
    … …  
    283456                this->save();
    284457            }
     458            /**
     459                @brief Returns the value of a given element of a vector in the config file. Returns a blank string if the value doesn't exist.
     460
     461                @param section  The name of the section
     462                @param name     The name of the vector
     463                @param index    The index of the element in the vector
     464                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     465            */
    285466            inline const std::string& getValue(const std::string& section, const std::string& name, unsigned int index, bool bString)
    286467            {
    … …  
    288469                return (sectionPtr ? sectionPtr->getValue(name, index, bString) : BLANKSTRING);
    289470            }
    290             const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString);
     471            /**
     472                @brief Returns the value of a given element of a vector in the config file. If it doesn't exist, the entry is created using the fallback value.
     473
     474                @param section  The name of the section
     475                @param name     The name of the vector
     476                @param index    The index of the element in the vector
     477                @param fallback The value that will be used if the entry doesn't exist
     478                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     479            */
     480            const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString)
     481            {
     482                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, index, fallback, bString);
     483                this->saveIfUpdated();
     484                return output;
     485            }
    291486
    292487            void deleteVectorEntries(const std::string& section, const std::string& name, unsigned int startindex = 0);
     488            /**
     489                @brief Returns the size of a config vector.
     490                @param section  The section of the vector
     491                @param name     The name of the vector
     492            */
    293493            inline unsigned int getVectorSize(const std::string& section, const std::string& name) const
    294494            {
    … …  
    297497            }
    298498
    299             static const char* DEFAULT_CONFIG_FOLDER;
     499            static const char* DEFAULT_CONFIG_FOLDER;   ///< The folder where the default config files will be stored
    300500
    301501        protected:
    … …  
    303503            ConfigFileSection* getOrCreateSection(const std::string& section);
    304504
    305             std::list<ConfigFileSection*> sections_;
     505            std::list<ConfigFileSection*> sections_;    ///< A list of sections in this config file
    306506
    307507        private:
    308508            void saveIfUpdated();
    309             const std::string filename_;
    310             const bool bCopyFallbackFile_;
    311             bool bUpdated_;
     509
     510            const std::string filename_;                ///< The filename of this config file
     511            const bool bCopyFallbackFile_;              ///< If true, the default config file is copied into the config-directory before loading the file
     512            bool bUpdated_;                             ///< Becomes true if a section is added
    312513    };
    313514
    … …  
    316517    // SettingsConfigFile //
    317518    ////////////////////////
     519    /**
     520        @brief Child class of ConfigFile, used to store the settings of the game.
     521
     522        In addition to ConfigFile, this class provides an interface to manipulate the settings
     523        with console commands and to cache entries in instances of ConfigValueContainer.
     524
     525        SettingsConfigFile is a Singleton, meaning there's only one instance of this class
     526        (and thus only one config file that stores settings).
     527    */
    318528    class _CoreExport SettingsConfigFile // tolua_export
    319529        : public ConfigFile, public Singleton<SettingsConfigFile>
    … …  
    338548            void removeConfigValueContainer(ConfigValueContainer* container);
    339549
     550            /// Returns a set containing the names of all sections in this config file.
    340551            inline const std::set<std::string>& getSectionNames()
    341552                { return this->sectionNames_; }
     553            /// Returns the lower-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    342554            inline ContainerMap::const_iterator getContainerLowerBound(const std::string section)
    343555                { return this->containers_.lower_bound(section); }
     556            /// Returns the upper-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    344557            inline ContainerMap::const_iterator getContainerUpperBound(const std::string section)
    345558                { return this->containers_.upper_bound(section); }
    … …  
    351564            bool configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&));
    352565
    353             ContainerMap containers_;
    354             std::set<std::string> sectionNames_;
    355             static SettingsConfigFile* singletonPtr_s;
     566            ContainerMap containers_;                   ///< Stores all @ref ConfigValueContainer "config value containers"
     567            std::set<std::string> sectionNames_;        ///< Stores all section names
     568            static SettingsConfigFile* singletonPtr_s;  ///< The singleton pointer
    356569    }; // tolua_export
    357570
    … …  
    360573    // ConfigFileManager //
    361574    ///////////////////////
     575    /**
     576        @brief Manages the different config files (settings, calibration, etc). Implemented as Singleton.
     577    */
    362578    class _CoreExport ConfigFileManager : public Singleton<ConfigFileManager>
    363579    {
    … …  
    369585            void setFilename(ConfigFileType::Value type, const std::string& filename);
    370586
     587            /// Returns the config file of a given type (settings, calibration, etc.)
    371588            inline ConfigFile* getConfigFile(ConfigFileType::Value type)
    372589            {
    … …  
    376593
    377594        private:
    378             ConfigFileManager(const ConfigFileManager&);
    379 
    380             boost::array<ConfigFile*, 3> configFiles_;
    381             static ConfigFileManager* singletonPtr_s;
     595            ConfigFileManager(const ConfigFileManager&);    ///< Copy-constructor: not implemented
     596
     597            boost::array<ConfigFile*, 3> configFiles_;      ///< Stores the config files for each type in an array (must have the same size like ConfigFileType::Value)
     598            static ConfigFileManager* singletonPtr_s;       ///< Stores the singleton-pointer
    382599    };
    383600} // tolua_export
Note: See TracChangeset for help on using the changeset viewer.