Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

documented and commented the Language.h and .cc file

Location:
code/branches/FICN/src/orxonox/core
Files:
2 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    {

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

    r715 r720  
    2626 */
    2727
     28/*!
     29    @file Language.h
     30    @brief Definition of the Language and the LanguageEntry class.
     31
     32    The Language class is used, to get a translation of a string in the configured language.
     33    The string is identified by another string, the name of the entry.
     34    If the translation in the configured language isn't available, the default entry, defined in the code, is used.
     35
     36    Usage:
     37     - Set the entry with the default string:
     38       Language::getLanguage()->addEntry("name of the entry", "the string to translate");
     39
     40     - Get the translation of the entry in the configured language:
     41       std::cout << Language::getLanguage()->getTranslation("name of the entry") << std::endl;
     42*/
     43
    2844#ifndef _Language_H__
    2945#define _Language_H__
    … …  
    3349
    3450#include "CorePrereqs.h"
    35 
    3651#include "OrxonoxClass.h"
    3752
    … …  
    4055    typedef std::string LanguageEntryName;
    4156
     57    //! The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
    4258    class _CoreExport LanguageEntry : public OrxonoxClass
    4359    {
    … …  
    4763            void setDefault(const std::string& fallbackEntry);
    4864
     65            /** @brief Returns the translated entry in the configured language. @return The translated entry */
    4966            inline const std::string& getTranslation()
    5067                { return this->translatedEntry_; }
    5168
     69            /** @brief Returns the default entry. @return The default entry */
    5270            inline const std::string& getDefault()
    5371                { return this->fallbackEntry_; }
    5472
    5573        private:
    56             std::string fallbackEntry_;
    57             std::string translatedEntry_;
     74            std::string fallbackEntry_;                             //!< The default entry: Used, if no translation is available or no language configured
     75            std::string translatedEntry_;                           //!< The translated entry in the configured language
    5876    };
    5977
     78    //! The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
    6079    class _CoreExport Language : public OrxonoxClass
    6180    {
    … …  
    7796            void createEntry(const LanguageEntryName& name, const std::string& entry);
    7897
    79             std::string language_;
    80             std::string defaultLanguage_;
    81             std::string defaultTranslation_;
    82             std::map<std::string, LanguageEntry*> languageEntries_;
     98            std::string language_;                                  //!< The configured language
     99            std::string defaultLanguage_;                           //!< The default language
     100            std::string defaultTranslation_;                        //!< The returned string, if an entry unavailable entry is requested
     101            std::map<std::string, LanguageEntry*> languageEntries_; //!< A map to store all LanguageEntry objects and their name
    83102    };
    84103}
Note: See TracChangeset for help on using the changeset viewer.