Função LoadKeyboardLayoutW (winuser.h)

Artigo
03/04/2024

Carrega uma nova identificação de localidade de entrada (chamada antes de layout de teclado) no sistema.

Antes de Windows 8: vários identificadores de localidade de entrada podem ser carregados por vez, mas apenas um por processo está ativo por vez. Carregar várias identificações de localidade de entrada possibilita alternar rapidamente entre elas.

Começando no Windows 8: o identificador de localidade de entrada é carregado para todo o sistema. Essa função não terá efeito se o processo atual não possuir a janela com foco no teclado.

Sintaxe

HKL LoadKeyboardLayoutW(
  [in] LPCWSTR pwszKLID,
  [in] UINT    Flags
);

Parâmetros

[in] pwszKLID

Tipo: LPCTSTR

O nome do identificador de localidade de entrada a ser carregado. Esse nome é uma cadeia de caracteres composta pelo valor hexadecimal do Identificador de Idioma (palavra baixa) e um identificador de dispositivo (palavra alta). Por exemplo, o inglês dos EUA tem um identificador de idioma de 0x0409, portanto, o layout principal em inglês dos EUA é chamado de "00000409". Variantes do layout em inglês dos EUA (como o layout Dvorak) são chamadas de "00010409", "00020409" e assim por diante.

Para obter uma lista dos layouts de entrada fornecidos com o Windows, consulte Identificadores de teclado e Editores de método de entrada para Windows.

[in] Flags

Tipo: UINT

Especifica como o identificador de localidade de entrada deve ser carregado. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
KLF_ACTIVATE 0x00000001	Antes de Windows 8: se o identificador de localidade de entrada especificado ainda não estiver carregado, a função carregará e ativará o identificador de localidade de entrada para o thread atual. Começando no Windows 8: se o identificador de localidade de entrada especificado ainda não estiver carregado, a função carregará e ativará o identificador de localidade de entrada para o sistema.
KLF_NOTELLSHELL 0x00000080	Antes de Windows 8: impede que um procedimento de gancho ShellProc receba um código de gancho HSHELL_LANGUAGE quando o novo identificador de localidade de entrada é carregado. Esse valor normalmente é usado quando um aplicativo carrega vários identificadores de localidade de entrada um após o outro. Aplicar esse valor a todos, exceto ao último identificador de localidade de entrada, atrasa o processamento do shell até que todos os identificadores de localidade de entrada tenham sido adicionados. A partir de Windows 8: nesse cenário, o último identificador de localidade de entrada é definido para todo o sistema.
KLF_REORDER 0x00000008	Antes de Windows 8: move o identificador de localidade de entrada especificado para o cabeçalho da lista de identificadores de localidade de entrada, tornando esse identificador de localidade o identificador de localidade ativo para o thread atual. Esse valor reordena a lista de identificadores de localidade de entrada mesmo que KLF_ACTIVATE não seja fornecido. Começando no Windows 8: move o identificador de localidade de entrada especificado para o cabeçalho da lista de identificadores de localidade de entrada, tornando esse identificador de localidade o identificador de localidade ativo para o sistema. Esse valor reordena a lista de identificadores de localidade de entrada mesmo que KLF_ACTIVATE não seja fornecido.
KLF_REPLACELANG 0x00000010	Se o novo identificador de localidade de entrada tiver o mesmo identificador de idioma que um identificador de localidade de entrada atual, o novo identificador de localidade de entrada substituirá o atual como o identificador de localidade de entrada para esse idioma. Se esse valor não for fornecido e os identificadores de localidade de entrada tiverem os mesmos identificadores de idioma, o identificador de localidade de entrada atual não será substituído e a função retornará NULL.
KLF_SUBSTITUTE_OK 0x00000002	Substitui o identificador de localidade de entrada especificado por outra localidade preferida pelo usuário. O sistema começa com esse sinalizador definido e é recomendável que seu aplicativo sempre use esse sinalizador. A substituição ocorrerá somente se a chave do Registro HKEY_CURRENT_USER\Keyboard Layout\Substitutes definir explicitamente uma localidade de substituição. Por exemplo, se a chave incluir o nome do valor "00000409" com o valor "00010409", carregar o layout dos EUA ("00000409") fará com que o layout do United States-Dvorak ("00010409") seja carregado. O sistema usa KLF_SUBSTITUTE_OK ao inicializar e é recomendável que todos os aplicativos usem esse valor ao carregar identificadores de localidade de entrada para garantir que a preferência do usuário esteja selecionada.
KLF_SETFORPROCESS 0x00000100	Antes de Windows 8: esse sinalizador é válido somente com KLF_ACTIVATE. Ativa o identificador de localidade de entrada especificado para todo o processo e envia a mensagem WM_INPUTLANGCHANGE para a janela Foco ou Ativo do thread atual. Normalmente, LoadKeyboardLayout ativa um identificador de localidade de entrada somente para o thread atual. Começando no Windows 8: esse sinalizador não é usado. LoadKeyboardLayout sempre ativa um identificador de localidade de entrada para todo o sistema se o processo atual possuir a janela com foco no teclado.
KLF_UNLOADPREVIOUS	Este sinalizador não tem suporte. Em vez disso, use a função UnloadKeyboardLayout .

Retornar valor

Tipo: HKL

Se a função for bem-sucedida, o valor retornado será o identificador de localidade de entrada correspondente ao nome especificado em pwszKLID. Se nenhuma localidade correspondente estiver disponível, o valor retornado será o idioma padrão do sistema.

Se a função falhar, o valor retornado será NULL. Isso poderá ocorrer se a biblioteca de layout for carregada do diretório do aplicativo.

Para obter informações de erro estendidas, chame GetLastError.

Comentários

O identificador de localidade de entrada é um conceito mais amplo do que um layout de teclado, pois também pode abranger um conversor de fala em texto, um método de entrada Editor (IME) ou qualquer outra forma de entrada.

Um aplicativo pode e normalmente carregará o IME ou o identificador de localidade de entrada padrão para um idioma e pode fazer isso especificando apenas uma versão de cadeia de caracteres do identificador de idioma. Se um aplicativo quiser carregar uma localidade ou IME específica, ele deverá ler o registro para determinar o identificador de local de entrada específico a ser passado para LoadKeyboardLayout. Nesse caso, uma solicitação para ativar o identificador de localidade de entrada padrão para uma localidade ativará o primeiro correspondente. Um IME específico deve ser ativado usando um identificador de localidade de entrada explícito retornado de GetKeyboardLayout ou LoadKeyboardLayout.

Antes de Windows 8: essa função afeta apenas o layout do processo ou thread atual.

Começando no Windows 8: essa função afeta o layout de todo o sistema.

Observação

O cabeçalho winuser.h define LoadKeyboardLayout como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

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