Fungsi SetThreadPreferredUILanguages (winnls.h)

Artikel
08/27/2023

Mengatur bahasa UI pilihan utas untuk utas saat ini. Untuk informasi selengkapnya, lihat Manajemen Bahasa Antarmuka Pengguna.

Catatan Fungsi ini juga digunakan oleh sistem operasi untuk mengidentifikasi bahasa yang aman digunakan pada konsol Windows.

Sintaks

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

Parameter

[in] dwFlags

Bendera yang mengidentifikasi format dan pemfilteran untuk mengatur bahasa.

Bendera format berikut menentukan format bahasa yang akan digunakan untuk bahasa UI pilihan utas. Bendera saling eksklusif, dan defaultnya adalah MUI_LANGUAGE_NAME.

Kami menyarankan agar Anda menggunakan MUI_LANGUAGE_NAME alih-alih MUI_LANGUAGE_ID.

Nilai	Makna
MUI_LANGUAGE_ID	String bahasa parameter input dalam format pengidentifikasi bahasa .
MUI_LANGUAGE_NAME	String bahasa parameter input dalam format nama bahasa .

Bendera pemfilteran berikut menentukan pemfilteran untuk daftar bahasa. Bendera saling eksklusif. Secara default, baik MUI_COMPLEX_SCRIPT_FILTER maupun MUI_CONSOLE_FILTER tidak diatur. Untuk informasi selengkapnya tentang bendera pemfilteran, lihat bagian Keterangan.

Nilai	Makna
MUI_COMPLEX_SCRIPT_FILTER	GetThreadPreferredUILanguages harus mengganti dengan fallback yang sesuai semua bahasa yang memiliki skrip yang kompleks. Ketika bendera ini ditentukan, NULL harus diteruskan untuk semua parameter lainnya.
MUI_CONSOLE_FILTER	GetThreadPreferredUILanguages harus mengganti dengan fallback yang sesuai semua bahasa yang tidak dapat ditampilkan dengan benar di jendela konsol dengan pengaturan sistem operasi saat ini. Ketika bendera ini ditentukan, NULL harus diteruskan untuk semua parameter lainnya.
MUI_RESET_FILTERS	Reset pemfilteran untuk daftar bahasa dengan menghapus pengaturan filter lainnya. Ketika bendera ini ditentukan, NULL harus diteruskan untuk semua parameter lainnya. Setelah mengatur bendera ini, aplikasi dapat memanggil GetThreadPreferredUILanguages untuk mengambil daftar lengkap yang tidak difilter.

[in, optional] pwszLanguagesBuffer

Penunjuk ke buffer multi-string ganda yang dihentikan null yang berisi daftar yang diurutkan dan dibatasi null, dalam format yang ditentukan oleh dwFlags.

Untuk menghapus daftar bahasa UI pilihan utas, aplikasi mengatur parameter ini ke string null atau string kosong yang dihentikan null ganda. Jika aplikasi menghapus daftar bahasa, aplikasi harus menentukan bendera format atau 0 untuk parameter dwFlags .

Ketika aplikasi menentukan salah satu bendera pemfilteran, aplikasi harus mengatur parameter ini ke NULL. Dalam hal ini, fungsi berhasil, tetapi tidak mengatur ulang bahasa pilihan utas.

[out, optional] pulNumLanguages

Arahkan ke jumlah bahasa yang telah diatur fungsi dalam daftar bahasa UI pilihan utas. Ketika aplikasi menentukan salah satu bendera pemfilteran, fungsi harus mengatur parameter ini ke NULL.

Mengembalikan nilai

Mengembalikan TRUE jika fungsi berhasil atau FALSE sebaliknya.

Keterangan

Ketika aplikasi memuat sumber daya setelah panggilan ke fungsi ini, preferensi khusus utas lebih diprioritaskan daripada bahasa yang disukai oleh pengguna.

Fungsi ini dapat mengatur hingga lima bahasa pilihan untuk utas, dalam urutan preferensi. Jika buffer bahasa berisi lebih dari lima bahasa yang valid, fungsi mengatur lima bahasa pertama yang valid dan mengabaikan sisanya.

Jika aplikasi memanggil fungsi ini dengan bendera MUI_LANGUAGE_ID diatur, string dalam daftar bahasa harus menggunakan bahasa heksadesimal

pengidentifikasi yang tidak menyertakan 0x di depannya, dan panjangnya 4 karakter. Misalnya, en-US harus

diteruskan sebagai "0409" dan en sebagai "0009".

Ketika MUI_LANGUAGE_ID ditentukan, nilai heksadesimal dalam daftar bahasa masing-masing harus mewakili pengidentifikasi bahasa aktual. Secara khusus, nilai pengidentifikasi lokal berikut tidak dapat digunakan untuk sesuai dengan pengidentifikasi bahasa:

Memanggil fungsi ini dengan daftar bahasa kosong dan mengatur bendera MUI_CONSOLE_FILTER memiliki efek yang sama dengan memanggil SetThreadUILanguage dengan pengidentifikasi bahasa yang diatur ke 0. Bahasa diatur dengan tepat untuk digunakan di jendela konsol.

Setelah fungsi ini kembali, aplikasi dapat memanggil GetThreadPreferredUILanguages untuk memverifikasi dan memeriksa daftar bahasa yang dihasilkan. Ketika MUI_CONSOLE_FILTER atau MUI_COMPLEX_FILTER telah ditetapkan oleh SetThreadPreferredUILanguages, fungsi GetThreadPreferredUILanguages menggantikan dengan fallback bahasa yang tidak dapat ditampilkan konsol menggunakan pengaturan bahasa sistem operasi saat ini. Fallback untuk bahasa ditentukan berdasarkan nilai LOCALE_SCONSOLEFALLBACKNAME untuk bahasa tersebut.

Mengatur bendera MUI_COMPLEX_SCRIPT_FILTER dalam panggilan ke SetThreadPreferredUILanguages menyebabkan GetThreadPreferredUILanguages menghapus bahasa yang tidak dapat ditampilkan konsol dengan bahasa yang hanya dapat dirender menggunakan Uniscribe, dan menyisipkan bahasa fallback sebagai fallback akhir. Contoh bahasa tersebut adalah bahasa Arab atau berbagai bahasa Indik.

Mengatur bendera MUI_CONSOLE_FILTER dalam panggilan ke SetThreadPreferredUILanguages menyebabkan GetThreadPreferredUILanguages menghapus bahasa yang tidak dapat ditampilkan konsol dengan pengaturan sistem saat ini dan memasukkan bahasa fallback sebagai fallback utama, karena konsol terbatas untuk menampilkan karakter dari satu halaman kode. Misalnya, jika bahasa pengguna adalah Bahasa Jepang (Jepang), tetapi halaman kode konsol saat ini adalah halaman kode untuk Bahasa Rusia (Rusia), konsol menampilkan teks bahasa Jepang sebagian besar sebagai serangkaian simbol karakter yang tidak ditemukan. GetThreadPreferredUILanguages memilih bahasa dari daftar fallback yang akan dapat terbaca di konsol.

Catatan Fungsi pemuatan sumber daya, seperti LoadString, LoadImage, dan FindResource, juga melakukan panggilan ke GetThreadPreferredUILanguages.

Untuk mengubah halaman kode, aplikasi menggunakan fungsi setlocale , atau setara.

Tanda Tangan C#

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	winnls.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll