WM_APPCOMMAND

The WM_APPCOMMAND message notifies a window that the user generated an application command event, for example, by clicking an application command button using the mouse or typing an application command key on the keyboard.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_APPCOMMAND
  WPARAM wParam,   // handle to window (DWORD)
  LPARAM lParam    // command, device, and virtual keys
);

Parameters

wParam

Handle to the window where the user clicked the button or pressed the key. This can be a child window of the window receiving the message. For more information about processing this message, see the Remarks section.

lParam

Use the following code to crack the lParam parameter.

cmd  = GET_APPCOMMAND_LPARAM(lParam);
uDevice = GET_DEVICE_LPARAM(lParam);
dwKeys = GET_KEYSTATE_LPARAM(lParam);

Where cmd indicates the application command. This parameter can be one of the following values.

Value	Meaning
APPCOMMAND_BASS_BOOST	Toggle the bass boost on and off.
APPCOMMAND_BASS_DOWN	Decrease the bass.
APPCOMMAND_BASS_UP	Increase the bass.
APPCOMMAND_BROWSER_BACKWARD	Navigate backward.
APPCOMMAND_BROWSER_FAVORITES	Open favorites.
APPCOMMAND_BROWSER_FORWARD	Navigate forward.
APPCOMMAND_BROWSER_HOME	Navigate home.
APPCOMMAND_BROWSER_REFRESH	Refresh page.
APPCOMMAND_BROWSER_SEARCH	Open search.
APPCOMMAND_BROWSER_STOP	Stop download.
APPCOMMAND_LAUNCH_APP1	Start App1.
APPCOMMAND_LAUNCH_APP2	Start App2.
APPCOMMAND_LAUNCH_MAIL	Open mail.
APPCOMMAND_MEDIA_NEXTTRACK	Go to next track.
APPCOMMAND_MEDIA_PLAY_PAUSE	Play or pause playback.
APPCOMMAND_MEDIA_PREVIOUSTRACK	Go to previous track.
APPCOMMAND_MEDIA_SELECT	Go to Media Select mode.
APPCOMMAND_MEDIA_STOP	Stop playback.
APPCOMMAND_TREBLE_DOWN	Decrease the treble.
APPCOMMAND_TREBLE_UP	Increase the treble.
APPCOMMAND_VOLUME_DOWN	Lower the volume.
APPCOMMAND_VOLUME_MUTE	Mute the volume.
APPCOMMAND_VOLUME_UP	Raise the volume.

Where uDevice indicates the input device that generated the input event. It can be one of the following values.

Value	Meaning
FAPPCOMMAND_KEY	User pressed a key..
FAPPCOMMAND_MOUSE	User clicked a mouse button.
FAPPCOMMAND_OEM	An undentified hardware source generated the event. It could be a mouse or a keyboard event.

Where dwKeys indicates whether various virtual keys are down. It can be one or more of the following values.

Value	Meaning
MK_CONTROL	The CTRL key is down.
MK_LBUTTON	The left mouse button is down.
MK_MBUTTON	The middle mouse button is down.
MK_RBUTTON	The right mouse button is down.
MK_SHIFT	The SHIFT key is down.
MK_XBUTTON1	The first X button is down.
MK_XBUTTON2	The second X button is down.

Return Values

If an application processes this message, it should return TRUE. For more information about processing the return value, see the Remarks section.

Remarks

DefWindowProc generates the WM_APPCOMMAND message when it processes the WM_XBUTTONUP or WM_NCXBUTTONUP message, or when the user types an application command key.

If a child window does not process this message and instead calls DefWindowProc, DefWindowProc will send the message to its parent window. If a top level window does not process this message and instead calls DefWindowProc, DefWindowProc will call a shell hook with the hook code equal to HSHELL_APPCOMMAND.

To get the coordinates of the cursor if the message was generated by a button click on the mouse, the application can call GetMessagePos. An application can test whether the message was generated by the mouse by checking whether lParam contains FAPPCOMMAND_MOUSE.

Unlike other windows messages, an application should return TRUE from this message if it processes it. Doing so will allow software that simulates this message on Windows systems earlier than Windows 2000 to determine whether the window procedure processed the message or called DefWindowProc to process it.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winuser.h; include Windows.h.

See Also

Mouse Input Overview, Mouse Input Messages, DefWindowProc, GET_APPCOMMAND_LPARAM, GET_DEVICE_LPARAM, GET_KEYSTATE_LPARAM, ShellProc, WM_XBUTTONUP, WM_NCXBUTTONUP