Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 7373 for code/branches/doc/src


Ignore:
Timestamp:
Sep 7, 2010, 11:24:47 PM (14 years ago)
Author:
landauf
Message:

added documentation

Location:
code/branches/doc/src/libraries/core
Files:
6 edited

Legend:

Unmodified
Added
Removed
  • code/branches/doc/src/libraries/core/ConfigFileManager.cc

    r7284 r7373  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of ConfigFileManager and its helper classes.
     32*/
     33
    2934#include "ConfigFileManager.h"
    3035
     
    4348    // ConfigFileEntryValue //
    4449    //////////////////////////
    45 
     50    /**
     51        @brief Updates the string that will be stored in the file after one of it's components (name, value, comment) has changed.
     52    */
    4653    void ConfigFileEntryValue::update()
    4754    {
     
    6370    // ConfigFileEntryVectorValue //
    6471    ////////////////////////////////
     72    /**
     73        @brief Updates the string that will be stored in the file after one of it's components (name, value, index, comment) has changed.
     74    */
    6575    void ConfigFileEntryVectorValue::update()
    6676    {
     
    7383    // ConfigFileSection //
    7484    ///////////////////////
     85    /**
     86        @brief Destructor: Deletes all entries.
     87    */
    7588    ConfigFileSection::~ConfigFileSection()
    7689    {
     
    7992    }
    8093
     94    /**
     95        @brief Deletes all elements of a config vector if their index is greater or equal to @a startindex.
     96
     97        @param name         The name of the vector
     98        @param startindex   The index of the first element that will be deleted
     99    */
    81100    void ConfigFileSection::deleteVectorEntries(const std::string& name, unsigned int startindex)
    82101    {
     
    95114    }
    96115
     116    /**
     117        @brief Returns the size of a config vector.
     118        @param name     The name of the vector
     119    */
    97120    unsigned int ConfigFileSection::getVectorSize(const std::string& name) const
    98121    {
     
    108131    }
    109132
     133    /**
     134        @brief Returns the title and comment of the section as it will be stored in the file.
     135    */
    110136    std::string ConfigFileSection::getFileEntry() const
    111137    {
     
    116142    }
    117143
     144    /**
     145        @brief Returns the entry with given name (or NULL if it doesn't exist).
     146
     147        @param name     The name of the entry
     148    */
    118149    ConfigFileEntry* ConfigFileSection::getEntry(const std::string& name) const
    119150    {
     
    126157    }
    127158
     159    /**
     160        @brief Returns the entry of a vector element with given name and index (or NULL if it doesn't exist).
     161
     162        @param name     The name of the vector
     163        @param index    The index of the element in the vector
     164    */
    128165    ConfigFileEntry* ConfigFileSection::getEntry(const std::string& name, unsigned int index) const
    129166    {
     
    136173    }
    137174
     175    /**
     176        @brief Returns the iterator to the entry with given name. If the entry doesn't exist, it is created using the fallback value.
     177
     178        @param name     The name of the entry
     179        @param fallback The value that will be used if the entry doesn't exist
     180        @param bString  If true, the value is treated as string which means some special treatment of special characters.
     181    */
    138182    std::list<ConfigFileEntry*>::iterator ConfigFileSection::getOrCreateEntryIterator(const std::string& name, const std::string& fallback, bool bString)
    139183    {
     
    152196    }
    153197
     198    /**
     199        @brief Returns the iterator to the entry of a vector element with given name and index. If the entry doesn't exist, it is created using the fallback value.
     200
     201        @param name     The name of the vector
     202        @param index    The index of the element in the vector
     203        @param fallback The value that will be used if the entry doesn't exist
     204        @param bString  If true, the value is treated as string which means some special treatment of special characters.
     205    */
    154206    std::list<ConfigFileEntry*>::iterator ConfigFileSection::getOrCreateEntryIterator(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    155207    {
     
    178230    const char* ConfigFile::DEFAULT_CONFIG_FOLDER = "defaultConfig";
    179231
     232    /**
     233        @brief Constructor: Initializes the config file.
     234        @param filename The file-name of this config file
     235        @param bCopyFallbackFile If true, the default config file is copied into the config-directory before loading the file
     236    */
    180237    ConfigFile::ConfigFile(const std::string& filename, bool bCopyFallbackFile)
    181238        : filename_(filename)
     
    185242    }
    186243
     244    /**
     245        @brief Destructor: Deletes all sections and entries.
     246    */
    187247    ConfigFile::~ConfigFile()
    188248    {
     
    190250    }
    191251
     252    /**
     253        @brief Loads the config file from the hard-disk and reads the sections and their values.
     254    */
    192255    void ConfigFile::load()
    193256    {
     
    318381    }
    319382
     383    /**
     384        @brief Writes the sections and values to the hard-disk.
     385    */
    320386    void ConfigFile::save() const
    321387    {
     
    323389    }
    324390
     391    /**
     392        @brief Writes the sections and values to a given file on the hard-disk.
     393    */
    325394    void ConfigFile::saveAs(const std::string& filename) const
    326395    {
     
    354423    }
    355424
     425    /**
     426        @brief Deletes all sections (which again delete all their values) and clears the list of sections.
     427    */
    356428    void ConfigFile::clear()
    357429    {
     
    361433    }
    362434
    363     const std::string& ConfigFile::getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString)
    364     {
    365         const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, fallback, bString);
    366         this->saveIfUpdated();
    367         return output;
    368     }
    369 
    370     const std::string& ConfigFile::getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    371     {
    372         const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, index, fallback, bString);
    373         this->saveIfUpdated();
    374         return output;
    375     }
    376 
     435    /**
     436        @brief Deletes all elements of a config vector if their index is greater or equal to @a startindex.
     437
     438        @param section      The name of the section
     439        @param name         The name of the vector
     440        @param startindex   The index of the first element that will be deleted
     441    */
    377442    void ConfigFile::deleteVectorEntries(const std::string& section, const std::string& name, unsigned int startindex)
    378443    {
     
    384449    }
    385450
     451    /**
     452        @brief Returns a pointer to the section with given name (or NULL if the section doesn't exist).
     453    */
    386454    ConfigFileSection* ConfigFile::getSection(const std::string& section) const
    387455    {
     
    392460    }
    393461
     462    /**
     463        @brief Returns a pointer to the section with given name. If it doesn't exist, the section is created.
     464    */
    394465    ConfigFileSection* ConfigFile::getOrCreateSection(const std::string& section)
    395466    {
     
    403474    }
    404475
     476    /**
     477        @brief Saves the config file if it was updated (or if any of its sections were updated).
     478    */
    405479    void ConfigFile::saveIfUpdated()
    406480    {
     
    442516    SettingsConfigFile* SettingsConfigFile::singletonPtr_s = 0;
    443517
     518    /**
     519        @brief Constructor: Activates the console commands.
     520    */
    444521    SettingsConfigFile::SettingsConfigFile(const std::string& filename)
    445522        : ConfigFile(filename)
     
    452529    }
    453530
     531    /**
     532        @brief Destructor: Deactivates the console commands.
     533    */
    454534    SettingsConfigFile::~SettingsConfigFile()
    455535    {
     
    461541    }
    462542
     543    /**
     544        @brief Loads the config file and updates the @ref ConfigValueContainer "config value containers".
     545    */
    463546    void SettingsConfigFile::load()
    464547    {
     
    467550    }
    468551
     552    /**
     553        @brief Changes the file-name.
     554    */
    469555    void SettingsConfigFile::setFilename(const std::string& filename)
    470556    {
     
    472558    }
    473559
     560    /**
     561        @brief Registers a new @ref ConfigValueContainer "config value container".
     562    */
    474563    void SettingsConfigFile::addConfigValueContainer(ConfigValueContainer* container)
    475564    {
     
    481570    }
    482571
     572    /**
     573        @brief Unregisters a @ref ConfigValueContainer "config value container".
     574    */
    483575    void SettingsConfigFile::removeConfigValueContainer(ConfigValueContainer* container)
    484576    {
     
    500592    }
    501593
     594    /**
     595        @brief Updates all @ref ConfigValueContainer "config value containers".
     596    */
    502597    void SettingsConfigFile::updateConfigValues()
    503598    {
     599        // todo: can this be done more efficiently? looks like some identifiers will be updated multiple times.
     600
    504601        for (ContainerMap::const_iterator it = this->containers_.begin(); it != this->containers_.end(); ++it)
    505602        {
     
    509606    }
    510607
     608    /**
     609        @brief Removes entries and sections from the file that don't exist anymore (i.e. if there's no corresponding @ref ConfigValueContainer "config value container").
     610        @param bCleanComments If true, comments are also removed from the file
     611    */
    511612    void SettingsConfigFile::clean(bool bCleanComments)
    512613    {
     
    558659    }
    559660
     661    /**
     662        @brief Console-command: Changes the value of an entry and stores it the file.
     663
     664        @param section  The section of the config value
     665        @param entry    The name of the config value
     666        @param value    The new value
     667    */
    560668    void SettingsConfigFile::config(const std::string& section, const std::string& entry, const std::string& value)
    561669    {
     
    564672    }
    565673
     674    /**
     675        @brief Console-command: Changes the value of an entry, but doesn't store it in the file (it's only a temporary change).
     676
     677        @param section  The section of the config value
     678        @param entry    The name of the config value
     679        @param value    The new value
     680    */
    566681    void SettingsConfigFile::tconfig(const std::string& section, const std::string& entry, const std::string& value)
    567682    {
     
    570685    }
    571686
     687    /**
     688        @brief Changes the value of an entry, depending on @a function, either by using "set" or "tset"
     689
     690        @param section  The section of the config value
     691        @param entry    The name of the config value
     692        @param value    The new value
     693        @param function The function ("set" or "tset") that will be used to change the value.
     694    */
    572695    bool SettingsConfigFile::configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&))
    573696    {
     
    586709    }
    587710
     711    /**
     712        @brief Console-command: Returns the value of a given entry.
     713
     714        @param section  The section of the config value
     715        @param entry    The name of the config value
     716    */
    588717    std::string SettingsConfigFile::getConfig(const std::string& section, const std::string& entry)
    589718    {
     
    611740    ConfigFileManager* ConfigFileManager::singletonPtr_s = 0;
    612741
     742    /// Constructor: Initializes the array of config files with NULL.
    613743    ConfigFileManager::ConfigFileManager()
    614744    {
     
    616746    }
    617747
     748    /// Destructor: Deletes the config files.
    618749    ConfigFileManager::~ConfigFileManager()
    619750    {
     
    623754    }
    624755
     756    /// Defines the file-name for the config file of a given type (settings, calibration, etc.).
    625757    void ConfigFileManager::setFilename(ConfigFileType::Value type, const std::string& filename)
    626758    {
  • code/branches/doc/src/libraries/core/ConfigFileManager.h

    r7363 r7373  
    3030    @file
    3131    @ingroup Config ConfigFile
     32    @brief Declaration of ConfigFileManager and its helper classes.
    3233*/
    3334
     
    5152    // ConfigFileEntry //
    5253    /////////////////////
     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    */
    5359    class _CoreExport ConfigFileEntry
    5460    {
    5561        public:
     62            /// Destructor
    5663            virtual ~ConfigFileEntry() {};
     64
     65            /// Changes the value of the entry.
    5766            virtual void setValue(const std::string& value) = 0;
     67            /// Returns the value of the entry.
    5868            virtual const std::string& getValue() const = 0;
     69
     70            /// Returns the name of the entry
    5971            virtual const std::string& getName() const = 0;
     72
     73            /// Changes the comment of the entry (will be placed after the value)
    6074            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)
    6177            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.
    6280            virtual void setString(bool bString) = 0;
     81
     82            /// Returns the line as it will be stored in the config file.
    6383            virtual const std::string& getFileEntry() const = 0;
    6484    };
     
    6888    // ConfigFileEntryValue //
    6989    //////////////////////////
     90    /**
     91        @brief This class represents a normal value in the config file.
     92    */
    7093    class _CoreExport ConfigFileEntryValue : public ConfigFileEntry
    7194    {
    7295        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            */
    73104            inline ConfigFileEntryValue(const std::string& name, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    74105                : name_(name)
     
    78109                { this->update(); }
    79110
     111            /// Destructor
    80112            inline virtual ~ConfigFileEntryValue() {}
    81113
     
    97129                { return this->fileEntry_; }
    98130
     131            /// Returns the "key" of the value (in this case it's just the name of the entry, but for vectors it's different)
    99132            inline virtual const std::string& getKeyString() const
    100133                { return this->name_; }
     
    103136            virtual void update();
    104137
    105             const std::string name_;
    106             std::string value_;
    107             std::string additionalComment_;
    108             std::string fileEntry_;
    109             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.
    110143    };
    111144
     
    114147    // ConfigFileEntryVectorValue //
    115148    ////////////////////////////////
     149    /**
     150        @brief Subclass of ConfigFileEntryValue, represents an element of a vector.
     151    */
    116152    class _CoreExport ConfigFileEntryVectorValue : public ConfigFileEntryValue
    117153    {
    118154        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            */
    119164            inline ConfigFileEntryVectorValue(const std::string& name, unsigned int index, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    120165                : ConfigFileEntryValue(name, value, bString, additionalComment)
     
    122167                { this->update(); /*No virtual calls in base class ctor*/ }
    123168
     169            /// Destructor
    124170            inline ~ConfigFileEntryVectorValue() {}
    125171
     
    127173                { return this->index_; }
    128174
     175            /// Returns the "key" of the value (the name of the vector plus the index of the element)
    129176            inline const std::string& getKeyString() const
    130177                { return this->keyString_; }
     
    133180            void update();
    134181
    135             unsigned int index_;
    136             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)
    137184    };
    138185
     
    141188    // ConfigFileEntryComment //
    142189    ////////////////////////////
     190    /**
     191        @brief This class represents a line in the config file which contains only a comment.
     192    */
    143193    class _CoreExport ConfigFileEntryComment : public ConfigFileEntry
    144194    {
    145195        public:
     196            /// Constructor: Initializes the object.
    146197            inline ConfigFileEntryComment(const std::string& comment) : comment_(comment) {}
     198
     199            /// Destructor
    147200            inline virtual ~ConfigFileEntryComment() {}
    148201
     
    164217                { return this->comment_; }
    165218
    166             inline virtual const std::string& getKeyString() const
    167                 { return BLANKSTRING; }
    168 
    169219        private:
    170             std::string comment_;
     220            std::string comment_;   ///< The comment
    171221    };
    172222
     
    175225    // ConfigFileSection //
    176226    ///////////////////////
     227    /**
     228        @brief Represents a section in a config file.
     229
     230        A section has a name and a list of config values.
     231    */
    177232    class _CoreExport ConfigFileSection
    178233    {
     
    181236
    182237        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            */
    183244            inline ConfigFileSection(const std::string& name, const std::string& additionalComment = "")
    184245                : name_(name)
     
    188249            ~ConfigFileSection();
    189250
     251            /// Returns the name of the section.
    190252            inline const std::string& getName() const
    191253                { return this->name_; }
    192254
     255            /// Changes the comment which is placed after the title of the section in the config file.
    193256            inline void setComment(const std::string& comment)
    194257                { this->additionalComment_ = comment; }
    195258
     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            */
    196266            inline void setValue(const std::string& name, const std::string& value, bool bString)
    197267                { 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            */
    198274            inline const std::string& getValue(const std::string& name, bool bString)
    199275            {
     
    201277                if (entry)
    202278                {
    203                     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
    204280                    return entry->getValue();
    205281                }
    206282                return BLANKSTRING;
    207283            }
     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            */
    208291            inline const std::string& getOrCreateValue(const std::string& name, const std::string& fallback, bool bString)
    209292                { return this->getOrCreateEntry(name, fallback, bString)->getValue(); }
    210293
     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            */
    211302            inline void setValue(const std::string& name, unsigned int index, const std::string& value, bool bString)
    212303                { 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            */
    213311            inline const std::string& getValue(const std::string& name, unsigned int index, bool bString)
    214312            {
     
    216314                if (entry)
    217315                {
    218                     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
    219317                    return entry->getValue();
    220318                }
    221319                return BLANKSTRING;
    222320            }
     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            */
    223329            inline const std::string& getOrCreateValue(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    224330                { return this->getOrCreateEntry(name, index, fallback, bString)->getValue(); }
     
    230336
    231337        private:
     338            /// Returns the list of entries in this section.
    232339            std::list<ConfigFileEntry*>& getEntries()
    233340                { return this->entries_; }
     341            /// Returns the begin-iterator of the list of entries in this section.
    234342            std::list<ConfigFileEntry*>::const_iterator getEntriesBegin() const
    235343                { return this->entries_.begin(); }
     344            /// Returns the end-iterator of the list of entries in this section.
    236345            std::list<ConfigFileEntry*>::const_iterator getEntriesEnd() const
    237346                { return this->entries_.end(); }
     
    241350
    242351            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            */
    243359            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, const std::string& fallback, bool bString)
    244360                { return (*this->getOrCreateEntryIterator(name, fallback, bString)); }
     361
    245362            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            */
    246371            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    247372                { return (*this->getOrCreateEntryIterator(name, index, fallback, bString)); }
    248373
    249             std::string name_;
    250             std::string additionalComment_;
    251             std::list<ConfigFileEntry*> entries_;
    252             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
    253378    };
    254379
     
    257382    // ConfigFile //
    258383    ////////////////
     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    */
    259389    class _CoreExport ConfigFile
    260390    {
     
    268398            virtual void clear();
    269399
     400            /// Returns the file-name of this config file
    270401            inline const std::string& getFilename()
    271402                { return this->filename_; }
    272403
     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            */
    273412            inline void setValue(const std::string& section, const std::string& name, const std::string& value, bool bString)
    274413            {
     
    276415                this->save();
    277416            }
     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            */
    278424            inline const std::string& getValue(const std::string& section, const std::string& name, bool bString)
    279425            {
     
    281427                return (sectionPtr ? sectionPtr->getValue(name, bString) : BLANKSTRING);
    282428            }
    283             const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString);
    284 
     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            */
    285453            inline void setValue(const std::string& section, const std::string& name, unsigned int index, const std::string& value, bool bString)
    286454            {
     
    288456                this->save();
    289457            }
     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            */
    290466            inline const std::string& getValue(const std::string& section, const std::string& name, unsigned int index, bool bString)
    291467            {
     
    293469                return (sectionPtr ? sectionPtr->getValue(name, index, bString) : BLANKSTRING);
    294470            }
    295             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            }
    296486
    297487            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            */
    298493            inline unsigned int getVectorSize(const std::string& section, const std::string& name) const
    299494            {
     
    302497            }
    303498
    304             static const char* DEFAULT_CONFIG_FOLDER;
     499            static const char* DEFAULT_CONFIG_FOLDER;   ///< The folder where the default config files will be stored
    305500
    306501        protected:
     
    308503            ConfigFileSection* getOrCreateSection(const std::string& section);
    309504
    310             std::list<ConfigFileSection*> sections_;
     505            std::list<ConfigFileSection*> sections_;    ///< A list of sections in this config file
    311506
    312507        private:
    313508            void saveIfUpdated();
    314             const std::string filename_;
    315             const bool bCopyFallbackFile_;
    316             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
    317513    };
    318514
     
    321517    // SettingsConfigFile //
    322518    ////////////////////////
     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    */
    323528    class _CoreExport SettingsConfigFile // tolua_export
    324529        : public ConfigFile, public Singleton<SettingsConfigFile>
     
    343548            void removeConfigValueContainer(ConfigValueContainer* container);
    344549
     550            /// Returns a set containing the names of all sections in this config file.
    345551            inline const std::set<std::string>& getSectionNames()
    346552                { return this->sectionNames_; }
     553            /// Returns the lower-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    347554            inline ContainerMap::const_iterator getContainerLowerBound(const std::string section)
    348555                { return this->containers_.lower_bound(section); }
     556            /// Returns the upper-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    349557            inline ContainerMap::const_iterator getContainerUpperBound(const std::string section)
    350558                { return this->containers_.upper_bound(section); }
     
    356564            bool configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&));
    357565
    358             ContainerMap containers_;
    359             std::set<std::string> sectionNames_;
    360             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
    361569    }; // tolua_export
    362570
     
    365573    // ConfigFileManager //
    366574    ///////////////////////
     575    /**
     576        @brief Manages the different config files (settings, calibration, etc). Implemented as Singleton.
     577    */
    367578    class _CoreExport ConfigFileManager : public Singleton<ConfigFileManager>
    368579    {
     
    374585            void setFilename(ConfigFileType::Value type, const std::string& filename);
    375586
     587            /// Returns the config file of a given type (settings, calibration, etc.)
    376588            inline ConfigFile* getConfigFile(ConfigFileType::Value type)
    377589            {
     
    381593
    382594        private:
    383             ConfigFileManager(const ConfigFileManager&);
    384 
    385             boost::array<ConfigFile*, 3> configFiles_;
    386             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
    387599    };
    388600} // tolua_export
  • code/branches/doc/src/libraries/core/OrxonoxClass.cc

    r6417 r7373  
    4141namespace orxonox
    4242{
    43     /** @brief Constructor: Sets the default values. */
     43    /**
     44        @brief Constructor: Sets the default values.
     45    */
    4446    OrxonoxClass::OrxonoxClass()
    4547    {
     
    5355    }
    5456
    55     /** @brief Destructor: Deletes, if existing, the list of the parents. */
     57    /**
     58        @brief Destructor: Removes the object from the object-lists, notifies all @ref WeakPtr "weak pointers" that this object is being deleted.
     59    */
    5660    OrxonoxClass::~OrxonoxClass()
    5761    {
     
    7276    }
    7377
    74     /** @brief Deletes the object if no smart pointers point to this object. Otherwise schedules the object to be deleted as soon as possible. */
     78    /**
     79        @brief Deletes the object if no @ref orxonox::SmartPtr "smart pointers" point to this object. Otherwise schedules the object to be deleted as soon as possible.
     80    */
    7581    void OrxonoxClass::destroy()
    7682    {
     
    8591    }
    8692
     93    /**
     94        @brief Removes this object from the object-lists.
     95    */
    8796    void OrxonoxClass::unregisterObject()
    8897    {
     
    92101    }
    93102
    94     /** @brief Returns true if the objects class is of the given type or a derivative. */
     103    /// Returns true if the object's class is of the given type or a derivative.
    95104    bool OrxonoxClass::isA(const Identifier* identifier)
    96105        { return this->getIdentifier()->isA(identifier); }
    97     /** @brief Returns true if the objects class is exactly of the given type. */
     106    /// Returns true if the object's class is exactly of the given type.
    98107    bool OrxonoxClass::isExactlyA(const Identifier* identifier)
    99108        { return this->getIdentifier()->isExactlyA(identifier); }
    100     /** @brief Returns true if the objects class is a child of the given type. */
     109    /// Returns true if the object's class is a child of the given type.
    101110    bool OrxonoxClass::isChildOf(const Identifier* identifier)
    102111        { return this->getIdentifier()->isChildOf(identifier); }
    103     /** @brief Returns true if the objects class is a direct child of the given type. */
     112    /// Returns true if the object's class is a direct child of the given type.
    104113    bool OrxonoxClass::isDirectChildOf(const Identifier* identifier)
    105114        { return this->getIdentifier()->isDirectChildOf(identifier); }
    106     /** @brief Returns true if the objects class is a parent of the given type. */
     115    /// Returns true if the object's class is a parent of the given type.
    107116    bool OrxonoxClass::isParentOf(const Identifier* identifier)
    108117        { return this->getIdentifier()->isParentOf(identifier); }
    109     /** @brief Returns true if the objects class is a direct parent of the given type. */
     118    /// Returns true if the object's class is a direct parent of the given type.
    110119    bool OrxonoxClass::isDirectParentOf(const Identifier* identifier)
    111120        { return this->getIdentifier()->isDirectParentOf(identifier); }
    112121
    113122
    114     /** @brief Returns true if the objects class is of the given type or a derivative. */
     123    /// Returns true if the object's class is of the given type or a derivative.
    115124    bool OrxonoxClass::isA(const OrxonoxClass* object)
    116125        { return this->getIdentifier()->isA(object->getIdentifier()); }
    117     /** @brief Returns true if the objects class is exactly of the given type. */
     126    /// Returns true if the object's class is exactly of the given type.
    118127    bool OrxonoxClass::isExactlyA(const OrxonoxClass* object)
    119128        { return this->getIdentifier()->isExactlyA(object->getIdentifier()); }
    120     /** @brief Returns true if the objects class is a child of the given type. */
     129    /// Returns true if the object's class is a child of the given type.
    121130    bool OrxonoxClass::isChildOf(const OrxonoxClass* object)
    122131        { return this->getIdentifier()->isChildOf(object->getIdentifier()); }
    123     /** @brief Returns true if the objects class is a direct child of the given type. */
     132    /// Returns true if the object's class is a direct child of the given type.
    124133    bool OrxonoxClass::isDirectChildOf(const OrxonoxClass* object)
    125134        { return this->getIdentifier()->isDirectChildOf(object->getIdentifier()); }
    126     /** @brief Returns true if the objects class is a parent of the given type. */
     135    /// Returns true if the object's class is a parent of the given type.
    127136    bool OrxonoxClass::isParentOf(const OrxonoxClass* object)
    128137        { return this->getIdentifier()->isParentOf(object->getIdentifier()); }
    129     /** @brief Returns true if the objects class is a direct child of the given type. */
     138    /// Returns true if the object's class is a direct child of the given type.
    130139    bool OrxonoxClass::isDirectParentOf(const OrxonoxClass* object)
    131140        { return this->getIdentifier()->isDirectParentOf(object->getIdentifier()); }
  • code/branches/doc/src/libraries/core/OrxonoxClass.h

    r7372 r7373  
    6363
    6464        The BaseObject and Interfaces are derived with @c virtual @c public @c OrxonoxClass from OrxonoxClass.
    65         OrxonoxClass is needed to create the class-hierarchy at startup and to store the Identifier and the MetaObjectList.
     65        OrxonoxClass is needed to create the class-hierarchy at startup and to store the Identifier and the
     66        MetaObjectList, as well as to provide an interface for SmartPtr and WeakPtr.
    6667    */
    6768    class _CoreExport OrxonoxClass
     
    9697            bool isDirectParentOf(const Identifier* identifier);
    9798
     99            /// Returns true if the object's class is of the given type or a derivative.
    98100            template <class B> inline bool isA(const SubclassIdentifier<B>* identifier)
    99101                { return this->isA(*identifier); }
     102            /// Returns true if the object's class is exactly of the given type.
    100103            template <class B> inline bool isExactlyA(const SubclassIdentifier<B>* identifier)
    101104                { return this->isExactlyA(*identifier); }
     105            /// Returns true if the object's class is a child of the given type.
    102106            template <class B> inline bool isChildOf(const SubclassIdentifier<B>* identifier)
    103107                { return this->isChildOf(*identifier); }
     108            /// Returns true if the object's class is a direct child of the given type.
    104109            template <class B> inline bool isDirectChildOf(const SubclassIdentifier<B>* identifier)
    105110                { return this->isDirectChildOf(*identifier); }
     111            /// Returns true if the object's class is a parent of the given type.
    106112            template <class B> inline bool isParentOf(const SubclassIdentifier<B>* identifier)
    107113                { return this->isParentOf(*identifier); }
     114            /// Returns true if the object's class is a direct parent of the given type.
    108115            template <class B> inline bool isDirectParentOf(const SubclassIdentifier<B>* identifier)
    109116                { return this->isDirectParentOf(*identifier); }
     
    118125            virtual void clone(OrxonoxClass*& item) {}
    119126
     127            /// Returns the number of @ref orxonox::SmartPtr "smart pointers" that point to this object.
    120128            inline unsigned int getReferenceCount() const
    121129                { return this->referenceCount_; }
     
    146154
    147155        protected:
     156            /// This virtual function is called if destroy() is called and no SmartPtr points to this object. Used in some cases to create a new SmartPtr to prevent destruction.
    148157            virtual void preDestroy() {}
    149158
     
    169178                { this->weakPointers_.erase(reinterpret_cast<WeakPtr<OrxonoxClass>*>(pointer)); }
    170179
    171             Identifier* identifier_;                   //!< The Identifier of the object
    172             std::set<const Identifier*>* parents_;     //!< List of all parents of the object
    173             MetaObjectList* metaList_;                 //!< MetaObjectList, containing all ObjectLists and ObjectListElements the object is registered in
    174             int referenceCount_;                       //!< Counts the references from smart pointers to this object
    175             bool requestedDestruction_;                //!< Becomes true after someone called delete on this object
    176             std::set<WeakPtr<OrxonoxClass>*> weakPointers_; //!< All weak pointers which point to this object (and like to get notified if it dies)
     180            Identifier* identifier_;                            //!< The Identifier of the object
     181            std::set<const Identifier*>* parents_;              //!< List of all parents of the object
     182            MetaObjectList* metaList_;                          //!< MetaObjectList, containing all ObjectLists and ObjectListElements the object is registered in
     183            int referenceCount_;                                //!< Counts the references from smart pointers to this object
     184            bool requestedDestruction_;                         //!< Becomes true after someone called delete on this object
     185            std::set<WeakPtr<OrxonoxClass>*> weakPointers_;     //!< All weak pointers which point to this object (and like to get notified if it dies)
    177186
    178187            /// 'Fast map' that holds this-pointers of all derived types
  • code/branches/doc/src/libraries/core/SmartPtr.h

    r7363 r7373  
    3737    @file
    3838    @ingroup Object SmartPtr
     39    @brief Definition of SmartPtr<T>.
     40
     41    @anchor SmartPtrExample
     42
     43    orxonox::SmartPtr is an implementation of a smart pointer - it wraps a pointer to an
     44    object  and keeps this object alive until no SmartPtr points to this object anymore.
     45    In contrast to orxonox::SharedPtr, SmartPtr works only with classes that are derived
     46    from orxonox::OrxonoxClass, because it's an intrusive implementation, meaning the
     47    reference counter is stored in the object itself.
     48
     49    It's possible to use normal pointers and smart pointers to an object simultaneously.
     50    You don't have to use SmartPtr all the time, you can create a SmartPtr for an object
     51    at any time and also convert it back to a normal pointer if you like. This is possible
     52    because the reference counter is stored in the object itself and not in SmartPtr (in
     53    contrast to SharedPtr).
     54
     55    @b Important: If you want to delete an object, you must not use @c delete @c object but
     56    rather @c object->destroy(). This function will check if there are smart pointers
     57    pointing to the object. If yes, the object will be kept alive until all smart pointes
     58    are destroyed. If no, the object is deleted instantly.
     59
     60    If all smart pointers that point to an object are destroyed, but you never called
     61    @c object->destroy() before, the object will not be deleted! All a SmartPtr will do
     62    is to really just keep an object alive, but it will not delete it automatically
     63    unless you tried to destroy it before.
     64
     65    Example:
     66    @code
     67    class MyClass                                           // class declaration
     68    {
     69        public:
     70            void setObject(OtherClass* object)              // passes a normal pointer which will be stored in a SmartPtr
     71                { this->object_ = object; }
     72
     73            OtherClass* getObject() const                   // converts the SmartPtr to a normal pointer and returns it
     74                { return this->object_; }
     75
     76        private:
     77            SmartPtr<OtherClass> object_;                   // a pointer to an instance of OtherClass is stored in a SmartPtr
     78    };
     79    @endcode
     80    In this example we assume that OtherClass is a child of OrxonoxClass. We don't care
     81    about the inheritance of MyClass though.
     82
     83    Now we create an instance of MyClass and assign a pointer to an instance of OtherClass:
     84    @code
     85    MyClass* myclass = new MyClass();                       // create an instance of MyClass
     86    OtherClass* object = new OtherClass();                  // create an instance of OtherClass
     87    myclass->setObject(object);                             // the object is now stored in a SmartPtr inside myclass
     88
     89    object->destroy();                                      // we try to destroy object, but there's still a SmartPtr pointing at it.
     90
     91    # object still exists at this point (because a SmartPtr points at it)
     92
     93    delete myclass;                                         // now we delete myclass, which also destroys the SmartPtr
     94
     95    # object doesn't exist anymore (because the SmartPtr is now destroyed)
     96    @endcode
     97
     98    Now we look at the same example, but we first delete myclass, then destroy object:
     99    @code
     100    MyClass* myclass = new MyClass();                       // create an instance of MyClass
     101    OtherClass* object = new OtherClass();                  // create an instance of OtherClass
     102    myclass->setObject(object);                             // the object is now stored in a SmartPtr inside myclass
     103
     104    delete myclass;                                         // we delete myclass, which also destroys the SmartPtr
     105
     106    # object still exists at this point (because destroy() was not called yet)
     107
     108    object->destroy();                                      // now we try to destroy object, which works instantly
     109
     110    # object doesn't exist anymore (because we just destroyed it)
     111    @endcode
     112
     113    Note that in any case @c object->destroy() has to be called to delete the object.
     114    However if a SmartPtr points at it, the destruction is delayed until all SmartPtr
     115    are destroyed.
    39116*/
    40117
     
    52129namespace orxonox
    53130{
     131    /**
     132        @brief A smart pointer which wraps a pointer to an object and keeps this object alive as long as the smart pointer exists.
     133
     134        @see See @ref SmartPtrExample "this description" for more information and an example.
     135    */
    54136    template <class T>
    55137    class SmartPtr
    56138    {
    57139        public:
     140            /// Constructor: Initializes the smart pointer with a null pointer.
    58141            inline SmartPtr() : pointer_(0), base_(0)
    59142            {
    60143            }
    61144
     145            /// Constructor: Used to explicitly initialize the smart pointer with a null pointer
    62146            inline SmartPtr(int) : pointer_(0), base_(0)
    63147            {
    64148            }
    65149
     150            /// Constructor: Initializes the smart pointer with a pointer to an object. @param pointer The pointer @param bAddRef If true, the reference counter is increased. Don't set this to false unless you know exactly what you're doing! (for example to avoid circular references if the @c this pointer of the possessing object is stored)
    66151            inline SmartPtr(T* pointer, bool bAddRef = true) : pointer_(pointer), base_(pointer)
    67152            {
     
    70155            }
    71156
     157            /// Copy-constructor
    72158            inline SmartPtr(const SmartPtr& other) : pointer_(other.pointer_), base_(other.base_)
    73159            {
     
    76162            }
    77163
     164            /// Copy-constructor for smart pointers to objects of another class.
    78165            template <class O>
    79166            inline SmartPtr(const SmartPtr<O>& other) : pointer_(other.get()), base_(other.base_)
     
    83170            }
    84171
     172            /// Constructor: Initializes the smart pointer with the pointer that is stored in a WeakPtr.
    85173            template <class O>
    86174            inline SmartPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.getBase())
     
    90178            }
    91179
     180            /// Destructor: Decrements the reference counter.
    92181            inline ~SmartPtr()
    93182            {
     
    96185            }
    97186
     187            /// Used to assign a null pointer.
    98188            inline SmartPtr& operator=(int)
    99189            {
     
    102192            }
    103193
     194            /// Assigns a new pointer.
    104195            inline SmartPtr& operator=(T* pointer)
    105196            {
     
    108199            }
    109200
     201            /// Assigns the wrapped pointer of another SmartPtr.
    110202            inline SmartPtr& operator=(const SmartPtr& other)
    111203            {
     
    114206            }
    115207
     208            /// Assigns the wrapped pointer of a SmartPtr of another class
    116209            template <class O>
    117210            inline SmartPtr& operator=(const SmartPtr<O>& other)
     
    121214            }
    122215
     216            /// Assigns the wrapped pointer of a WeakPtr.
    123217            template <class O>
    124218            inline SmartPtr& operator=(const WeakPtr<O>& other)
     
    128222            }
    129223
     224            /// Returns the wrapped pointer as @c T*
    130225            inline T* get() const
    131226            {
     
    133228            }
    134229
     230            /// Returns the wrapped pointer as @c OrxonoxClass*
    135231            inline OrxonoxClass* getBase() const
    136232            {
     
    138234            }
    139235
     236            /// Implicitly converts the SmartPtr to a pointer of type @c T*
    140237            inline operator T*() const
    141238            {
     
    143240            }
    144241
     242            /// Overloaded operator, returns a pointer to the stored object.
    145243            inline T* operator->() const
    146244            {
     
    149247            }
    150248
     249            /// Overloaded operator, returns a reference to the stored object.
    151250            inline T& operator*() const
    152251            {
     
    155254            }
    156255
     256            /// Returns true if the wrapped pointer is NULL.
    157257            inline bool operator!() const
    158258            {
     
    160260            }
    161261
     262            /// Swaps the contents of two smart pointers.
    162263            inline void swap(SmartPtr& other)
    163264            {
     
    174275            }
    175276
     277            /// Resets the smart pointer (equivalent to assigning a NULL pointer).
    176278            inline void reset()
    177279            {
     
    180282
    181283        private:
    182             T* pointer_;
    183             OrxonoxClass* base_;
     284            T* pointer_;            ///< The wrapped pointer to an object of type @a T
     285            OrxonoxClass* base_;    ///< The wrapped pointer, casted up to OrxonoxClass (this is needed because with just a T* pointer, SmartPtr couln't be used with forward declarations)
    184286    };
    185287
     288    /// Swaps the contents of two smart pointers.
    186289    template <class T>
    187290    void swap(SmartPtr<T>& a, SmartPtr<T>& b)
     
    190293    }
    191294
     295    /// Uses a static_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>.
    192296    template <class T, class U>
    193297    SmartPtr<T> static_pointer_cast(const SmartPtr<U>& p)
     
    196300    }
    197301
     302    /// Uses a const_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>.
    198303    template <class T, class U>
    199304    SmartPtr<T> const_pointer_cast(const SmartPtr<U>& p)
     
    202307    }
    203308
     309    /// Uses a dynamic_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>.
    204310    template <class T, class U>
    205311    SmartPtr<T> dynamic_pointer_cast(const SmartPtr<U>& p)
  • code/branches/doc/src/libraries/core/WeakPtr.h

    r7363 r7373  
    3232    @file
    3333    @ingroup Object SmartPtr
     34    @brief Definition of WeakPtr<T>.
     35
     36    @anchor WeakPtrExample
     37
     38    A WeakPtr wraps a pointer to an object. If the object gets deleted, the WeakPtr becomes
     39    NULL. This can be used to store pointers to objects without knowing when they will be
     40    destroyed.
     41
     42    WeakPtr works only with objects that are derived from orxonox::OrxonoxClass, because
     43    WeakPtr is intrusive and registers itself in the stored object, to get a notification if
     44    the object is being deleted.
     45
     46    Example:
     47    @code
     48    MyClass* object = new MyClass();                    // create an instance of MyClass
     49
     50    WeakPtr<MyClass> pointer = object;                  // create a WeakPtr and assign the object
     51
     52    if (pointer)                                        // checks if pointer is not NULL (which is true)
     53        pointer->someFunction();                        // calls MyClass::someFunction()
     54
     55    object->destroy();                                  // calls destroy() which deletes the object
     56
     57    if (pointer)                                        // checks if pointer is not NULL (which is now false)
     58        pointer->someFunction();                        // this will not be executed
     59    @endcode
     60    In this example we assumed that MyClass is derived of OrxonoxClass (otherwise it couldn't
     61    be used with a WeakPtr).
     62
     63    A callback can be registerd with the WeakPtr that will be called if the object gets deleted.
     64    @code
     65    void myCallback()                                   // definition of the callback function
     66    {
     67        COUT(0) << "Object destroyed" << std::endl;
     68    }
     69
     70    MyClass* object = new MyClass();                    // create an instance of MyClass
     71
     72    WeakPtr<MyClass> pointer = object;                  // create a WeakPtr and assign the object
     73
     74    pointer.setCallback(createFunctor(&myCallback));    // defines a callback
     75
     76    object->destroy();                                  // calls destroy() which deletes the object. prints "Object destroyed" to the console
     77    @endcode
    3478*/
    3579
     
    4690namespace orxonox
    4791{
     92    /**
     93        @brief WeakPtr wraps a pointer to an object, which becomes NULL if the object is deleted.
     94
     95        @see See @ref WeakPtrExample "this description" for more information and an example.
     96    */
    4897    template <class T>
    4998    class WeakPtr
     
    52101
    53102        public:
     103            /// Constructor: Initializes the weak pointer with a null pointer.
    54104            inline WeakPtr() : pointer_(0), base_(0), callback_(0)
    55105            {
    56106            }
    57107
     108            /// Constructor: Used to explicitly initialize the weak pointer with a null pointer
    58109            inline WeakPtr(int) : pointer_(0), base_(0), callback_(0)
    59110            {
    60111            }
    61112
     113            /// Constructor: Initializes the weak pointer with a pointer to an object.
    62114            inline WeakPtr(T* pointer) : pointer_(pointer), base_(pointer), callback_(0)
    63115            {
     
    66118            }
    67119
     120            /// Copy-constructor
    68121            inline WeakPtr(const WeakPtr& other) : pointer_(other.pointer_), base_(other.base_), callback_(0)
    69122            {
     
    72125            }
    73126
     127            /// Copy-constructor for weak pointers to objects of another class.
    74128            template <class O>
    75129            inline WeakPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.base_), callback_(0)
     
    79133            }
    80134
     135            /// Destructor
    81136            inline ~WeakPtr()
    82137            {
     
    86141            }
    87142
     143            /// Used to assign a null pointer.
    88144            inline WeakPtr& operator=(int)
    89145            {
     
    92148            }
    93149
     150            /// Assigns a new pointer.
    94151            inline WeakPtr& operator=(T* pointer)
    95152            {
     
    98155            }
    99156
     157            /// Assigns the wrapped pointer of another WeakPtr.
    100158            inline WeakPtr& operator=(const WeakPtr& other)
    101159            {
     
    104162            }
    105163
     164            /// Assigns the wrapped pointer of a WeakPtr of another class
    106165            template <class O>
    107166            inline WeakPtr& operator=(const WeakPtr<O>& other)
     
    111170            }
    112171
     172            /// Returns the wrapped pointer as @c T*
    113173            inline T* get() const
    114174            {
     
    116176            }
    117177
     178            /// Returns the wrapped pointer as @c OrxonoxClass*
    118179            inline OrxonoxClass* getBase() const
    119180            {
     
    121182            }
    122183
     184            /// Implicitly converts the WeakPtr to a pointer of type @c T*
    123185            inline operator T*() const
    124186            {
     
    126188            }
    127189
     190            /// Overloaded operator, returns a pointer to the stored object.
    128191            inline T* operator->() const
    129192            {
     
    132195            }
    133196
     197            /// Overloaded operator, returns a reference to the stored object.
    134198            inline T& operator*() const
    135199            {
     
    138202            }
    139203
     204            /// Returns true if the wrapped pointer is NULL.
    140205            inline bool operator!() const
    141206            {
     
    143208            }
    144209
     210            /// Swaps the contents of two weak pointers.
    145211            inline void swap(WeakPtr& other)
    146212            {
     
    167233            }
    168234
     235            /// Resets the weak pointer (equivalent to assigning a NULL pointer).
    169236            inline void reset()
    170237            {
     
    172239            }
    173240
     241            /// Registers a callback that will be executed if the stored object is destroyed.
    174242            inline void setCallback(const FunctorPtr& callback)
    175243            {
     
    177245            }
    178246
     247            /// Returns the registered callback.
    179248            inline const FunctorPtr& getCallback() const
    180249            {
     
    183252
    184253        private:
     254            /// Will be called by OrxonoxClass::~OrxonoxClass() if the stored object is deleted. Resets the wrapped pointer and executes the callback.
    185255            inline void objectDeleted()
    186256            {
     
    191261            }
    192262
    193             T* pointer_;
    194             OrxonoxClass* base_;
    195             FunctorPtr callback_;
     263            T* pointer_;            ///< The wrapped pointer to an object of type @a T
     264            OrxonoxClass* base_;    ///< The wrapped pointer, casted up to OrxonoxClass (this is needed because with just a T* pointer, WeakPtr couln't be used with forward declarations)
     265            FunctorPtr callback_;   ///< This callback will be executed if the stored object is deleted
    196266    };
    197267
     268    /// Swaps the contents of two weak pointers.
    198269    template <class T>
    199270    void swap(WeakPtr<T>& a, WeakPtr<T>& b)
     
    202273    }
    203274
     275    /// Uses a static_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new WeakPtr<T>.
    204276    template <class T, class U>
    205277    WeakPtr<T> static_pointer_cast(const WeakPtr<U>& p)
     
    208280    }
    209281
     282    /// Uses a const_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new WeakPtr<T>.
    210283    template <class T, class U>
    211284    WeakPtr<T> const_pointer_cast(const WeakPtr<U>& p)
     
    214287    }
    215288
     289    /// Uses a dynamic_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new WeakPtr<T>.
    216290    template <class T, class U>
    217291    WeakPtr<T> dynamic_pointer_cast(const WeakPtr<U>& p)
Note: See TracChangeset for help on using the changeset viewer.