Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/trunk/src/libraries/core/Language.h @ 11071

Last change on this file since 11071 was 11071, checked in by landauf, 8 years ago

merged branch cpp11_v3 back to trunk

  • Property svn:eol-style set to native
File size: 6.9 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Fabian 'x3n' Landau
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @defgroup Language Language
31    @ingroup Core
32*/
33
34/**
35    @file
36    @ingroup Language
37    @brief Declaration of the Language and the LanguageEntry class, as well as some helper functions.
38
39    @anchor LanguageExample
40
41    The Language class is used, to get a localisation of a string in the configured language.
42    The string is identified by another string, the label of the entry.
43    If the translation in the configured language isn't available, the default entry, defined in the code, is used.
44
45    Usage:
46     - Set the entry with the default string:
47       @code
48       Language::getInstance()->addEntry("label of the entry", "the string to translate");
49       @endcode
50
51     - Get the localisation of the entry in the configured language:
52       @code
53       orxout() << Language::getInstance()->getLocalisation("name of the entry") << endl;
54       @endcode
55
56    Example:
57    @code
58    int age = 20;
59    AddLanguageEntry("user_age", "Age");
60    orxout() << GetLocalisation("user_age") << ": " << age << endl;
61    @endcode
62
63    Resulting output:
64    @code
65    Age: 20
66    @endcode
67
68    The language entry is now defined in @a translation_default.lang:
69    @code
70    user_age=Age
71    @endcode
72
73    We can add a translation for another language, for example @a translation_german.lang:
74    @code
75    user_age=Alter
76    @endcode
77
78    Now change the language in @a orxonox.ini to "german":
79    @code
80    language_ = "german"
81    @endcode
82
83    Now you will see the translated language entry in the resulting output of the above code:
84    @code
85    Alter: 20
86    @endcode
87*/
88
89#ifndef _Language_H__
90#define _Language_H__
91
92#include "CorePrereqs.h"
93
94#include <map>
95#include <string>
96#include <cassert>
97#include "util/Singleton.h"
98
99namespace orxonox
100{
101    // ###############################
102    // ###      LanguageEntry      ###
103    // ###############################
104    /**
105        @brief The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
106
107        This class belongs to the Language class.
108    */
109    class _CoreExport LanguageEntry
110    {
111        public:
112            explicit LanguageEntry(const std::string& fallbackEntry);
113            void setLocalisation(const std::string& localisation);
114            void setDefault(const std::string& fallbackEntry);
115
116            /**
117              @brief Returns the localised entry in the configured language.
118              @return The translated entry
119            */
120            inline const std::string& getLocalisation()
121                { return this->localisedEntry_; }
122
123            /**
124              @brief Returns the default entry.
125              @return The default entry
126            */
127            inline const std::string& getDefault()
128                { return this->fallbackEntry_; }
129
130            /**
131                @brief Sets the label of this entry.
132                @param label The label
133            */
134            inline void setLabel(const LanguageEntryLabel& label)
135                { this->label_ = label; }
136
137            /**
138                @brief Returns the label of this entry.
139                @return The label
140            */
141            inline const LanguageEntryLabel& getLabel() const
142                { return this->label_; }
143
144        private:
145            LanguageEntryLabel label_;              //!< The label of the entry
146            std::string fallbackEntry_;             //!< The default entry: Used, if no translation is available or no language configured
147            std::string localisedEntry_;            //!< The localised entry in the configured language
148            bool bLocalisationSet_;                 //!< True if the translation was set
149    };
150
151
152    // ###############################
153    // ###         Language        ###
154    // ###############################
155    /**
156        @brief The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
157
158        @see See @ref LanguageExample "Language.h" for some examples.
159    */
160    class _CoreExport Language : public Singleton<Language>
161    {
162        friend class Singleton<Language>;
163        friend class CoreConfig;
164
165        public:
166            Language();
167            ~Language();
168
169            void addEntry(const LanguageEntryLabel& label, const std::string& entry);
170            const std::string& getLocalisation(const LanguageEntryLabel& label, bool bError = true) const;
171
172        private:
173            // non-copyable:
174            Language(const Language&) = delete;
175            Language& operator=(const Language&) = delete;
176
177            void readDefaultLanguageFile();
178            bool readTranslatedLanguageFile(const std::string& language);
179            void writeDefaultLanguageFile() const;
180            static std::string getFilename(const std::string& language);
181            LanguageEntry* createEntry(const LanguageEntryLabel& label, const std::string& entry);
182
183            std::string defaultLanguage_;                           //!< The default language
184            std::string defaultLocalisation_;                       //!< The returned string, if an entry unavailable entry is requested
185            std::map<std::string, LanguageEntry*> languageEntries_; //!< A map to store all LanguageEntry objects and their labels
186
187            static Language* singletonPtr_s;
188    };
189
190    /// Shortcut function for Language::addEntry
191    inline void AddLanguageEntry(const LanguageEntryLabel& label, const std::string& fallbackString)
192    {
193        Language::getInstance().addEntry(label, fallbackString);
194    }
195
196    /// Shortcut function for Language::getLocalisation
197    inline const std::string& GetLocalisation(const LanguageEntryLabel& label)
198    {
199        return Language::getInstance().getLocalisation(label);
200    }
201
202    /// Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
203    inline const std::string& GetLocalisation_noerror(const LanguageEntryLabel& label)
204    {
205        return Language::getInstance().getLocalisation(label, false);
206    }
207}
208
209#endif /* _Language_H__ */
Note: See TracBrowser for help on using the repository browser.