SetThreadPreferredUILanguages 函数 (winnls.h)

  • 项目

设置当前线程的线程首选 UI 语言。 有关详细信息，请参阅 用户界面语言管理。

注意 操作系统还使用此函数来识别在 Windows 主机上安全使用的语言。
 

语法

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

参数

[in] dwFlags

标识要设置的语言的格式和筛选的标志。

以下 格式标志 指定要用于线程首选 UI 语言的语言格式。 标志互斥，默认值为MUI_LANGUAGE_NAME。

建议使用 MUI_LANGUAGE_NAME 而不是MUI_LANGUAGE_ID。

值 含义
MUI_LANGUAGE_ID
 输入参数语言字符串采用 语言标识符 格式。
MUI_LANGUAGE_NAME
 输入参数语言字符串采用 语言名称 格式。
 

以下 筛选标志 指定语言列表的筛选。 标志是互斥的。 默认情况下，既不设置MUI_COMPLEX_SCRIPT_FILTER，也不设置MUI_CONSOLE_FILTER。 有关筛选标志的详细信息，请参阅“备注”部分。

值 含义
MUI_COMPLEX_SCRIPT_FILTER

GetThreadPreferredUILanguages 应替换为具有 复杂脚本的所有语言的适当回退。 指定此标志时，必须为所有其他参数传递 NULL 。
MUI_CONSOLE_FILTER

GetThreadPreferredUILanguages 应将 替换为使用当前操作系统设置在控制台窗口中无法正确显示的所有语言的适当回退。 指定此标志时，必须为所有其他参数传递 NULL 。
MUI_RESET_FILTERS
 通过删除任何其他筛选器设置来重置语言列表的筛选。 指定此标志时，必须为所有其他参数传递 NULL 。 设置此标志后，应用程序可以调用 GetThreadPreferredUILanguages 来检索完整的未筛选列表。

[in, optional] pwszLanguagesBuffer

指向以 dwFlags 指定的格式包含有序的 null 分隔列表的双 null 终止多字符串缓冲区的指针。

若要清除线程首选 UI 语言列表，应用程序将此参数设置为 null 字符串或空双 null 终止字符串。 如果应用程序清除语言列表，则应为 dwFlags 参数指定格式标志或 0。

当应用程序指定其中一个筛选标志时，它必须将此参数设置为 NULL。 在这种情况下，函数会成功，但不会重置线程首选语言。

[out, optional] pulNumLanguages

指向函数在线程首选 UI 语言列表中设置的语言数量的指针。 当应用程序指定筛选标志之一时，函数必须将此参数设置为 NULL。

返回值

如果函数成功，则返回 TRUE ;否则返回 FALSE 。

注解

当应用程序在调用此函数后加载资源时，特定于线程的首选项优先于用户首选的语言。

此函数最多可以按优先顺序为线程设置五种首选语言。 如果语言缓冲区包含五种以上有效语言，则函数将设置前五种有效语言，并忽略其余语言。

如果应用程序调用此函数并设置了 MUI_LANGUAGE_ID 标志，则语言列表中的字符串必须使用十六进制语言

不包含前导 0x 且长度为 4 个字符的标识符。 例如，en-US 应为

传递为“0409”，将 en 传递为“0009”。

指定MUI_LANGUAGE_ID时，语言列表中的十六进制值必须分别表示实际的语言标识符。 具体而言，以下区域设置标识符值不能用于与语言标识符相对应：

使用空语言列表调用此函数并设置 MUI_CONSOLE_FILTER 标志的效果与调用语言标识符设置为 0 的 SetThreadUILanguage 的效果相同。 语言设置得当，以便在控制台窗口中使用。

此函数返回后，应用程序可以调用 GetThreadPreferredUILanguages 来验证和检查生成的语言列表。 当 SetThreadPreferredUILanguages 设置了MUI_CONSOLE_FILTER或MUI_COMPLEX_FILTER时， GetThreadPreferredUILanguages 函数将替换为主机使用当前操作系统语言设置无法显示的语言的回退。 语言的回退基于语言 的 LOCALE_SCONSOLEFALLBACKNAME 值确定。

在调用 SetThreadPreferredUILanguages 中设置MUI_COMPLEX_SCRIPT_FILTER标志会导致 GetThreadPreferredUILanguages 删除控制台无法显示的语言，这些语言只能使用 Uniscribe 呈现，并插入回退语言作为最终回退。 此类语言的示例包括阿拉伯语或各种印度语。

在调用 SetThreadPreferredUILanguages 时设置MUI_CONSOLE_FILTER标志会导致 GetThreadPreferredUILanguages 删除主机在当前系统设置中无法显示的语言，并插入回退语言作为最终回退，因为主机仅限于显示单个 代码页中的字符。 例如，如果用户语言是日语 (日本) ，但当前控制台代码页是俄语 (俄罗斯) 的代码页，则控制台主要将日语文本显示为一系列未找到字符的符号。 GetThreadPreferredUILanguages 从回退列表中选择在控制台中可读的语言。

注意 资源加载函数（如 LoadString、 LoadImage 和 FindResource）也会调用 GetThreadPreferredUILanguages。
 
若要更改代码页，应用程序使用 setlocale 函数或等效函数。

C# 签名

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

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 winnls.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

GetThreadPreferredUILanguages

多语言用户界面

多语言用户界面函数

SetThreadUILanguage