version 2.8
gtrans.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gtrans/gtrans.h
10  *
11  * @addtogroup GTRANS
12  *
13  * @brief Module that allows changing the language of an application dynamically during run-time.
14  *
15  * @{
16  */
17 
18 #ifndef _TRANS_H
19 #define _TRANS_H
20 
21 #include "../../gfx.h"
22 
23 #if GFX_USE_GTRANS || defined(__DOXYGEN__)
24 
25 /**
26  * @struct transTable
27  * @brief A table containing translated strings.
28  */
29 typedef struct transTable {
30  unsigned numEntries; /**< The number of strings that this table contains */
31  const char** strings; /**< The translated strings */
32 } transTable;
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /**
39  * @brief A wrapper macro to make writing and reading translatable applications easier.
40  */
41 #define gt(str) gtransString(str)
42 
43 /**
44  * @brief Get the string of the current language specified by the string of the base language.
45  *
46  * @details This function will return the string of the current language that corresponds to
47  * the specified string in the base language.
48  * @details This function uses strcmp() internally to compare strings.
49  *
50  * @param[in] string The string to translate.
51  *
52  * @return The corresponding string of the current language or the string passed as a parameter if it doesn't exist.
53  */
54 const char* gtransString(const char* string);
55 
56 /**
57  * @brief Get the string at the specified index position of the current language.
58  *
59  * @details Getting translation strings is a lot faster using the index as an accessor rather
60  * than the string in the base language.
61  *
62  * @param[in] index The index of the string in the current language translation table.
63  *
64  * @return The string at the given index of the current language or 0 if it doesn't exist.
65  */
66 const char* gtransIndex(unsigned index);
67 
68 /**
69  * @brief Set the base language.
70  *
71  * @details A translatable application needs to have a base language. All translations will
72  * be relative to this base language.
73  *
74  * @param[in] translation The translation table
75  */
76 void gtransSetBaseLanguage(const transTable* const translation);
77 
78 /**
79  * @brief Set the current language.
80  *
81  * @details All translations will refer to the current language set by calling this function.
82  *
83  * @param[in] translation The translation table
84  */
85 void gtransSetLanguage(const transTable* const translation);
86 
87 #ifdef __cplusplus
88 }
89 #endif
90 
91 #endif /* GFX_USE_GTRANS */
92 
93 #endif /* _TRANS_H */
94 /** @} */
const char ** strings
Definition: gtrans.h:31
unsigned numEntries
Definition: gtrans.h:30
A table containing translated strings.
Definition: gtrans.h:29
void gtransSetBaseLanguage(const transTable *const translation)
Set the base language.
void gtransSetLanguage(const transTable *const translation)
Set the current language.
const char * gtransIndex(unsigned index)
Get the string at the specified index position of the current language.
const char * gtransString(const char *string)
Get the string of the current language specified by the string of the base language.