Siegfried Locale Library Developer Guide

Function overview

SFLocale *GetInstance()

By using the function "GetInstance()" an application receives access to the text data of the loaded "locale" file. As opposed to other classes the creation of an "SFLocale" object isn't needed (and not possible). Access to the class will be done in every instance by a pointer returned from "GetInstance()". The class "SFLocale()" is a so called "Singleton design pattern". A Singleton design pattern create one (and only one) instance of a class. This behaviour saves memory and if a language change is done the text data remains consistent.

Example:

SFLocale *lang;

lang = SFLocale::GetInstance();     //  get access to text data

Now at every point within the application it's possible to access the text data. Only one instance of the class exists. The pointer to the instance can be a global variable. But that's not the fine art of programming, because the priciple of encapsulation is broken. It's better to declare the pointer as class private or for base classes as protected:

xyz {
    xyz();
    ~xyz;
    :
    :
private:
    SFLocale  *cLang;
};

xyz::xyz()
{
cLang = SFLocale::GetInstance();
    :
    :
}

int32 SetLanguage(BDirectory *folder, const char *language)
int32 SetLanguage(BEntry *folder, const char *language)
int32 SetLanguage(BPath *folder, const char *language)
int32 SetLanguage(const char *folder, const char *language)
int32 SetLanguage(entry_ref *folder, const char *language)

Loading the language text. As first parameter the path to the "locale" files of the application is used. The second parameter is the native name of the language that should be set. It isn't the name of the "locale" file! The name of the language is saved as the string attribute "sf:language" to the file. This will be checked by "SetLanguage()" to grant the independence of the filename.

if the "locale" file is not found, the library will use the built-in default text (English) automatically.

The following results can be returned by the function:

0 = Ok, new language loaded and set
1 = Error, can't read file
2 = Error, file isn't a "locale" file
3 = Error, wrong "locale" file (application ID incorrect)
4 = Error, file has no language name
5 = Error, invalid folder

Example:

BPath    path;
BEntry   entry;
app_info info;
      :
      :
be_app->GetAppInfo(&info);               // get program info
entry.SetTo(&info.ref);                  // get access to program
entry.GetPath(&path);                    // path + filename
path.GetParent(&path);                   // get application path
path.Append("locale");                   // append language folder
cLang->SetLanguage(&path, "Deutsch");    // load and set language "Deutsch"


void SetDefaultText(const char *deftext[], int32 count, const char *language)

Set default language data. As parameter the default text field, the count of text lines and the name of the default language (mostly english) is used. The text field and the language name are internally copied by the function.

"SetDefaultText()" is normally called once at the application start up.

static const char	*mText[SF_LAST_ID] = 
{
"Ok",                                          //SFOK
"Cancel",                                      //SFCANCEL
"Continue",                                    //SFCONTINUE
      :
      :
"ERROR: There is no text to save!",            //SFERRNOTEXT
"Font",                                        //SFFONT
"Size",                                        //SFSIZE
};

The default text should be collected in a single Include file.

Example:

SuperApp::SuperApp()		
    : BApplication("application/x-vnd.siegfriedsoft-superapp")
{
SFLocale  *lang;

lang = SFLocale::GetInstance();     // get access for language data
lang->SetAppID(SF_TEXT_APP_ID);     // set applicaation ID
// --- set build-in text ---
lang->SetDefaultText(mText, SF_LAST_ID, SF_DEFAULT_LANGUAGE);
      :
      :


void SetAppID(const char *app_id)

Setting of the application ID to identfy "locale" files correctly. The string is used to identify the "locale" file that will be loaded by "SetLanguage()". It's the same ID string used at the Siegfried Locale Editor for the "locale" files. Only those "locale" files will be loaded that have the exact same string. The ID string will be copied internaly by the function.

Like "SetDefaultText()" the function is to be called once at application start-up.

Example: see example of "SetDefaultText()" above.


const char *AppID()

Returns the application ID set by "SetAppID()".


const char *Language()

Returns a pointer to the language name currently used. The name is always written in the native language. For the language german the string "Deutsch" is returned, or for french "Francais" is returned. The name of the language is set during the function call of "SetLanguage()".


const char *Text(int32 id)

The main function of the sfliblocale library. By a given ID number the function returns a text string of the language that was set by "SetLanguage()". The ID number must always be 0 <= ID < SF_LAST_ID. If not the result NULL is returned. When the function can't find a localized text for a given (correct) ID, the built-in default text is returned automatically.

Example:

BAlert  *alert

alert = new BAlert("Locale", cLang->Text(SFERRNOTEXT), cLang->Text(SFCANCEL));
alert->Go();