µGFX  2.9
version 2.9
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.io/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 /**
35  * @brief A wrapper macro to make writing and reading translatable applications easier.
36  */
37 #define gt(str) gtransString(str)
38 
39 /**
40  * @brief Get the string of the current language specified by the string of the base language.
41  *
42  * @details This function will return the string of the current language that corresponds to
43  * the specified string in the base language.
44  * @details This function uses strcmp() internally to compare strings.
45  *
46  * @param[in] string The string to translate.
47  *
48  * @return The corresponding string of the current language or the string passed as a parameter if it doesn't exist.
49  */
50 const char* gtransString(const char* string);
51 
52 /**
53  * @brief Get the string at the specified index position of the current language.
54  *
55  * @details Getting translation strings is a lot faster using the index as an accessor rather
56  * than the string in the base language.
57  *
58  * @param[in] index The index of the string in the current language translation table.
59  *
60  * @return The string at the given index of the current language or 0 if it doesn't exist.
61  */
62 const char* gtransIndex(unsigned index);
63 
64 /**
65  * @brief Set the base language.
66  *
67  * @details A translatable application needs to have a base language. All translations will
68  * be relative to this base language.
69  *
70  * @param[in] translation The translation table
71  */
72 void gtransSetBaseLanguage(const transTable* const translation);
73 
74 /**
75  * @brief Set the current language.
76  *
77  * @details All translations will refer to the current language set by calling this function.
78  *
79  * @param[in] translation The translation table
80  */
81 void gtransSetLanguage(const transTable* const translation);
82 
83 #endif /* GFX_USE_GTRANS */
84 
85 #endif /* _TRANS_H */
86 /** @} */
const char * gtransString(const char *string)
Get the string of the current language specified by the string of 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.
void gtransSetBaseLanguage(const transTable *const translation)
Set the base language.
A table containing translated strings.
Definition: gtrans.h:29
unsigned numEntries
Definition: gtrans.h:30
const char ** strings
Definition: gtrans.h:31