SetThreadPreferredUILanguages-Funktion (winnls.h)

Artikel
08/27/2023

Legt die bevorzugten Benutzeroberflächensprachen des Threads für den aktuellen Thread fest. Weitere Informationen finden Sie unter Benutzeroberflächensprachverwaltung.

Hinweis Diese Funktion wird auch vom Betriebssystem verwendet, um Sprachen zu identifizieren, die in der Windows-Konsole sicher verwendet werden können.

Syntax

BOOL SetThreadPreferredUILanguages(
  [in]            DWORD    dwFlags,
  [in, optional]  PCZZWSTR pwszLanguagesBuffer,
  [out, optional] PULONG   pulNumLanguages
);

Parameter

[in] dwFlags

Flags, die das Format und die Filterung für die festzulegenden Sprachen identifizieren.

Die folgenden Formatflags geben das Sprachformat an, das für die bevorzugten Benutzeroberflächensprachen des Threads verwendet werden soll. Die Flags schließen sich gegenseitig aus, und der Standardwert ist MUI_LANGUAGE_NAME.

Es wird empfohlen, MUI_LANGUAGE_NAME anstelle von MUI_LANGUAGE_ID zu verwenden.

Wert	Bedeutung
MUI_LANGUAGE_ID	Die Sprachzeichenfolgen des Eingabeparameters haben ein Sprachbezeichnerformat .
MUI_LANGUAGE_NAME	Die Sprachzeichenfolgen des Eingabeparameters haben das Format des Sprachnamens .

Die folgenden Filterflags geben die Filterung für die Sprachliste an. Die Flags schließen sich gegenseitig aus. Standardmäßig ist weder MUI_COMPLEX_SCRIPT_FILTER noch MUI_CONSOLE_FILTER festgelegt. Weitere Informationen zu den Filterflags finden Sie im Abschnitt Hinweise.

Wert	Bedeutung
MUI_COMPLEX_SCRIPT_FILTER	GetThreadPreferredUILanguages sollte alle Sprachen mit komplexen Skripts durch das entsprechende Fallback ersetzen. Wenn dieses Flag angegeben wird, muss NULL für alle anderen Parameter übergeben werden.
MUI_CONSOLE_FILTER	GetThreadPreferredUILanguages sollte alle Sprachen, die nicht ordnungsgemäß in einem Konsolenfenster mit den aktuellen Betriebssystemeinstellungen angezeigt werden können, durch das entsprechende Fallback ersetzen. Wenn dieses Flag angegeben wird, muss NULL für alle anderen Parameter übergeben werden.
MUI_RESET_FILTERS	Setzen Sie die Filterung für die Sprachliste zurück, indem Sie alle anderen Filtereinstellungen entfernen. Wenn dieses Flag angegeben wird, muss NULL für alle anderen Parameter übergeben werden. Nach dem Festlegen dieses Flags kann die Anwendung GetThreadPreferredUILanguages aufrufen, um die vollständige ungefilterte Liste abzurufen.

[in, optional] pwszLanguagesBuffer

Zeiger auf einen doppelt mit NULL endendten Puffer mit mehreren Zeichenfolgen, der eine geordnete, durch NULL getrennte Liste im von dwFlags angegebenen Format enthält.

Um die Liste der bevorzugten Benutzeroberflächensprachen des Threads zu löschen, legt eine Anwendung diesen Parameter auf eine NULL-Zeichenfolge oder eine leere doppelte Zeichenfolge mit NULL-Beendigung fest. Wenn eine Anwendung eine Sprachliste löscht, sollte sie entweder ein Formatflag oder 0 für den dwFlags-Parameter angeben.

Wenn die Anwendung eines der Filterflags angibt, muss sie diesen Parameter auf NULL festlegen. In diesem Fall ist die Funktion erfolgreich, setzt jedoch die bevorzugten Threadsprachen nicht zurück.

[out, optional] pulNumLanguages

Zeiger auf die Anzahl der Sprachen, die die Funktion in der Liste der bevorzugten Benutzeroberflächensprachen des Threads festgelegt hat. Wenn die Anwendung eines der Filterflags angibt, muss die Funktion diesen Parameter auf NULL festlegen.

Rückgabewert

Gibt TRUE zurück, wenn die Funktion erfolgreich ist, oder andernfalls FALSE .

Hinweise

Wenn die Anwendung nach einem Aufruf dieser Funktion Ressourcen lädt, haben die threadspezifischen Einstellungen Vorrang vor den vom Benutzer bevorzugten Sprachen.

Diese Funktion kann bis zu fünf bevorzugte Sprachen für den Thread in der Reihenfolge ihrer Präferenzen einrichten. Wenn der Sprachpuffer mehr als fünf gültige Sprachen enthält, legt die Funktion die ersten fünf gültigen Sprachen fest und ignoriert den Rest.

Wenn die Anwendung diese Funktion mit festgelegtem MUI_LANGUAGE_ID-Flag aufruft, müssen die Zeichenfolgen in der Sprachliste hexadezimale Sprache verwenden.

Bezeichner, die das führende 0x nicht enthalten und 4 Zeichen lang sind. en-US sollte z. B.

passed as "0409" and en as "0009".

Wenn MUI_LANGUAGE_ID angegeben wird, müssen die Hexadezimalwerte in der Sprachliste jeweils einen tatsächlichen Sprachbezeichner darstellen. Insbesondere können die folgenden Gebietsschemabezeichnerwerte nicht verwendet werden, um dem Sprachbezeichner zu entsprechen:

Das Aufrufen dieser Funktion mit einer leeren Sprachliste und das Festlegen des MUI_CONSOLE_FILTER-Flags hat die gleiche Auswirkung wie das Aufrufen von SetThreadUILanguage , wobei der Sprachbezeichner auf 0 festgelegt ist. Die Sprache ist für die Verwendung in einem Konsolenfenster entsprechend festgelegt.

Nachdem diese Funktion zurückgegeben wurde, kann die Anwendung GetThreadPreferredUILanguages aufrufen, um die resultierende Sprachliste zu überprüfen und zu untersuchen. Wenn MUI_CONSOLE_FILTER oder MUI_COMPLEX_FILTER von SetThreadPreferredUILanguages festgelegt wurde, ersetzt die GetThreadPreferredUILanguages-Funktion durch das Fallback die Sprachen, die die Konsole mit der aktuellen Spracheinstellung des Betriebssystems nicht anzeigen kann. Der Fallback für eine Sprache wird basierend auf dem Wert von LOCALE_SCONSOLEFALLBACKNAME für die Sprache bestimmt.

Durch das Festlegen des MUI_COMPLEX_SCRIPT_FILTER-Flags im Aufruf von SetThreadPreferredUILanguages entfernt GetThreadPreferredUILanguages Sprachen, die die Konsole nicht mit Sprachen anzeigen kann, die nur mit Uniscribe gerendert werden können, und fügt die Fallbacksprache als ultimatives Fallback ein. Beispiele für solche Sprachen sind Arabisch oder die verschiedenen indischen Sprachen.

Das Festlegen des MUI_CONSOLE_FILTER-Flags im Aufruf von SetThreadPreferredUILanguages bewirkt , dass GetThreadPreferredUILanguages Sprachen entfernt, die die Konsole nicht mit der aktuellen Systemeinstellung anzeigen kann, und fügt die Fallbacksprache als ultimatives Fallback ein, da die Konsole auf die Anzeige von Zeichen einer einzelnen Codepage beschränkt ist. Wenn die Benutzersprache beispielsweise Japanisch (Japan) ist, die aktuelle Konsolencodepage jedoch die Codepage für Russisch (Russland) ist, zeigt die Konsole den japanischen Text hauptsächlich als eine Reihe von Zeichen an, die nicht gefunden wurden. GetThreadPreferredUILanguages wählt eine Sprache aus der Fallbackliste aus, die in der Konsole lesbar ist.

Hinweis Ressourcenladefunktionen wie LoadString, LoadImage und FindResource rufen auch GetThreadPreferredUILanguages auf.

Um die Codepage zu ändern, verwendet die Anwendung die setlocale-Funktion oder eine entsprechende.

C#-Signatur

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean SetThreadPreferredUILanguages(
            System.UInt32 dwFlags,
            System.String pwszLanguagesBuffer,
            ref System.UInt32 pulNumLanguages
            );

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winnls.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

GetThreadPreferredUILanguages

Multilingual User Interface

Mehrsprachige Benutzeroberflächenfunktionen

SetThreadUILanguage

Freigeben über