TranslateMessage function
Translates virtual-key messages into character messages. The character messages are posted to the calling thread's message queue, to be read the next time the thread calls the GetMessage or PeekMessage function.
Syntax
BOOL WINAPI TranslateMessage( __in const MSG *lpMsg );
Parameters
- lpMsg [in]
-
Type: const MSG*
A pointer to an MSG structure that contains message information retrieved from the calling thread's message queue by using the GetMessage or PeekMessage function.
Return value
Type: BOOL
If the message is translated (that is, a character message is posted to the thread's message queue), the return value is nonzero.
If the message is WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUP, the return value is nonzero, regardless of the translation.
If the message is not translated (that is, a character message is not posted to the thread's message queue), the return value is zero.
Remarks
The TranslateMessage function does not modify the message pointed to by the lpMsg parameter.
WM_KEYDOWN and WM_KEYUP combinations produce a WM_CHAR or WM_DEADCHAR message. WM_SYSKEYDOWN and WM_SYSKEYUP combinations produce a WM_SYSCHAR or WM_SYSDEADCHAR message.
TranslateMessage produces WM_CHAR messages only for keys that are mapped to ASCII characters by the keyboard driver.
If applications process virtual-key messages for some other purpose, they should not call TranslateMessage. For instance, an application should not call TranslateMessage if the TranslateAccelerator function returns a nonzero value. Note that the application is responsible for retrieving and dispatching input messages to the dialog box. Most applications use the main message loop for this. However, to permit the user to move to and to select controls by using the keyboard, the application must call IsDialogMessage. For more information, see Dialog Box Keyboard Interface.
Examples
For an example, see Creating a Message Loop.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- Reference
- GetMessage
- IsDialogMessage
- PeekMessage
- TranslateAccelerator
- WM_CHAR
- WM_DEADCHAR
- WM_KEYDOWN
- WM_KEYUP
- WM_SYSCHAR
- WM_SYSDEADCHAR
- WM_SYSKEYDOWN
- WM_SYSKEYUP
- Conceptual
- Messages and Message Queues
Send comments about this topic to Microsoft
Build date: 9/11/2011
What's wrong with TranslateMessage? Two things:
- It probably shouldn't be in the message loop. Different windows do different things with character and keystroke messages. Performance is not an issue here nowadays. Having TranslateMessage in the message loop has resulted in awful things such as IsDialogMessage and TranslateAccelerator calls for every message that goes through the loop.
-
More importantly though, TranslateMessage really should return TRUE if the keystroke message generates characters. It should return FALSE in every other situation. Unfortunately, TranslateMessage currently returns TRUE for WM_*KEYDOWN messages, even if no characters are generated by the keystroke (think F2 or Ctrl or up-arrow or Ctrl+Shift+X). This means that application developers have no way of knowing if the key can be safely used as a shortcut key, or should be ignored because a WM_CHAR or similar is on its way to insert into the current focus.
This in turn means that shortcut keys are typically processed (with TranslateAccelerator or a homegrown variety thereof) before TranslateMessage - and some characters are now inaccessible on some keyboard layouts.
The typical workaround is to add a hack for Ctrl+Alt (AltGr). Yuck. And that doesn't solve other supported combinations such as Ctrl+Shift.
So what's the answer to these problems? TranslateMessageEx?
http://keyman.typepad.com/keyman_weblog/2008/06/whats-wrong-wit.htmlDoesn't Even work sometimes, and i use it exactly as its written.
