Siegfried Locale Editor Developer Guide

Funktionsübersicht

SFLocale *GetInstance()

Über die Funktion "GetInstance()" wird der Zugriff auf die Textdaten hergestellt. Entgegen anderen Klassen ist das Erzeugen eines Objekts von Typ "SFLocale" nicht nötig (und auch nicht möglich). Es wird immer mit einem Zeiger auf das Objekt gearbeitet. Die Klasse "SFLocale" leitet sich von dem sog. "Singelton Entwurfsmuster" ab. Dadurch wird gewährleistet das immer nur eine Instanz der Klasse innerhalb der Anwendung verwendet wird. Dies spart Speicherplatz und hält beim Wechseln der Sprache die Daten konsistent.

Beispiel:

SFLocale *lang;

lang = SFLocale::GetInstance();     // Zugriff auf Textdaten herstellen

An jeder Stelle an der Textdaten benötigt werden kann dieser Aufruf erfolgen. Es wird immer auf dieselbe Instanz der Klasse zugegriffen. Der Zeiger auf die Instanz kann entweder als globale Variable verwendet werden, was allerdings nicht unbedingt guten Programmierstil entspricht, da das Prinzip der Kapselung durchbrochen wird. Besser ist den Zeiger auf die Instanz als "private" Variable innerhalb einer Klasse zu deklarieren (oder bei Basisklassen als "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)

Sprachdaten laden. Es wird der Pfad als erster Parameter übergeben in dem die "locale" Dateien für die Anwendung abgelegt sind. Der zweite Parameter ist die gewünschte Sprache die geladen werden soll. Dies muss nicht der Name der Sprachdatei sein! Der Name der Sprache ist als String-Attribut "sf::language" gespeichert und wird von der Laderoutine ausgewertet, daher die Unabhängigkeit von dem Dateinamen.

Kann die gewünschte "locale" Datei nicht gefunden werden, wird mit der Defaultsprache (Englisch) weitergearbeitet.

Folgende Ergebnisse können zurückgegeben werden:

0 = alles OK
1 = Fehler: Datei konnte nicht gelesen werden
2 = Fehler: keine Sprachdatei
3 = Fehler: falsche Sprachdatei (AppID nicht korrekt)
4 = Fehler: Datei enthält keine Länderkennung
5 = Fehler: ungültiges Verzeichnis

Beispiel:

BPath    path;
BEntry   entry;
app_info info;
      :
      :
be_app->GetAppInfo(&info);               // Programminfo holen
entry.SetTo(&info.ref);                  // Entry auf Programm holen
entry.GetPath(&path);                    // Pfad + Dateiname
path.GetParent(&path);                   // Programmpfad ermitteln
path.Append("locale");                   // Sprachdaten-Pfad anhaengen
cLang->SetLanguage(&path, "Deutsch");    // Sprache "Deutsch" laden


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

Sprachvorgabedaten setzen. Es werden die Vorgabetexte als Feld, die Anzahl der Texte und der Name der Vorgabesprache (sollte Englisch sein) übergeben. Die Vorgabetexte und der Name der Sprache werden von "SetDefaultText()" umkopiert.

Die Funktion wird üblicherweise beim Start der Anwendung aufgerufen. Das Feld der Vorgabetexte baut sich wie folgt auf:

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
};

Die Vorgabetexte sollten zentral in einer Include-Datei gesammelt werden.

Beispiel:

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

lang = SFLocale::GetInstance();     // Zugriff auf Sprachdaten
lang->SetAppID(SF_TEXT_APP_ID);     // Anwendungskennung setzen
// --- Vorgabetexte setzen ---
lang->SetDefaultText(mText, SF_LAST_ID, SF_DEFAULT_LANGUAGE);
      :
      :


void SetAppID(const char *app_id)

Setzen der Anwendungs-ID zur korrekten identifizierung der "locale"-Dateien. Die übergebene Zeichenkette dient zur Identifizierung der "locale"-Dateien beim Laden mit "SetLanguage()". Es muss hier dieselbe Kennung angegeben werden wie sie im Siegfried Locale Editor unter "Application ID" für die "locale"-Dateien angegeben wurde. Es werden von der Anwendung nur solche "locale"-Dateien geladen die über die exakte Kennung verfügen. Die übergebene Kennung wird von der Funktion kopiert.

Wie bei "SetDefaultText()" sollte der Aufruf von "SetAppID()" beim Starten der Anwendung ausgeführt werden.

Beispiel: siehe Beispiel bei Funktion "SetDefaultText()"


const char *AppID()

Ermitteln der gesetzten Erkennungs ID für die "locale"-Dateien der Anwendung.


const char *Language()

Ermitteln der aktuell gesetzten Sprache. Es wird ein Zeiger auf den Namen der Sprache geliefert. Der Name der Sprache ist immer in der Muttersprache verfasst. Für die Sprache Deutsch wird "Deutsch" zurückgeliefert, für Französisch "Francais". Der aktuelle Sprachname wird beim Laden einer "locale"-Datei (per "SetLanguage()" gesetzt.


const char *Text(int32 id)

Die zentrale Funktion der "sfliblocale.so" Library. Aus der übergebenen ID wird je nach geladener "locale"-Datei der entsprechende Zeiger auf den Text ermittelt. Die sollte immer 0 <= id < SF_LAST_ID. Ansonsten wird als Ergebnis NULL zurückgeliefert. Kann unter der angegebene ID kein Text der geladenen Sprache ermittelt werden, wird automatisch der interne (englische) Text zurückgeliefert.

Beispiel:

BAlert  *alert

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