SetThreadPreferredUILanguages function (winnls.h)
Sets the thread preferred UI languages for the current thread. For more information, see User Interface Language Management.
Syntax
BOOL SetThreadPreferredUILanguages(
[in] DWORD dwFlags,
[in, optional] PCZZWSTR pwszLanguagesBuffer,
[out, optional] PULONG pulNumLanguages
);
Parameters
[in] dwFlags
Flags identifying format and filtering for the languages to set.
The following format flags specify the language format to use for the thread preferred UI languages. The flags are mutually exclusive, and the default is MUI_LANGUAGE_NAME.
We recommend that you use MUI_LANGUAGE_NAME instead of MUI_LANGUAGE_ID.
| Value | Meaning |
|---|---|
|
The input parameter language strings are in language identifier format. |
|
The input parameter language strings are in language name format. |
The following filtering flags specify filtering for the language list. The flags are mutually exclusive. By default, neither MUI_COMPLEX_SCRIPT_FILTER nor MUI_CONSOLE_FILTER is set. For more information about the filtering flags, see the Remarks section.
| Value | Meaning |
|---|---|
|
GetThreadPreferredUILanguages should replace with the appropriate fallback all languages having complex scripts. When this flag is specified, NULL must be passed for all other parameters. |
|
GetThreadPreferredUILanguages should replace with the appropriate fallback all languages that cannot display properly in a console window with the current operating system settings. When this flag is specified, NULL must be passed for all other parameters. |
|
Reset the filtering for the language list by removing any other filter settings. When this flag is specified, NULL must be passed for all other parameters. After setting this flag, the application can call GetThreadPreferredUILanguages to retrieve the complete unfiltered list. |
[in, optional] pwszLanguagesBuffer
Pointer to a double null-terminated multi-string buffer that contains an ordered, null-delimited list, in the format specified by dwFlags.
To clear the thread preferred UI languages list, an application sets this parameter to a null string or an empty double null-terminated string. If an application clears a language list, it should specify either a format flag or 0 for the dwFlags parameter.
When the application specifies one of the filtering flags, it must set this parameter to NULL. In this case, the function succeeds, but does not reset the thread preferred languages.
[out, optional] pulNumLanguages
Pointer to the number of languages that the function has set in the thread preferred UI languages list. When the application specifies one of the filtering flags, the function must set this parameter to NULL.
Return value
Returns TRUE if the function succeeds or FALSE otherwise.
Remarks
When the application loads resources after a call to this function, the thread-specific preferences take priority over the languages preferred by the user.
This function can set up to five preferred languages for the thread, in order of preference. If the language buffer contains more than five valid languages, the function sets the first five valid languages and ignores the rest.
If the application calls this function with the MUI_LANGUAGE_ID flag set, the strings in the language list must use hexadecimal language
identifiers that do not include the leading 0x, and are 4 characters in length. For example, en-US should be
passed as "0409" and en as "0009".
When MUI_LANGUAGE_ID is specified, the hexadecimal values in the language list must each represent an actual language identifier. In particular, the following locale identifier values cannot be used to correspond to the language identifier:
- LOCALE_SYSTEM_DEFAULT
- LOCALE_USER_DEFAULT
- LOCALE_CUSTOM_DEFAULT
- LOCALE_CUSTOM_UI_DEFAULT
- LOCALE_CUSTOM_UNSPECIFIED
After this function returns, the application can call GetThreadPreferredUILanguages to verify and examine the resulting language list. When MUI_CONSOLE_FILTER or MUI_COMPLEX_FILTER has been set by SetThreadPreferredUILanguages, the GetThreadPreferredUILanguages function replaces with the fallback the languages the console cannot display using the current operating system language setting. The fallback for a language is determined based on the value of LOCALE_SCONSOLEFALLBACKNAME for the language.
Setting the MUI_COMPLEX_SCRIPT_FILTER flag in the call to SetThreadPreferredUILanguages causes GetThreadPreferredUILanguages to remove languages that the console cannot display with languages that can only be rendered using Uniscribe, and insert the fallback language as the ultimate fallback. Examples of such languages are Arabic or the various Indic languages.
Setting the MUI_CONSOLE_FILTER flag in the call to SetThreadPreferredUILanguages causes GetThreadPreferredUILanguages to remove languages the console cannot display with the current system setting and insert the fallback language as the ultimate fallback, because the console is limited to displaying characters from a single code page. For example, if the user language is Japanese (Japan), but the current console code page is the code page for Russian (Russia), the console displays Japanese-language text mostly as a series of character-not-found symbols. GetThreadPreferredUILanguages chooses a language from the fallback list that will be legible in the console.
C# Signature
[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
static extern System.Boolean SetThreadPreferredUILanguages(
System.UInt32 dwFlags,
System.String pwszLanguagesBuffer,
ref System.UInt32 pulNumLanguages
);
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | winnls.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |