The LoadKeyboardLayout function loads a new keyboard layout into the system. Several keyboard layouts can be loaded at a time, but only one per process is active at a time. Loading multiple keyboard layouts makes it possible to rapidly switch between layouts.
HKL LoadKeyboardLayout(
LPCTSTR pwszKLID, // name of layout to load
UINT Flags // keyboard layout flags
);
| Value | Meaning |
|---|---|
| KLF_ACTIVATE | If the specified layout is not already loaded, the function loads and activates the layout for the current thread. |
| KLF_NOTELLSHELL | Prevents a ShellProc hook procedure from receiving an HSHELL_LANGUAGE hook code when the new layout is loaded. This value is typically used when an application loads multiple layouts one after another. Applying this value to all but the last layout delays the shell's processing until all layouts have been added. |
| KLF_REORDER | Moves the specified layout to the head of the keyboard layouts list, making that layout the active layout for the current thread. This value reorders the keyboard layouts list even if KLF_ACTIVATE is not provided. |
| KLF_REPLACELANG | Windows NT 4.0, Windows 95, and later: If the new layout has the same language identifier as a current layout, the new layout replaces the current one as the layout for that language. If this value is not provided and the layouts have the same language identifiers, the current layout is not replaced and the function returns NULL. |
| KLF_SUBSTITUTE_OK | Substitutes the specified keyboard layout with another layout preferred by the user. The system starts with this flag set, and it is recommended that your application always use this flag. The substitution occurs only if the registry key HKEY_CURRENT_USER\Keyboard Layout\Substitutes explicitly defines a substitution layout. For example, if the key includes the value name "00000409" with value "00010409", loading the U.S. English layout ("00000409") causes the Dvorak U.S. English layout ("00010409") to be loaded instead. The system uses KLF_SUBSTITUTE_OK when booting, and it is recommended that all applications use this value when loading layouts to ensure that the user's preference is selected. |
| KLF_SETFORPROCESS | Windows NT 5.0 and later:: This flag is valid only with KLF_ACTIVATE. Activates the specified keyboard layout for the entire process and sends the WM_INPUTLANGCHANGE message to all threads in the current process. Typically, LoadKeyboardLayout activates a layout only for the current thread. |
| KLF_UNLOADPREVIOUS | Unsupported in Windows NT 5.0, Windows 95, and Windows 98: This flag is only valid with KLF_ACTIVATE. Unloads the previous layout only if loading and activating the specified layout succeeds. It is recommended that your application use the UnloadKeyboardLayout function instead. |
If the function succeeds, the return value is the keyboard layout handle to the layout matched with the requested name. If no matching keyboard layout is available, the return value is NULL. To get extended error information, call GetLastError.
An application can and will typically load the default layout or IME for a language and can do so by specifying only a string version of the language identifier. If an application wants to load a specific layout or IME, it should read the registry to determine the specific layout identifier to pass to LoadKeyboardLayout. In this case, a request to activate the default keyboard layout handle for a locale will activate the first matching one. A specific IME should be activated using an explicit keyboard layout handle returned from GetKeyboardLayout, GetKeyboardLayoutList, or LoadKeyboardLayout.
Windows 95 and Windows 98: If a layout is to be loaded with the same language as a previously loaded layout and the KLF_REPLACELANG flag is not set, the call fails. Only one loaded layout may be associated with a given language. (It is acceptable for multiple IMEs to be loaded with associations to the same language.)
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winuser.h.
Import Library: Use user32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.
Keyboard Input Overview, Keyboard Input Functions, ActivateKeyboardLayout, GetKeyboardLayoutName, MAKELANGID, UnloadKeyboardLayout