LoadKeyboardLayout
The
implementations of LoadKeyboardLayout in Windows 95 and Windows NT are
substantially different. To accommodate these differences, this reference page
first presents the Windows 95 implementation in its entirety, followed by the
Windows NT version.
{bmc bm4.MRB} Windows 95:
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 |
|
); |
|
Parameters
pwszKLID
Points to the
buffer that specifies the name of the keyboard layout. This name is a string
composed from the hexadecimal value of the primary 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. For a list of the primary language
identifiers and secondary language identifiers that make up a language
identifier, see the MAKELANGID macro.
Flags
Specifies how
the keyboard layout is to be loaded. This parameter can be one of the following
values:
|
Value |
Meaning |
|
KLF_ACTIVATE |
If the
given layout is not already loaded, the function loads and activates the
layout for the current thread, inserting the layout at the head of the
keyboard layouts list in front of the previously active layout. If the layout
is already loaded and the KLF_REORDER value is not given, the function simply
rotates the keyboard layouts list, making the next layout the active layout. |
|
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
given 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 given. |
|
KLF_REPLACELANG |
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 given and the layouts have the same language identifiers, the current
layout is not replaced and the function returns NULL. |
|
KLF_SUBSTITUTE_OK |
Substitues
the given keyboard layout with another layout preferred by the user. 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 too. |
Return Values
If the
function succeeds, the return value is the keyboard layout handle of the layout
matched with the requested name or NULL if no matching keyboard is available.
Remarks
If a layout
is to be loaded with the same language as a previously loaded one 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.)
An
application can and will typically want to 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 one of GetKeyboardLayout,
GetKeyboardLayoutList or LoadKeyboardLayout.
See Also
{bmc bm4.MRB} Windows NT:
The LoadKeyboardLayout
function loads a keyboard layout.
HKL LoadKeyboardLayout(
|
LPCTSTR pwszKLID, |
// address of
buffer for layout name |
|
UINT Flags |
// keyboard layout
flags |
|
); |
|
Parameters
pwszKLID
Points to the
buffer that specifies the name of the keyboard layout. The name should be
derived from the hexadecimal value of the language identifier corresponding to
the layout. 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. For a list of the
primary language identifiers and sub-language identifiers that make up a
language identifier, see the MAKELANGID macro.
Flags
Specifies how
the keyboard layout is to be loaded. This parameter can be one of the following
values:
|
Value |
Meaning |
|
KLF_ACTIVATE |
The
function loads the layout if it is not already loaded, and activates it. This
value activates the layout for the entire system not just the calling thread. |
|
KLF_REORDER |
This flag
is meaningful only if the KLF_ACTIVATE flag is set and the layout is already
loaded. If these conditions are met and the KLF_REORDER bit is set, the
function removes the specified layout from its position in the system s
circular list of loaded layouts, and places it at the head of the list as the
active layout. |
|
|
If the
KLF_ACTIVATE bit is set and the layout is loaded but the KLF_REORDER bit is
not set, the function simply rotates the system s circular list of loaded
layouts. |
|
|
If the
KLF_ACTIVATE flag is set and the layout is not already loaded, it is loaded
as the active layout and inserted in the system s circular list of keyboard
layouts ahead of the previously active layout. |
|
KLF_SUBSTITUTE_OK |
The
specified layout is looked up in the user s profile (in the registry under the
key HKEY_CURRENT_USER\Keyboard Layout\Substitutes) to find a
substitution layout preferred by the user. For example, if there was a value
in this section of name 00000409 equal to 00010409 , loading the U.S.
English layout ( 00000409 ) with the KLF_SUBSTITUTE_OK flag set would cause
the Dvorak U.S. English layout ( 00010409 ) to be loaded. |
|
KLF_UNLOADPREVIOUS |
If
KLF_ACTIVATE is specified, and the layout is loaded and activated
successfully, the function unloads the previously active layout. Otherwise,
the function ignores this flag. |
Return Values
If the
function succeeds, the return value is the handle of the keyboard layout.
If the
function fails, the return value is NULL. To get extended error information,
call GetLastError.
Remarks
Several
keyboard layouts can be loaded at a time, but only one at a time is active.
Loading multiple keyboard layouts makes it possible to switch rapidly between
layouts.
See Also
ActivateKeyboardLayout, GetKeyboardLayoutName, UnloadKeyboardLayout