Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

Last change on this file since 9022 was 8858, checked in by landauf, 13 years ago

merged output branch back to trunk.

Changes:

  • you have to include util/Output.h instead of util/Debug.h
  • COUT(x) is now called orxout(level)
  • output levels are now defined by an enum instead of numbers. see util/Output.h for the definition
  • it's possible to use output contexts with orxout(level, context). see util/Output.h for some common contexts. you can define more contexts
  • you must use 'endl' at the end of an output message, '\n' does not flush the message

Output levels:

  • instead of COUT(0) use orxout()
  • instead of COUT(1) use orxout(user_error) or orxout(internal_error)
  • instead of COUT(2) use orxout(user_warning) or orxout(internal_warning)
  • instead of COUT(3) use orxout(user_status/user_info) or orxout(internal_status/internal_info)
  • instead of COUT(4) use orxout(verbose)
  • instead of COUT(5) use orxout(verbose_more)
  • instead of COUT(6) use orxout(verbose_ultra)

Guidelines:

  • user_* levels are for the user, visible in the console and the log-file
  • internal_* levels are for developers, visible in the log-file
  • verbose_* levels are for debugging, only visible if the context of the output is activated

Usage in C++:

  • orxout() << "message" << endl;
  • orxout(level) << "message" << endl;
  • orxout(level, context) << "message" << endl;

Usage in Lua:

  • orxout("message")
  • orxout(orxonox.level.levelname, "message")
  • orxout(orxonox.level.levelname, "context", "message")

Usage in Tcl (and in the in-game-console):

  • orxout levelname message
  • orxout_context levelname context message
  • shortcuts: log message, error message, warning message, status message, info message, debug message
  • Property svn:eol-style set to native
File size: 6.7 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 Core;
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            Language(const Language&);
174
175            void readDefaultLanguageFile();
176            void readTranslatedLanguageFile();
177            void writeDefaultLanguageFile() const;
178            static std::string getFilename(const std::string& language);
179            LanguageEntry* createEntry(const LanguageEntryLabel& label, const std::string& entry);
180
181            std::string defaultLanguage_;                           //!< The default language
182            std::string defaultLocalisation_;                       //!< The returned string, if an entry unavailable entry is requested
183            std::map<std::string, LanguageEntry*> languageEntries_; //!< A map to store all LanguageEntry objects and their labels
184
185            static Language* singletonPtr_s;
186    };
187
188    /// Shortcut function for Language::addEntry
189    inline void AddLanguageEntry(const LanguageEntryLabel& label, const std::string& fallbackString)
190    {
191        Language::getInstance().addEntry(label, fallbackString);
192    }
193
194    /// Shortcut function for Language::getLocalisation
195    inline const std::string& GetLocalisation(const LanguageEntryLabel& label)
196    {
197        return Language::getInstance().getLocalisation(label);
198    }
199
200    /// Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
201    inline const std::string& GetLocalisation_noerror(const LanguageEntryLabel& label)
202    {
203        return Language::getInstance().getLocalisation(label, false);
204    }
205}
206
207#endif /* _Language_H__ */
Note: See TracBrowser for help on using the repository browser.