SparrowText is for easy maintaining different translations of texts used by your application.
| sparrowText | SparrowText is for easy maintaining different translations of texts used by your application. |
| Macros | |
| SP_TEXT_MAX_READABLE_LINE | You shouldn’t have more signs in a line than this value ;-) Nobody will EVER need more than 64k letters in one translation... |
| Types | |
| spTranslation | Contains a translation text and the language. |
| spText | Contains different Translation of the same text, which is identified by a caption. |
| spBundle | A bundle is a collection of texts. |
| Functions | |
| spCreateText | Creates a new text, which contains different translations of the same text. |
| spAddTranslation | Adds a translation to a text. |
| spCreateTextWithTranslation | Works like a mix of spCreateText and spAddTranslation. |
| spSearchCaption | Finds a specific spText in a bundle. |
| spGetTranslation | Gives you the translation a text in the default language or (if not avaible) in the first added language. |
| spGetTranslationFromCaption | Gives you the translation in the default language of a text. |
| spCreateTextBundle | Creates a text bundle. |
| spLoadBundle | Loads a bundle out of a text file. |
| spReadPossibleLanguages | Reads a “possible languages file”. |
| spGetPossibleLanguagesCount | Gets you the total number of all possible languages, if you read them with spReadPossibleLanguages. |
| spGetPossibleLanguage | Gives you the language code for a possible language identified by its number. |
| spGetPossibleLanguageName | Gives you the language name for a possible language identified by its number. |
| spChangeBundle | Texts can change their bundles. |
| spDeleteBundle | Deletes a whole bundle. |
| spSetDefaultLanguage | Sets the default language of sparrowText. |
| spDeleteText | Deletes a text. |
Contains different Translation of the same text, which is identified by a caption. The captions should be unique in bundles (See spBundle).
| caption (char*) | name of the text |
| firstTranslation (spTranslation*) | start of a linked list of possible translations |
| bundle (spBundle*) | bundle of the text |
| prev,next (spText*) | internal double linked list variables for the bundle. Do not change |
PREFIX spTextPointer spCreateText( const char * caption, spBundlePointer bundle )
Creates a new text, which contains different translations of the same text.
| caption | the name of this text |
| bundle | optional bundle to add this text to. If no bundle is given, the text will be added to the internal global bundle |
| spText* | pointer to the created spText struct |
PREFIX void spAddTranslation( spTextPointer text, Uint16 language, const char * translation )
Adds a translation to a text.
| text | pointer to a spText struct, to which the translation shall be added |
| language | Uint16 language number of the added translation |
| translation | the text of the translation |
PREFIX spTextPointer spCreateTextWithTranslation( const char * caption, spBundlePointer bundle, Uint16 language, const char * translation )
Works like a mix of spCreateText and spAddTranslation. It creates a text and adds a first translation to it.
| caption | the name of this text |
| bundle | optional bundle to add this text to. If no bundle is given, the text will be added to the internal global bundle |
| language | Uint16 language number of the added translation |
| translation | the text of the translation |
| spText* | pointer to the created spText struct |
PREFIX spTextPointer spSearchCaption( spBundlePointer bundle, char * caption )
Finds a specific spText in a bundle. Attention! This function is relative slow. If you have much text, try to mind the returned pointer.
| bundle | the bundle, in which the function shall search. If the text is in the internal global bundel, pass NULL |
| caption | the caption of the text to find |
| spText* | a pointer of the found spText or NULL if nothing was found |
PREFIX char* spGetTranslation( spTextPointer text )
Gives you the translation a text in the default language or (if not avaible) in the first added language. That is the reason, why it makes sense, to add Englisch first everytime!
| text | a pointer to a spText struct, from which you want the right translation |
| char* | the translation as null terminated string |
PREFIX char* spGetTranslationFromCaption( spBundlePointer bundle, char * caption )
Gives you the translation in the default language of a text.
| bundle | the bundle, in which shall be searched |
| caption | the caption of the text |
| char* | the translation as null terminated string. However, if the language is not found, but the caption, the first definied language is returned. If the caption is not found an error string is returned. |
PREFIX spBundlePointer spCreateTextBundle( void )
Creates a text bundle. Bundles are very practical for encapsuling texts of different kinds. However: If you don’t need them and always refer to bundle “NULL”, the undeletable internal main bundle of sparrowText is used.
| spBundle* | pointer to the created bundle |
PREFIX spBundlePointer spLoadBundle( const char * filename, int own_bundle )
Loads a bundle out of a text file. The files are like ini-files and the interpretation of one line depends on the beginning. There are 3 kinds of beginning a line:
# this is a comment. --:example text en This is an example text. de Das ist ein Beispieltext la lorem ipsum ;-)
| filename | file to read |
| own_bundle | Pass 1 to create an own bundle or 0 to add the loaded translations to the internal main bundle |
| spBundle* | pointer to the spBundle struct the translations are added in |
PREFIX void spReadPossibleLanguages( const char * filename )
Reads a “possible languages file”. In fact it is the same like the bundle files explained in spLoadBundle, but there is just one “text” defined and this text HAVE to be named “languages”. The following defined translations are the possible languages and their names. Example:
--:languages en:English de:Deutsch la:Latinus
| filename | file with possible languages to read |
spGetPossibleLanguage, spGetPossibleLanguageName, spGetPossibleLanguagesCount
PREFIX int spGetPossibleLanguagesCount( void )
Gets you the total number of all possible languages, if you read them with spReadPossibleLanguages.
| int | the number of possible languages |
spReadPossibleLanguages, spGetPossibleLanguage, spGetPossibleLanguageName
PREFIX Uint16 spGetPossibleLanguage( int nr )
Gives you the language code for a possible language identified by its number.
| nr | the number of the language |
| Uint16 | the language code |
spReadPossibleLanguages, spGetPossibleLanguagesCount, spGetPossibleLanguageName
PREFIX char* spGetPossibleLanguageName( int nr )
Gives you the language name for a possible language identified by its number.
| nr | the number of the language |
| char* | name of the language |
spReadPossibleLanguages, spGetPossibleLanguagesCount, spGetPossibleLanguage
PREFIX void spDeleteBundle( spBundlePointer bundle, int keepText )
Deletes a whole bundle.
| bundle | bundle to deleted |
| keepText | if 1, no text well be deleted and the bundle of the texts will be the internal main bundle (which will be searched, if you pass “NULL” as bunch parameter), else the texts are deleted, too. Obviously |
spDeleteBundle(NULL,1);
doesn’t make sense. But of course you can use it to clean the main bundle with
spDeleteBundle(NULL,0);
Creates a new text, which contains different translations of the same text.
PREFIX spTextPointer spCreateText( const char * caption, spBundlePointer bundle )
Adds a translation to a text.
PREFIX void spAddTranslation( spTextPointer text, Uint16 language, const char * translation )
Works like a mix of spCreateText and spAddTranslation.
PREFIX spTextPointer spCreateTextWithTranslation( const char * caption, spBundlePointer bundle, Uint16 language, const char * translation )
Finds a specific spText in a bundle.
PREFIX spTextPointer spSearchCaption( spBundlePointer bundle, char * caption )
Gives you the translation a text in the default language or (if not avaible) in the first added language.
PREFIX char* spGetTranslation( spTextPointer text )
Gives you the translation in the default language of a text.
PREFIX char* spGetTranslationFromCaption( spBundlePointer bundle, char * caption )
Creates a text bundle.
PREFIX spBundlePointer spCreateTextBundle( void )
Loads a bundle out of a text file.
PREFIX spBundlePointer spLoadBundle( const char * filename, int own_bundle )
Reads a “possible languages file”.
PREFIX void spReadPossibleLanguages( const char * filename )
Gets you the total number of all possible languages, if you read them with spReadPossibleLanguages.
PREFIX int spGetPossibleLanguagesCount( void )
Gives you the language code for a possible language identified by its number.
PREFIX Uint16 spGetPossibleLanguage( int nr )
Gives you the language name for a possible language identified by its number.
PREFIX char* spGetPossibleLanguageName( int nr )
Texts can change their bundles.
PREFIX void spChangeBundle( spTextPointer text, spBundlePointer bundle )
Deletes a whole bundle.
PREFIX void spDeleteBundle( spBundlePointer bundle, int keepText )
Sets the default language of sparrowText.
PREFIX void spSetDefaultLanguage( Uint16 language )
Deletes a text.
PREFIX void spDeleteText( spTextPointer text )