{"id":32093,"date":"2006-03-02T10:00:10","date_gmt":"2006-03-02T10:00:10","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2006\/03\/02\/restating-the-obvious-about-the-wm_command-message\/"},"modified":"2006-03-02T10:00:10","modified_gmt":"2006-03-02T10:00:10","slug":"restating-the-obvious-about-the-wm_command-message","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20060302-10\/?p=32093","title":{"rendered":"Restating the obvious about the WM_COMMAND message"},"content":{"rendered":"

\nI’m satisfied with the MSDN documentation for\n\nthe WM_COMMAND<\/code> message<\/a>,\nbut for the sake of mind-numbing completeness,\nI’m going to state the obvious in the hope that you,\ndear readers, can use this technique to\nfill in the obvious in other parts of MSDN.\n<\/p>\n

\nThe one-line summary of the WM_COMMAND<\/code> message\nsays,\n“The WM_COMMAND message is sent when the user selects\na command item from a menu,\nwhen a control sends a notification message to its parent window,\nor when an accelerator keystroke is translated.”\nIn a nutshell, there are three scenarios that generate a\nWM_COMMAND<\/code> message, namely the three listed above.\nYou want to think of the menu and accelerator scenarios of the\nWM_COMMAND<\/code> message as special cases of the control scenario.\n<\/p>\n

\nThe high-order word of the wParam<\/code> parameter\n“specifies the notification code if the message is from a control”.\nWhat does “control” mean here?\nRemember that you have to take things in context.\nThe WM_COMMAND<\/code> message is being presented in the\ncontext of Win32 in general, and in the context of the window manager\nin particular.\nWindows such as edit boxes, push buttons, and list boxes\nare commonly called “controls”, as are all the window classes\nin the “common controls library”.\nIn the world of the window manager, a “control” is a window\nwhose purpose is to provide some degree of interactivity\n(which, in the case of the static control, might be no interactivity at all)\nin the service of its parent window.\nThe fact that the WM_COMMAND<\/code> is used primarily\nin the context of dialog boxes further emphasizes the point\nthat the term “control” here is just a synonym for “child window”.\n<\/p>\n

\nWhat does “notification code” mean here?\nControl notification codes are arbitrary 16-bit values defined\nby the control itself.\nBy convention, they are named xxN_xxxx<\/code>, where the “N”\nstands for “notification”.\nBe careful, however, not to confuse this with notification codes\nassociated with the WM_NOTIFY<\/code> message.\nFortunately, every notification code specifies in its documentation\nwhether it arrives as a WM_COMMAND<\/code> notification or\na WM_NOTIFY<\/code> notification.\nA modern control designer is more likely to use\nWM_NOTIFY<\/code> notifications since they allow\nadditional information to be passed with the notification.\nThe WM_COMMAND<\/code> message, by comparison, passes\nonly the notification itself; the other parameters to\nthe WM_COMMAND<\/code> message are forced, as we’ll see below.\nIf WM_NOTIFY<\/code> is superior to WM_COMMAND<\/code>,\nwhy do some controls use WM_COMMAND<\/code>?\nBecause WM_NOTIFY<\/code> wasn’t available until\nWindows 95.\nControls that were written prior to Windows 95 had to\ncontent themselves with the WM_COMMAND<\/code> message.\n<\/p>\n

\n“If the message is from an accelerator, this value [the high-order\nword of the wParam<\/code> parameter] is 1.”\nRemember, we’re still in the context of the window manager,\nand particular in the context of the WM_COMMAND<\/code>\nmessage.\nThe accelerator here refers to messages generated by the call to\nTranslateAccelerator<\/code> in the message loop.\n<\/p>\n

\n“If the message is from a menu, this value is zero.”\nIf the WM_COMMAND<\/code> mesage was triggered by\nthe user selecting an item from a menu, then the high-order\nword of the wParam<\/code> is zero.\n<\/p>\n

\nThe low-order word of the wParam<\/code> parameter\n“specifies the identifier of the menu item, control, or\naccelerator.”\nThe identifier of a menu item or accelerator\nis the command code you associated\nwith it in your menu or accelerator template or (in the case of a menu item)\nwhen you manually created the menu item with a function like\nInsertMenuItem<\/code>.\n(You probably named your menu item identifiers and accelerator\nidentifiers IDM_something<\/code>.)\nThe identifier of a control is determined by the creator of the\ncontrol; recall that the\nhMenu<\/code> parameter to the CreateWindow<\/code>\nand CreateWindowEx<\/code> functions is treated as a child\nwindow identifier if you’re creating a child window.\nIt is that identifier that the control identifier.\n(You can retrieve the identifier for a control by calling the\nGetDlgCtrlID<\/code> function.)\n<\/p>\n

\nFinally, the lParam<\/code> parameter is the\n“handle to the control sending the message if the message is from a control.\nOtherwise, this parameter is NULL.”\nIf the notification is generated by a child window\n(with a notification code appropriate for that child window, obviously),\nthen that child window handle is passed as the lParam<\/code>.\nIf the notification is generated by an accelerator or a menu,\nthen the lParam<\/code> is zero.\n<\/p>\n

\nNotice that nearly all of the parameters to the\nWM_COMMAND<\/code> message are forced, once you’ve decided\nwhat notification you’re generating.\n<\/p>\n

\nIf you are generating a notification from a control,\nyou must pass the notification code in the high word of the\nwParam<\/code>, the control identifier in the low word\nof the wParam<\/code>, and the control handle as the\nlParam<\/code>.\nIn other words, once you’ve decided that the\nhwndC<\/code> window wants to send a\nCN_READY<\/code> notification, you have no choice but\nto type\n<\/p>\n

\nSendMessage(GetParent(hwndC), WM_COMMAND,\n            MAKEWPARAM(GetDlgCtrlID(hwndC), CN_READY),\n            (LPARAM)hwndC);\n<\/pre>\n
\nIn other words, all control notifications take the form\n<\/p>\n
\nSendMessage(GetParent(hwndC), WM_COMMAND,\n            MAKEWPARAM(GetDlgCtrlID(hwndC), notificationCode),\n            (LPARAM)hwndC);\n<\/pre>\n
\nwhere hwndC<\/code> is the control generating the notification\nand notificationCode<\/code> is the notification code.\nOf course, you can use PostMessage<\/code> instead of\nSendMessage<\/code> if you would rather post the notification\nrather than sending it.\n<\/p>\n
\nThe other two cases (accelerators and menus) are not cases you\nwould normally code up, since you typically let the\nTranslateAccelerator<\/code> function deal with accelerators\nand let the menu system deal with menu identifiers.\nBut if for some reason, you wanted to pretend that the user\nhad typed an accelerator or selected a menu item, you can generate\nthe notification manually by following the rules set out in the\ndocumentation.\n<\/p>\n
\n\/\/ simulate the accelerator IDM_WHATEVER\nSendMessage(hwnd, WM_COMMAND,\n            MAKEWPARAM(IDM_WHATEVER, 1),\n            0);\n<\/pre>\n
\nHere, hwnd<\/code> is the window that you want to pretend was\nthe window passed to the TranslateAccelerator<\/code> function,\nand IDM_WHATEVER<\/code> is the accelerator identifier.\n<\/p>\n
\nSimulating a menu selection is exactly the same, except that\n(according to the rules above), you set the high-order word of\nthe wParam<\/code> to zero.\n<\/p>\n
\n\/\/ simulate the menu item IDM_WHATEVER\nSendMessage(hwnd, WM_COMMAND,\n            MAKEWPARAM(IDM_WHATEVER, 0),\n            0);\n<\/pre>\n
\nHere, hwnd<\/code> is the window associated with the menu.\nA window can be associated with a menu either by being created\nwith the menu (having passed the menu handle to the\nCreateWindow<\/code> or CreateWindowEx<\/code> function\nexplicitly, or having it done implicitly by including it with the\nclass registration) or by having been passed explicitly as\nthe window parameter to a function like\nTrackPopupWindow<\/code>.\n<\/p>\n
\nOne significant difference between the accelerator\/menu case\nand the control notification case is that accelerator and menu\nidentifiers are defined by the calling application,\nwhereas control notifications are defined by the control.\n<\/p>\n
\nYou may have noticed the opportunity to “pun”\nthe control notification codes.\nIf a control defines a notification code as zero, then it will\n“look like” a menu item selection, since the high-order word\nof the wParam<\/code> in the case of a menu item selection\nis zero.\nThe button control takes advantage of this pun:\n<\/p>\n
\n#define BN_CLICKED          0\n<\/pre>\n
\nThis means that when the user clicks a button control,\nthe WM_COMMAND<\/code> message that is generated\n“smells like” a menu selection notification.\nYou probably take advantage of this in your dialog procedure\nwithout even realizing it.\n<\/p>\n
\n(The static control also takes advantage of this pun:\n<\/p>\n
\n#define STN_CLICKED         0\n<\/pre>\n
\nbut in order for the static control to generate the\nSTN_CLICKED<\/code> notification,\nyou have to set the SS_NOTIFY<\/code> style.)\n<\/p>\n
\nI stated at the start that the accelerator and menu scenarios\nare just special cases of the control scenario.\nIf you take the pieces of the WM_COMMAND<\/code> message\napart, you’ll see that they fall into two categories:\n<\/p>\n