Adding documentation to GTRANS

ugfx_release_2.6
Joel Bodenmann 2016-02-08 00:03:30 +01:00
parent 7b60003461
commit 39c13d1645
3 changed files with 60 additions and 7 deletions

View File

@ -68,7 +68,7 @@ int main(void)
gdispFillStringBox(20+300*i, 35*j, 300, 35, gtransIndex(j), font, Black, Silver, justifyLeft);
}
gdispFillStringBox(20, 300, 300, 25, gtransString("Welcome"), font, Black, Silver, justifyLeft);
gdispFillStringBox(20, 300, 300, 25, gt("Welcome"), font, Black, Silver, justifyLeft);
while (TRUE) {
gfxSleepMilliseconds(500);

View File

@ -25,23 +25,29 @@ void _gtransDeinit(void)
const char* gtransString(const char* string)
{
// Find the index of the specified string in the base language table
size_t i = 0;
while (1) {
// Prevent overflow
if (i >= _languageBase->numEntries-1) {
return 0;
return string;
}
// Check if we found the string
if (strcmp(string, _languageBase->strings[i]) == 0) {
break;
}
// Otherwise keep going
i++;
}
// Make sure that the index exists in the current language table
if (i >= _languageCurrent->numEntries-1) {
return 0;
return string;
}
// Return the translated string
return _languageCurrent->strings[i];
}

View File

@ -10,7 +10,7 @@
*
* @addtogroup GTRANS
*
* @brief Module to allow changing the language of an application dynamically during run-time.
* @brief Module that allows changing the language of an application dynamically during run-time.
*
* @{
*/
@ -22,18 +22,66 @@
#if GFX_USE_GTRANS || defined(__DOXYGEN__)
/**
* @struct transTable
* @brief A table containing translated strings.
*/
typedef struct transTable {
unsigned numEntries;
const char** strings;
unsigned numEntries; /**< The number of strings that this table contains */
const char** strings; /**< The translated strings */
} transTable;
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief A wrapper macro to make writing and reading translatable applications easier.
*/
#define gt(str) gtransString(str)
/**
* @brief Get the string of the current language specified by the string of the base language.
*
* @details This function will return the string of the current language that corresponds to
* the specified string in the base language.
* @details This function uses strcmp() internally to compare strings.
*
* @param[in] string The string to translate.
*
* @return The corresponding string of the current language or the string passed as a parameter if it doesn't exist.
*/
const char* gtransString(const char* string);
/**
* @brief Get the string at the specified index position of the current language.
*
* @details Getting translation strings is a lot faster using the index as an accessor rather
* than the string in the base language.
*
* @param[in] index The index of the string in the current language translation table.
*
* @return The string at the given index of the current language or 0 if it doesn't exist.
*/
const char* gtransIndex(unsigned index);
/**
* @brief Set the base language.
*
* @details A translatable application needs to have a base language. All translations will
* be relative to this base language.
*
* @param[in] translation The translation table
*/
void gtransSetBaseLanguage(const transTable* const translation);
/**
* @brief Set the current language.
*
* @details All translations will refer to the current language set by calling this function.
*
* @param[in] translation The translation table
*/
void gtransSetLanguage(const transTable* const translation);
#ifdef __cplusplus
@ -44,4 +92,3 @@ void gtransSetLanguage(const transTable* const translation);
#endif /* _TRANS_H */
/** @} */