TranslateAccelerator

Syntax

int TranslateAccelerator(hWnd,hAccTable,lpMsg)

This function processes keyboard accelerators for menu commands. The Translate-Accelerator function translates WM_KEYUP and WM_KEYDOWN messages to WM_COMMAND or WM_SYSCOMMAND messages, if there is an entry for the key in the application's accelerator table. The high-order word of the lParam parameter of the WM_COMMAND or WM_SYSCOMMAND message contains the value 1 to differentiate the message from messages sent by menus or controls.

WM_COMMAND or WM_SYSCOMMAND messages are sent directly to the window, rather than being posted to the application queue. The TranslateAccelerator function does not return until the message is processed.

Accelerator key strokes that are defined to select items from the system menu are translated into WM_SYSCOMMAND messages; all other accelerators are translated into WM_COMMAND messages.

Parameter Type/Description  

hWnd HWND Identifies the window whose messages are to be translated.  
hAccTable HANDLE Identifies an accelerator table (loaded by using the LoadAccelerators function).  
lpMsg LPMSG Points to a message retrieved by using the GetMessage or PeekMessage function. The message must be an MSG data structure and contain message information from the Windows application queue.  

Return Value

The return value specifies the outcome of the function. It is nonzero if translation occurs. Otherwise, it is zero.

Comments

When TranslateAccelerator returns nonzero (meaning that the message is translated), the application should not process the message again by using the TranslateMessage function.

Commands in accelerator tables do not have to correspond to menu items.

If the accelerator command does correspond to a menu item, the application is sent WM_INITMENU and WM_INITMENUPOPUP messages, just as if the user were trying to display the menu. However, these messages are not sent if any of the following conditions are present:

The window is disabled.

The menu item is disabled.

The command is not in the System menu and the window is minimized.

A mouse capture is in effect (for more information, see the SetCapture function, earlier in this chapter).

If the window is the active window and there is no keyboard focus (generally true if the window is minimized), then WM_SYSKEYUP and WM_SYSKEYDOWN messages are translated instead of WM_KEYUP and WM_KEYDOWN messages.

If an accelerator key stroke that corresponds to a menu item occurs when the window that owns the menu is iconic, no WM_COMMAND message is sent. However, if an accelerator key stroke that does not match any of the items on the window's menu or the System menu occurs, a WM_COMMAND message is sent, even if the window is iconic.