Função SetThreadPreferredUILanguages (winnls.h)

  • Artigo

Define os idiomas de interface do usuário preferenciais do thread para o thread atual. Para obter mais informações, consulte Gerenciamento de linguagem de interface do usuário.

Nota Essa função também é usada pelo sistema operacional para identificar idiomas que são seguros de usar no console do Windows.
 

Sintaxe

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

Parâmetros

[in] dwFlags

Sinaliza a identificação do formato e da filtragem para os idiomas a serem definidos.

Os sinalizadores de formato a seguir especificam o formato de idioma a ser usado para os idiomas de interface do usuário preferenciais do thread. Os sinalizadores são mutuamente exclusivos e o padrão é MUI_LANGUAGE_NAME.

Recomendamos que você use MUI_LANGUAGE_NAME em vez de MUI_LANGUAGE_ID.

Valor Significado
MUI_LANGUAGE_ID
 As cadeias de caracteres de linguagem do parâmetro de entrada estão no formato de identificador de idioma .
MUI_LANGUAGE_NAME
 As cadeias de caracteres de linguagem do parâmetro de entrada estão no formato de nome de idioma .
 

Os sinalizadores de filtragem a seguir especificam a filtragem para a lista de idiomas. Os sinalizadores são mutuamente exclusivos. Por padrão, nem MUI_COMPLEX_SCRIPT_FILTER nem MUI_CONSOLE_FILTER está definido. Para obter mais informações sobre os sinalizadores de filtragem, consulte a seção Comentários.

Valor Significado
MUI_COMPLEX_SCRIPT_FILTER

GetThreadPreferredUILanguages deve substituir pelo fallback apropriado de todas as linguagens com scripts complexos. Quando esse sinalizador é especificado, NULL deve ser passado para todos os outros parâmetros.
MUI_CONSOLE_FILTER

GetThreadPreferredUILanguages deve substituir pelo fallback apropriado de todos os idiomas que não podem ser exibidos corretamente em uma janela do console com as configurações atuais do sistema operacional. Quando esse sinalizador é especificado, NULL deve ser passado para todos os outros parâmetros.
MUI_RESET_FILTERS
 Redefina a filtragem da lista de idiomas removendo outras configurações de filtro. Quando esse sinalizador é especificado, NULL deve ser passado para todos os outros parâmetros. Depois de definir esse sinalizador, o aplicativo pode chamar GetThreadPreferredUILanguages para recuperar a lista completa não filtrada.

[in, optional] pwszLanguagesBuffer

Ponteiro para um buffer de várias cadeias de caracteres com terminação nula dupla que contém uma lista ordenada e delimitada por nulo, no formato especificado por dwFlags.

Para limpar a lista de idiomas de interface do usuário preferenciais do thread, um aplicativo define esse parâmetro como uma cadeia de caracteres nula ou uma cadeia de caracteres vazia terminada em nulo duplo. Se um aplicativo limpar uma lista de idiomas, ele deverá especificar um sinalizador de formato ou 0 para o parâmetro dwFlags .

Quando o aplicativo especifica um dos sinalizadores de filtragem, ele deve definir esse parâmetro como NULL. Nesse caso, a função é bem-sucedida, mas não redefine os idiomas preferenciais do thread.

[out, optional] pulNumLanguages

Ponteiro para o número de idiomas que a função definiu na lista de idiomas de interface do usuário preferenciais do thread. Quando o aplicativo especifica um dos sinalizadores de filtragem, a função deve definir esse parâmetro como NULL.

Retornar valor

Retornará TRUE se a função for bem-sucedida ou FALSE caso contrário.

Comentários

Quando o aplicativo carrega recursos após uma chamada para essa função, as preferências específicas do thread têm prioridade sobre os idiomas preferidos pelo usuário.

Essa função pode configurar até cinco idiomas preferenciais para o thread, em ordem de preferência. Se o buffer de idioma contiver mais de cinco idiomas válidos, a função definirá os cinco primeiros idiomas válidos e ignorará o restante.

Se o aplicativo chamar essa função com o sinalizador MUI_LANGUAGE_ID definido, as cadeias de caracteres na lista de idiomas deverão usar linguagem hexadecimal

identificadores que não incluem o 0x à esquerda e têm 4 caracteres de comprimento. Por exemplo, en-US deve ser

passado como "0409" e en como "0009".

Quando MUI_LANGUAGE_ID é especificado, os valores hexadecimal na lista de idiomas devem representar um identificador de idioma real. Em particular, os seguintes valores de identificador de localidade não podem ser usados para corresponder ao identificador de idioma:

Chamar essa função com uma lista de idiomas vazia e definir o sinalizador MUI_CONSOLE_FILTER tem o mesmo efeito que chamar SetThreadUILanguage com o identificador de idioma definido como 0. O idioma é definido adequadamente para uso em uma janela do console.

Depois que essa função retornar, o aplicativo poderá chamar GetThreadPreferredUILanguages para verificar e examinar a lista de idiomas resultante. Quando MUI_CONSOLE_FILTER ou MUI_COMPLEX_FILTER foi definido por SetThreadPreferredUILanguages, a função GetThreadPreferredUILanguages substitui pelo fallback dos idiomas que o console não pode exibir usando a configuração de idioma do sistema operacional atual. O fallback de um idioma é determinado com base no valor de LOCALE_SCONSOLEFALLBACKNAME para o idioma.

Definir o sinalizador MUI_COMPLEX_SCRIPT_FILTER na chamada para SetThreadPreferredUILanguages faz com que GetThreadPreferredUILanguages remova idiomas que o console não pode exibir com idiomas que só podem ser renderizados usando Uniscribe e insira o idioma de fallback como o fallback final. Exemplos desses idiomas são árabe ou os vários idiomas índices.

Definir o sinalizador MUI_CONSOLE_FILTER na chamada para SetThreadPreferredUILanguages faz com que GetThreadPreferredUILanguages remova idiomas que o console não pode exibir com a configuração atual do sistema e insira o idioma de fallback como o fallback final, pois o console está limitado a exibir caracteres de uma única página de código. Por exemplo, se o idioma do usuário for japonês (Japão), mas a página de código do console atual for a página de código para russo (Rússia), o console exibirá o texto em japonês principalmente como uma série de símbolos não encontrados. GetThreadPreferredUILanguages escolhe um idioma na lista de fallback que será legível no console.

Nota As funções de carregamento de recursos, como LoadString, LoadImage e FindResource, também fazem chamadas para GetThreadPreferredUILanguages.
 
Para alterar a página de código, o aplicativo usa a função setlocale ou equivalente.

Assinatura do C#

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

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winnls.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

GetThreadPreferredUILanguages

Interface do Usuário Multilíngue

Funções de interface do usuário multilíngue

SetThreadUILanguage