Hot Key Controls


		Contents Index Topic Contents
	Previous Topic: NMHEADER Next Topic: Hot Key Control Reference

Hot Key Controls

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.
Using Hot Key Controls

Hot Key Control Reference

Using Hot Key Controls

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.
Hot Key Control Creation

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; 
} 
Hot Key Control Messages

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.
Hot Key Control Notifications

The hot key control does not send any notification messages via the WM_NOTIFY message. It will, however, send the EN_CHANGE notification via the WM_COMMAND message when the user changes the contents of the control.
Retrieving and Setting a Hot Key

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; 
    } 
} 
Default Hot Key Message Processing

This section describes the window messages handled by the window procedure for the pre defined 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.

Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.

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.