Funzione SetThreadPreferredUILanguages (winnls.h)

Articolo
03/04/2024

Imposta le lingue dell'interfaccia utente preferite per il thread corrente. Per altre informazioni, vedere Gestione del linguaggio dell'interfaccia utente.

Nota Questa funzione viene usata anche dal sistema operativo per identificare le lingue che sono sicure da usare nella console di Windows.

Sintassi

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

Parametri

[in] dwFlags

Contrassegni che identificano il formato e il filtro per le lingue da impostare.

I flag di formato seguenti specificano il formato della lingua da usare per le lingue preferite dell'interfaccia utente del thread. I flag si escludono a vicenda e il valore predefinito è MUI_LANGUAGE_NAME.

È consigliabile usare MUI_LANGUAGE_NAME anziché MUI_LANGUAGE_ID.

Valore	Significato
MUI_LANGUAGE_ID	Le stringhe della lingua dei parametri di input sono in formato identificatore di lingua .
MUI_LANGUAGE_NAME	Le stringhe della lingua dei parametri di input sono in formato nome lingua .

I flag di filtro seguenti specificano il filtro per l'elenco di lingue. I flag si escludono a vicenda. Per impostazione predefinita, non è impostato né MUI_COMPLEX_SCRIPT_FILTER né MUI_CONSOLE_FILTER. Per altre informazioni sui flag di filtro, vedere la sezione Osservazioni.

Valore	Significato
MUI_COMPLEX_SCRIPT_FILTER	GetThreadPreferredUILanguages deve sostituire con il fallback appropriato per tutti i linguaggi con script complessi. Quando viene specificato questo flag, è necessario passare NULL per tutti gli altri parametri.
MUI_CONSOLE_FILTER	GetThreadPreferredUILanguages deve sostituire con il fallback appropriato tutte le lingue che non possono essere visualizzate correttamente in una finestra della console con le impostazioni correnti del sistema operativo. Quando viene specificato questo flag, è necessario passare NULL per tutti gli altri parametri.
MUI_RESET_FILTERS	Reimpostare il filtro per l'elenco di lingue rimuovendo eventuali altre impostazioni di filtro. Quando viene specificato questo flag, è necessario passare NULL per tutti gli altri parametri. Dopo aver impostato questo flag, l'applicazione può chiamare GetThreadPreferredUILanguages per recuperare l'elenco completo non filtrato.

[in, optional] pwszLanguagesBuffer

Puntatore a un buffer a più stringhe con terminazione Null doppia contenente un elenco ordinato delimitato da Null, nel formato specificato da dwFlags.

Per cancellare l'elenco di lingue dell'interfaccia utente preferite del thread, un'applicazione imposta questo parametro su una stringa Null o una stringa vuota con terminazione Null. Se un'applicazione cancella un elenco di lingue, deve specificare un flag di formato o 0 per il parametro dwFlags .

Quando l'applicazione specifica uno dei flag di filtro, deve impostare questo parametro su NULL. In questo caso, la funzione ha esito positivo, ma non reimposta le lingue preferite del thread.

[out, optional] pulNumLanguages

Puntatore al numero di lingue impostate dalla funzione nell'elenco delle lingue dell'interfaccia utente preferite del thread. Quando l'applicazione specifica uno dei flag di filtro, la funzione deve impostare questo parametro su NULL.

Valore restituito

Restituisce TRUE se la funzione ha esito positivo o FALSE in caso contrario.

Commenti

Quando l'applicazione carica le risorse dopo una chiamata a questa funzione, le preferenze specifiche del thread hanno la priorità sulle lingue preferite dall'utente.

Questa funzione può impostare fino a cinque lingue preferite per il thread, in ordine di preferenza. Se il buffer di lingua contiene più di cinque lingue valide, la funzione imposta le prime cinque lingue valide e ignora il resto.

Se l'applicazione chiama questa funzione con il flag MUI_LANGUAGE_ID impostato, le stringhe nell'elenco di lingue devono usare il linguaggio esadecimale

identificatori che non includono l'0x iniziale e sono di 4 caratteri. Ad esempio, en-US deve essere

passato come "0409" e en come "0009".

Quando si specifica MUI_LANGUAGE_ID, i valori esadecimali nell'elenco delle lingue devono rappresentare un identificatore di lingua effettivo. In particolare, non è possibile usare i valori di identificatore delle impostazioni locali seguenti per corrispondere all'identificatore di lingua:

La chiamata a questa funzione con un elenco di lingue vuoto e l'impostazione del flag MUI_CONSOLE_FILTER ha lo stesso effetto della chiamata a SetThreadUILanguage con l'identificatore di lingua impostato su 0. La lingua viene impostata in modo appropriato per l'uso in una finestra della console.

Al termine di questa funzione, l'applicazione può chiamare GetThreadPreferredUILanguages per verificare ed esaminare l'elenco di lingue risultanti. Quando MUI_CONSOLE_FILTER o MUI_COMPLEX_FILTER è stato impostato da SetThreadPreferredUILanguages, la funzione GetThreadPreferredUILanguages sostituisce con il fallback le lingue che la console non può visualizzare usando l'impostazione corrente della lingua del sistema operativo. Il fallback per una lingua viene determinato in base al valore di LOCALE_SCONSOLEFALLBACKNAME per la lingua.

Impostando il flag MUI_COMPLEX_SCRIPT_FILTER nella chiamata a SetThreadPreferredUILanguages , GetThreadPreferredUILanguages rimuove le lingue che la console non può visualizzare con lingue di cui è possibile eseguire il rendering solo tramite Uniscribe e inserire il linguaggio di fallback come fallback finale. Esempi di tali lingue sono l'arabo o le varie lingue indice.

L'impostazione del flag MUI_CONSOLE_FILTER nella chiamata a SetThreadPreferredUILanguages fa sì che GetThreadPreferredUILanguages rimuovono le lingue che la console non può visualizzare con l'impostazione di sistema corrente e inserire il linguaggio di fallback come fallback finale, perché la console è limitata alla visualizzazione di caratteri da una singola tabella codici. Ad esempio, se la lingua dell'utente è giapponese (Giappone), ma la tabella codici della console corrente è la tabella codici per russo (Russia), la console visualizza il testo in lingua giapponese principalmente come una serie di simboli di caratteri non trovati. GetThreadPreferredUILanguages sceglie una lingua dall'elenco di fallback che sarà leggibile nella console.

Nota Anche le funzioni di caricamento delle risorse, ad esempio LoadString, LoadImage e FindResource, effettuano chiamate a GetThreadPreferredUILanguages.

Per modificare la tabella codici, l'applicazione usa la funzione setlocale o equivalente.

Firma C#

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll