VC++ LoadKeyboardLayout

LoadKeyboardLayout Function

The LoadKeyboardLayout function loads a new input locale identifier (formerly called the keyboard layout) into the system. Several input locale identifiers can be loaded at a time, but only one per process is active at a time. Loading multiple input locale identifiers makes it possible to rapidly switch between them.

Syntax

HKL LoadKeyboardLayout(      
    LPCTSTR pwszKLID,    UINT Flags);

Parameters

pwszKLID

[in] Pointer to the buffer that specifies the name of the input locale identifier to load. This name is a string composed of the hexadecimal value of the Language Identifier (low word) and a device identifier (high word). For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named "00000409". Variants of U.S. English layout (such as the Dvorak layout) are named "00010409", "00020409", and so on.

Flags

[in] Specifies how the input locale identifier is to be loaded. This parameter can be one of the following values.

KLF_ACTIVATE

If the specified input locale identifier is not already loaded, the function loads and activates the input locale identifier for the current thread.

KLF_NOTELLSHELL

Prevents a ShellProc hook procedure from receiving an HSHELL_LANGUAGE hook code when the new input locale identifier is loaded. This value is typically used when an application loads multiple input locale identifiers one after another. Applying this value to all but the last input locale identifier delays the shell's processing until all input locale identifiers have been added.

KLF_REORDER

Moves the specified input locale identifier to the head of the input locale identifier list, making that locale identifier the active locale identifier for the current thread. This value reorders the input locale identifier list even if KLF_ACTIVATE is not provided.

KLF_REPLACELANG

Windows 95/98/Me, Windows NT 4.0, and Windows 2000/XP: If the new input locale identifier has the same language identifier as a current input locale identifier, the new input locale identifier replaces the current one as the input locale identifier for that language. If this value is not provided and the input locale identifiers have the same language identifiers, the current input locale identifier is not replaced and the function returns NULL.

KLF_SUBSTITUTE_OK

Substitutes the specified input locale identifier with another locale 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 locale. 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 input locale identifiers to ensure that the user's preference is selected.

KLF_SETFORPROCESS

Windows 2000/XP:: This flag is valid only with KLF_ACTIVATE. Activates the specified input locale identifier for the entire process and sends the WM_INPUTLANGCHANGE message to the current thread's Focus or Active window. Typically, LoadKeyboardLayout activates an input locale identifier only for the current thread.

KLF_UNLOADPREVIOUS

This flag is unsupported. Use the UnloadKeyboardLayout function instead.

Return Value

If the function succeeds, the return value is the input locale identifier to the locale matched with the requested name. If no matching locale is available, the return value is NULL. To get extended error information, call GetLastError.

Remarks

This function only affects the layout for the current process or thread.

The input locale identifier is a broader concept than a keyboard layout, since it can also encompass a speech-to-text converter, an Input Method Editor (IME), or any other form of input.

An application can and will typically load the default input locale identifier 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 locale or IME, it should read the registry to determine the specific input locale identifier to pass to LoadKeyboardLayout. In this case, a request to activate the default input locale identifier for a locale will activate the first matching one. A specific IME should be activated using an explicit input locale identifier returned from GetKeyboardLayout or LoadKeyboardLayout.

Windows 95/98/Me: If an input locale identifier is to be loaded with the same language as a previously loaded input locale identifier and the KLF_REPLACELANG flag is not set, the call fails. Only one loaded locale may be associated with a language. (It is acceptable for multiple IMEs to be loaded with associations to the same language.)

Windows 95/98/Me: LoadKeyboardLayoutW is supported by the Microsoft Layer for Unicode (MSLU). To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.