ホーム › Globalization › SetThreadPreferredUILanguages

SetThreadPreferredUILanguages

関数

現在のスレッドの優先UI言語リストを設定する。

DLLKERNEL32.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// KERNEL32.dll
#include <windows.h>

BOOL SetThreadPreferredUILanguages(
    DWORD dwFlags,
    LPCWSTR pwszLanguagesBuffer,   // optional
    DWORD* pulNumLanguages   // optional
);

パラメーター

名前

型

方向

説明

dwFlags

DWORD

設定する言語の形式とフィルタリングを指定するフラグです。

次の 形式フラグ は、スレッドの優先 UI 言語に使用する言語形式を指定します。これらのフラグは相互排他的で、既定値は MUI_LANGUAGE_NAME です。

MUI_LANGUAGE_ID ではなく MUI_LANGUAGE_NAME を使用することをお勧めします。

値	意味
MUI_LANGUAGE_ID	入力パラメーターの言語文字列が language identifier 形式です。
MUI_LANGUAGE_NAME	入力パラメーターの言語文字列が language name 形式です。

次の フィルタリングフラグ は、言語リストに対するフィルタリングを指定します。これらのフラグは相互排他的です。既定では、MUI_COMPLEX_SCRIPT_FILTER と MUI_CONSOLE_FILTER のいずれも設定されません。フィルタリングフラグの詳細については、「解説」セクションを参照してください。

値	意味
MUI_COMPLEX_SCRIPT_FILTER	GetThreadPreferredUILanguages は、complex scripts を持つすべての言語を適切なフォールバックに置き換えます。このフラグを指定する場合、他のすべてのパラメーターには NULL を渡す必要があります。
MUI_CONSOLE_FILTER	GetThreadPreferredUILanguages は、現在のオペレーティングシステム設定ではコンソールウィンドウに正しく表示できないすべての言語を適切なフォールバックに置き換えます。このフラグを指定する場合、他のすべてのパラメーターには NULL を渡す必要があります。
MUI_RESET_FILTERS	他のフィルター設定をすべて削除して、言語リストのフィルタリングをリセットします。このフラグを指定する場合、他のすべてのパラメーターには NULL を渡す必要があります。このフラグを設定した後、アプリケーションは GetThreadPreferredUILanguages を呼び出して、フィルタリングされていない完全なリストを取得できます。

pwszLanguagesBuffer

LPCWSTR

inoptional

dwFlags で指定された形式で、順序付けされた null 区切りのリストを含む、二重 null 終端のマルチ文字列バッファーへのポインターです。

スレッドの優先 UI 言語リストをクリアするには、アプリケーションはこのパラメーターに null 文字列または空の二重 null 終端文字列を設定します。アプリケーションが言語リストをクリアする場合は、dwFlags パラメーターに形式フラグまたは 0 のいずれかを指定する必要があります。

アプリケーションがフィルタリングフラグのいずれかを指定する場合、このパラメーターには NULL を設定する必要があります。この場合、関数は成功しますが、スレッドの優先言語はリセットされません。

pulNumLanguages

DWORD*

outoptional

関数がスレッドの優先 UI 言語リストに設定した言語の数へのポインターです。アプリケーションがフィルタリングフラグのいずれかを指定する場合、関数はこのパラメーターに NULL を設定する必要があります。

戻り値の型: BOOL

公式ドキュメント

現在のスレッドに対して、スレッドの優先 UI 言語を設定します。詳細については、User Interface Language Management を参照してください。

戻り値

関数が成功した場合は TRUE を、それ以外の場合は FALSE を返します。

解説(Remarks)

この関数を呼び出した後にアプリケーションがリソースを読み込む場合、スレッド固有の設定がユーザーの優先言語よりも優先されます。

この関数は、スレッドに対して優先順位の高い順に最大 5 つの優先言語を設定できます。言語バッファーに 5 つを超える有効な言語が含まれている場合、関数は最初の 5 つの有効な言語を設定し、残りは無視します。

アプリケーションが MUI_LANGUAGE_ID フラグを設定してこの関数を呼び出す場合、言語リスト内の文字列には、先頭の 0x を含まない 4 文字の 16 進数の言語

識別子を使用する必要があります。たとえば、en-US は

"0409"、en は "0009" として渡す必要があります。

MUI_LANGUAGE_ID を指定する場合、言語リスト内の各 16 進数値は実際の言語識別子を表す必要があります。特に、次のロケール識別子値は言語識別子に対応するものとして使用できません。

空の言語リストで 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 は、現在のシステム設定ではコンソールが表示できない言語を削除し、最終的なフォールバックとしてフォールバック言語を挿入します。これは、コンソールが単一の code page の文字の表示に制限されているためです。たとえば、ユーザー言語が日本語 (日本) であっても、現在のコンソールのコードページがロシア語 (ロシア) 用のコードページである場合、コンソールは日本語のテキストをほとんど文字が見つからないことを示す記号の列として表示します。GetThreadPreferredUILanguages は、フォールバックリストの中からコンソールで判読可能な言語を選択します。

注意 LoadString、LoadImage、FindResource などのリソース読み込み関数も、GetThreadPreferredUILanguages を呼び出します。

コードページを変更するには、アプリケーションは setlocale 関数またはそれに相当するものを使用します。

C# Signature

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll
#include <windows.h>

BOOL SetThreadPreferredUILanguages(
    DWORD dwFlags,
    LPCWSTR pwszLanguagesBuffer,   // optional
    DWORD* pulNumLanguages   // optional
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", ExactSpelling = true)]
static extern bool SetThreadPreferredUILanguages(
    uint dwFlags,   // DWORD
    [MarshalAs(UnmanagedType.LPWStr)] string pwszLanguagesBuffer,   // LPCWSTR optional
    IntPtr pulNumLanguages   // DWORD* optional, out
);

<DllImport("KERNEL32.dll", ExactSpelling:=True)>
Public Shared Function SetThreadPreferredUILanguages(
    dwFlags As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPWStr)> pwszLanguagesBuffer As String,   ' LPCWSTR optional
    pulNumLanguages As IntPtr   ' DWORD* optional, out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' dwFlags : DWORD
' pwszLanguagesBuffer : LPCWSTR optional
' pulNumLanguages : DWORD* optional, out
Declare PtrSafe Function SetThreadPreferredUILanguages Lib "kernel32" ( _
    ByVal dwFlags As Long, _
    ByVal pwszLanguagesBuffer As LongPtr, _
    ByVal pulNumLanguages As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SetThreadPreferredUILanguages = ctypes.windll.kernel32.SetThreadPreferredUILanguages
SetThreadPreferredUILanguages.restype = wintypes.BOOL
SetThreadPreferredUILanguages.argtypes = [
    wintypes.DWORD,  # dwFlags : DWORD
    wintypes.LPCWSTR,  # pwszLanguagesBuffer : LPCWSTR optional
    ctypes.POINTER(wintypes.DWORD),  # pulNumLanguages : DWORD* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
SetThreadPreferredUILanguages = Fiddle::Function.new(
  lib['SetThreadPreferredUILanguages'],
  [
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # pwszLanguagesBuffer : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # pulNumLanguages : DWORD* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn SetThreadPreferredUILanguages(
        dwFlags: u32,  // DWORD
        pwszLanguagesBuffer: *const u16,  // LPCWSTR optional
        pulNumLanguages: *mut u32  // DWORD* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll")]
public static extern bool SetThreadPreferredUILanguages(uint dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pwszLanguagesBuffer, IntPtr pulNumLanguages);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_SetThreadPreferredUILanguages' -Namespace Win32 -PassThru
# $api::SetThreadPreferredUILanguages(dwFlags, pwszLanguagesBuffer, pulNumLanguages)

#uselib "KERNEL32.dll"
#func global SetThreadPreferredUILanguages "SetThreadPreferredUILanguages" sptr, sptr, sptr
; SetThreadPreferredUILanguages dwFlags, pwszLanguagesBuffer, varptr(pulNumLanguages)   ; 戻り値は stat
; dwFlags : DWORD -> "sptr"
; pwszLanguagesBuffer : LPCWSTR optional -> "sptr"
; pulNumLanguages : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global SetThreadPreferredUILanguages "SetThreadPreferredUILanguages" int, wstr, var
; res = SetThreadPreferredUILanguages(dwFlags, pwszLanguagesBuffer, pulNumLanguages)
; dwFlags : DWORD -> "int"
; pwszLanguagesBuffer : LPCWSTR optional -> "wstr"
; pulNumLanguages : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global SetThreadPreferredUILanguages "SetThreadPreferredUILanguages" int, wstr, sptr
; res = SetThreadPreferredUILanguages(dwFlags, pwszLanguagesBuffer, varptr(pulNumLanguages))
; dwFlags : DWORD -> "int"
; pwszLanguagesBuffer : LPCWSTR optional -> "wstr"
; pulNumLanguages : DWORD* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。