
A hot key control is a window that enables the user to enter a combination of keystrokes to be used as a hot key. A hot key is a key combination that the user can press to perform an action quickly. For example, a user can create a hot key that activates a given window and brings it to the top of the z-order. The hot key control displays the user's choices and ensures that the user selects a valid key combination.
When the user enters a key combination to be used as a hot key, the names of the keys appear in the hot key control. A key combination can consist of a modifier key (such as CTRL, ALT, or SHIFT) and an accompanying key (such as a character key, an arrow key, a function key, and so on).
After the user has chosen a key combination, the application retrieves the key combination from the hot key control and uses it to set up a hot key in the system. The information retrieved from the hot key control includes a flag indicating the modifier key and the virtual key code of the accompanying key.
The application can use the information provided by a hot key control to set up a global hot key or a thread-specific hot key. A global hot key is associated with a particular window; it allows the user to activate the window from any part of the system. An application sets a global hot key by using the WM_SETHOTKEY message. Whenever the user presses a global hot key, the window specified in WM_SETHOTKEY receives a WM_SYSCOMMAND message that specifies the SC_HOTKEY value. This message activates the window that receives it. The hot key remains valid until the application that called WM_SETHOTKEY exits.
A thread-specific hot key generates a WM_HOTKEY message that is posted to the beginning of a particular thread so that it is removed by the next iteration of the message loop. An application sets a thread-specific hot key by using the RegisterHotKey function.
You create a hot key control by using the CreateWindowEx function, specifying the HOTKEY_CLASS window class. When the function returns a handle to the hot key control, an application typically sets some rules about invalid hot key combinations and may provide a default key combination. If an application does not set any rules, the user can choose any key or key combination as a hot key. Most applications, however, do not allow the user to use a common key (for example, the letter A) as a hot key.
The following function creates a hot key control, uses the HKM_SETRULES and HKM_SETHOTKEY messages to initialize it, and returns a handle to the control. This hot key control does not allow the user to choose a hot key that is a single unmodified key, nor does it permit the user to choose only SHIFT and a key. (These rules effectively prevent the user from choosing a hot key that might be entered accidentally while typing text.)
// InitializeHotkey - creates a hot key control and sets rules
// and default settings for it.
// Returns the handle of the hot key control.
// hwndDlg - handle of the parent window (dialog box).
//
// Global variable
// g_hinst - handle of the application instance.
extern HINSTANCE g_hinst;
HWND WINAPI InitializeHotkey(HWND hwndDlg)
{
// Ensure that the common control DLL is loaded.
InitCommonControls();
hwndHot = CreateWindowEx(
0, // no extended styles
HOTKEY_CLASS, // class name
"", // no title (caption)
WS_CHILD | WS_VISIBLE, // style
10, 10, // position
200, 20, // size
hwndDlg, // parent window
NULL, // uses class menu
g_hinst, // instance
NULL // no WM_CREATE parameter
);
SetFocus(hwndHot);
// Set rules for invalid key combinations. If the user
// does not supply a modifier key, use ALT as a modifier.
// If the user supplies SHIFT as a modifier key, use
// SHIFT + ALT instead.
SendMessage(hwndHot, HKM_SETRULES,
(WPARAM) HKCOMB_NONE | HKCOMB_S, // invalid key combinations
MAKELPARAM(HOTKEYF_ALT, 0)); // add ALT to invalid entries
// Set CTRL + ALT + A as the default hot key for this window.
// 0x41 is the virtual key code for 'A'.
SendMessage(hwndHot, HKM_SETHOTKEY,
MAKEWORD(0x41, HOTKEYF_CONTROL | HOTKEYF_ALT), 0);
return hwndHot;
}
After creating a hot key control, an application interacts with it by using three messages: HKM_SETRULES, HKM_SETHOTKEY, and HKM_GETHOTKEY.
An application can send the HKM_SETRULES message to specify a set of CTRL, ALT, and SHIFT key combinations that are considered invalid hot keys. If the application specifies an invalid key combination, it should also specify a default modifier combination to use when the user selects the invalid combination. When the user enters the invalid combination, the system performs a logical OR operation on the invalid combination and the default combination. The result is considered a valid combination; it is converted to a string and displayed in the control.
The HKM_SETHOTKEY message allows an application to set the hot key combination for a hot key control. This message is also typically used when the hot key control is created.
Applications use the HKM_GETHOTKEY message to retrieve the virtual key code and modifier flags of the hot key chosen by the user.
After the user has chosen a hot key, an application should retrieve it from the hot key control by using the HKM_GETHOTKEY message. This message retrieves a 16-bit value that contains the virtual key code and modifier keys describing the hot key.
The following function retrieves a key combination from a hot key control and then uses the WM_SETHOTKEY message to set a global hot key. Note that you cannot set a global hot key for a window that has the WS_CHILD window style.
// ProcessHotkey - retrieves the hot key from the hot key control and
// sets it as the hot key for the application's main window.
// Returns TRUE if successful, or FALSE otherwise.
// hwndHot - handle of the hot key control.
// hwndMain - handle of the main window.
BOOL WINAPI ProcessHotkey(HWND hwndHot, HWND hwndMain)
{
WORD wHotkey;
UINT iSetResult;
// Retrieve the hot key (virtual key code and modifiers).
wHotkey = SendMessage(hwndHot, HKM_GETHOTKEY, 0, 0);
// Use the result as wParam for WM_SETHOTKEY.
iSetResult = SendMessage(hwndMain, WM_SETHOTKEY, wHotkey, 0);
switch (iSetResult)
{
case 2: // WM_SETHOTKEY succeeded.
MessageBox(NULL, "Hot key previously assigned",
"Okay", MB_OK);
return TRUE;
case 1: // WM_SETHOTKEY succeeded.
return TRUE;
case 0:
MessageBox(NULL, "Invalid window for hot key",
"Error", MB_OK);
return FALSE;
case -1:
MessageBox(NULL, "Invalid hot key",
"Error", MB_OK);
return FALSE;
default:
MessageBox(NULL, "Unknown error", "Error", MB_OK);
return FALSE;
}
}
This section describes the window messages handled by the window procedure for the predefined HOTKEY_CLASS window class used with hot key controls.
| Message | Processing performed |
| WM_CHAR | Retrieves the virtual key code. |
| WM_CREATE | Initializes the hot key control, clears any hot key rules, and uses the system font. |
| WM_ERASEBKGND | Hides the caret, calls the DefWindowProc function, and shows the caret again. |
| WM_GETDLGCODE | Returns a combination of the DLGC_WANTCHARS and DLGC_WANTARROWS values. |
| WM_GETFONT | Retrieves the font. |
| WM_KEYDOWN | Calls the DefWindowProc function if the key is ENTER, TAB, SPACE BAR, DEL, ESC, or BACKSPACE. If the key is SHIFT, CTRL, or ALT, it checks whether the combination is valid and, if it is, sets the hot key using the combination. All other keys are set as hot keys without their validity being checked first. |
| WM_KEYUP | Retrieves the virtual key code. |
| WM_KILLFOCUS | Destroys the caret. |
| WM_LBUTTONDOWN | Sets the focus to the window. |
| WM_NCCREATE | Sets the WS_EX_CLIENTEDGE window style. |
| WM_PAINT | Paints the hot key control. |
| WM_SETFOCUS | Creates and shows the caret. |
| WM_SETFONT | Sets the font. |
| WM_SYSCHAR | Retrieves the virtual key code. |
| WM_SYSKEYDOWN | Calls the DefWindowProc function if the key is ENTER, TAB, SPACE BAR, DEL, ESC, or BACKSPACE. If the key is SHIFT, CTRL, or ALT, it checks whether the combination is valid and, if it is, sets the hot key using the combination. All other keys are set as hot keys without their validity being checked first. |
| WM_SYSKEYUP | Retrieves the virtual key code. |
This section contains information about the following programming elements used with hot key controls.
| HKM_GETHOTKEY |
| HKM_SETHOTKEY |
| HKM_SETRULES |
The following messages are associated with hot key controls.
HKM_GETHOTKEY
wParam = 0;
lParam = 0;
Retrieves the virtual key code and modifier flags of a hot key from a hot key control.
| HOTKEYF_ALT | ALT key |
| HOTKEYF_CONTROL | CTRL key |
| HOTKEYF_EXT | Extended key |
| HOTKEYF_SHIFT | SHIFT key |
The 16-bit value returned by this message can be used as the wParam parameter in the WM_SETHOTKEY message.
HKM_SETHOTKEY
wParam = MAKEWORD(bVKHotKey, bfMods);
lParam = 0;
Sets the hot key combination for a hot key control.
See also WM_GETHOTKEY
HKM_SETRULES
wParam = (WPARAM) fwCombInv;
lParam = MAKELPARAM(fwModInv, 0);
Defines the invalid combinations and the default modifier combination for a hot key control.
| HKCOMB_A | ALT |
| HKCOMB_C | CTRL |
| HKCOMB_CA | CTRL+ALT |
| HKCOMB_NONE | Unmodified keys |
| HKCOMB_S | SHIFT |
| HKCOMB_SA | SHIFT+ALT |
| HKCOMB_SC | SHIFT+CTRL |
| HKCOMB_SCA | SHIFT+CTRL+ALT |
When a user enters an invalid key combination, as defined by flags specified in fwCombInv, the system uses the bitwise-OR operator to combine the keys entered by the user with the flags specified in fwModInv. The resulting key combination is converted into a string and then displayed in the hot key control.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.