Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Dec 29, 2007, 2:37:45 AM (16 years ago)
Author:
landauf
Message:

documented and commented the Language.h and .cc file

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/FICN/src/orxonox/core/Language.cc

    r719 r720  
    2525 *
    2626 */
     27
     28/*!
     29    @file Language.cc
     30    @brief Implementation of the Language and the LanguageEntry class.
     31*/
    2732
    2833#include <fstream>
    … …  
    3641    // ###      LanguageEntry      ###
    3742    // ###############################
     43    /**
     44        @brief Constructor: Sets the default entry.
     45        @param fallbackEntry The default entry
     46    */
    3847    LanguageEntry::LanguageEntry(const std::string& fallbackEntry)
    3948    {
    … …  
    4150
    4251        this->fallbackEntry_ = fallbackEntry;
    43         this->translatedEntry_ = fallbackEntry;
    44     }
    45 
     52        this->translatedEntry_ = fallbackEntry; // Set the translation to the fallback entry, for the case that no translation gets assigned
     53    }
     54
     55    /**
     56        @brief Sets the translation of the entry.
     57        @param translation The translation
     58    */
    4659    void LanguageEntry::setTranslation(const std::string& translation)
    4760    {
     61        // Check if the translation is more than just an empty string
    4862        if (translation.compare("") != 0)
    4963            this->translatedEntry_ = translation;
    … …  
    5266    }
    5367
     68    /**
     69        @brief Sets the default entry.
     70        @param fallbackEntry The default entry
     71    */
    5472    void LanguageEntry::setDefault(const std::string& fallbackEntry)
    5573    {
     74        // If the default entry changes and the translation wasn't set yet, use the new default entry as translation
    5675        if (this->translatedEntry_.compare(this->fallbackEntry_) == 0)
    5776            this->translatedEntry_ = fallbackEntry;
    … …  
    6382    // ###        Language         ###
    6483    // ###############################
     84    /**
     85        @brief Constructor: Reads the default language file and sets some values.
     86    */
    6587    Language::Language()
    6688    {
    6789        RegisterRootObject(Language);
     90
    6891        this->defaultLanguage_ = "default";
    6992        this->defaultTranslation_ = "ERROR: LANGUAGE ENTRY DOESN'T EXIST!";
     93
     94        // Read the default language file to create all known LanguageEntry objects
    7095        this->readDefaultLanguageFile();
    7196    }
    7297
     98    /**
     99        @brief Function to collect the SetConfigValue-macro calls.
     100    */
    73101    void Language::setConfigValues()
    74102    {
    75103        SetConfigValue(language_, this->defaultLanguage_).description("The language of the ingame text");
     104
     105        // Read the translation file after the language was configured
    76106        this->readTranslatedLanguageFile();
    77107    }
    78108
     109    /**
     110        @brief Returns a reference to the only existing instance of the Language class and calls the setConfigValues() function.
     111        @return The reference to the only existing instance
     112    */
    79113    Language& Language::getLanguage()
    80114    {
     115        // Use static variables to avoid conflicts while executing this code before main()
    81116        static Language theOnlyLanguageObject = Language();
    82117        static bool bCreatingTheOnlyLanguageObject = true;
    83118
     119        // This workaround is used to set a description of the own config value without creating an infinite recursion
    84120        if (bCreatingTheOnlyLanguageObject)
    85121        {
    … …  
    91127    }
    92128
     129    /**
     130        @brief Creates a new LanguageEntry with a given name and a given default entry.
     131        @param name The name of the entry
     132        @param entry The default entry
     133    */
    93134    void Language::createEntry(const LanguageEntryName& name, const std::string& entry)
    94135    {
     136        // Make sure we don't create a duplicate entry
    95137        if (!this->languageEntries_[name])
    96138        {
    … …  
    105147    }
    106148
     149    /**
     150        @brief Adds a new LanguageEntry, if it's not already existing.
     151        @param name The name of the entry
     152        @param entry The default entry
     153    */
    107154    void Language::addEntry(const LanguageEntryName& name, const std::string& entry)
    108155    {
    109156        std::map<std::string, LanguageEntry*>::const_iterator it = this->languageEntries_.find(name);
    110157        if (!it->second)
     158        {
     159            // The entry isn't available yet, meaning it's new, so create it
    111160            this->createEntry(name, entry);
     161        }
    112162        else if (it->second->getDefault().compare(entry) == 0)
     163        {
     164            // The entry is available and the default string is the same, so return because everything is fine
    113165            return;
     166        }
    114167        else
     168        {
     169            // The defined default entry is not the same as in the default language file - change it to the new entry
    115170            it->second->setDefault(entry);
    116 
     171        }
     172
     173        // Write the default language file because either a new entry was created or an existing entry has changed
    117174        this->writeDefaultLanguageFile();
    118175    }
    119176
     177    /**
     178        @brief Returns the translation of a given entry.
     179        @param name The name of the entry
     180        @return The translation
     181    */
    120182    const std::string& Language::getTranslation(const LanguageEntryName& name) const
    121183    {
    … …  
    125187        else
    126188        {
     189            // Uh, oh, an undefined entry was requested: return the default string
    127190            COUT(2) << "Error: Language entry \"" << name << "\" not found!" << std::endl;
    128191            return this->defaultTranslation_;
    … …  
    130193    }
    131194
     195    /**
     196        @brief Creates the name of the language file out of the languages name.
     197        @param language The name of the language
     198        @return The filename
     199    */
    132200    const std::string Language::getFileName(const std::string& language)
    133201    {
    … …  
    135203    }
    136204
     205    /**
     206        @brief Reads the default language file and creates a LanguageEntry objects for every entry.
     207    */
    137208    void Language::readDefaultLanguageFile()
    138209    {
    … …  
    161232            file.getline(line, 1024);
    162233            std::string lineString = std::string(line);
     234
     235            // Check if the line is empty
    163236            if (lineString.compare("") != 0)
    164237            {
    165238                unsigned int pos = lineString.find('=');
    166                 if (pos < lineString.size() && lineString.size() >= 3)
     239
     240                // Check if the length is at least 3 and if there's an entry before and behind the =
     241                if (pos > 0 && pos < (lineString.size() - 1) && lineString.size() >= 3)
    167242                    this->createEntry(lineString.substr(0, pos), lineString.substr(pos + 1));
    168243                else
    … …  
    174249    }
    175250
     251    /**
     252        @brief Reads the language file of the configured language and assigns the translations to the corresponding LanguageEntry object.
     253    */
    176254    void Language::readTranslatedLanguageFile()
    177255    {
    … …  
    197275            file.getline(line, 1024);
    198276            std::string lineString = std::string(line);
     277
     278            // Check if the line is empty
    199279            if (lineString.compare("") != 0)
    200280            {
    201281                unsigned int pos = lineString.find('=');
    202                 if (pos < lineString.size() && lineString.size() >= 3)
     282
     283                // Check if the length is at least 3 and if there's an entry before and behind the =
     284                if (pos > 0 && pos < (lineString.size() - 1) && lineString.size() >= 3)
    203285                {
    204286                    std::map<std::string, LanguageEntry*>::const_iterator it = this->languageEntries_.find(lineString.substr(0, pos));
     287
     288                    // Check if the entry exists
    205289                    if (it->second)
    206290                        it->second->setTranslation(lineString.substr(pos + 1));
    … …  
    216300    }
    217301
     302    /**
     303        @brief Writes all default entries to the default language file.
     304    */
    218305    void Language::writeDefaultLanguageFile() const
    219306    {
Note: See TracChangeset for help on using the changeset viewer.