{"id":36393,"date":"2005-02-22T07:00:00","date_gmt":"2005-02-22T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2005\/02\/22\/modality-part-3-the-wm_quit-message\/"},"modified":"2005-02-22T07:00:00","modified_gmt":"2005-02-22T07:00:00","slug":"modality-part-3-the-wm_quit-message","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20050222-00\/?p=36393","title":{"rendered":"Modality, part 3: The WM_QUIT message"},"content":{"rendered":"

\nAfter\n\nour two quick introductions<\/a>\n\nto modality<\/a>,\nwe’re now going to dig in a little deeper.\n<\/p>\n

\nThe trick with modality is that when you call a modal function,\nthe responsibility of message dispatch is handled by that function\nrather than by your main program. Consequently, if you have\ncustomized your main program’s message pump, those customizations\nare lost once you lose control to a modal loop.\n<\/p>\n

\nThe other important thing about modality is that a\n\nWM_QUIT<\/code> message<\/a> always breaks the modal loop.\nRemember this in your own modal loops! If ever\nyou call\n\nthe PeekMessage<\/code> function<\/a>\nor\n\nThe [typo fixed 10:30am] GetMessage<\/code> function<\/a> and get\na WM_QUIT<\/code>\nmessage, you must not only exit your modal loop, but\nyou must also re-generate the WM_QUIT<\/code> message\n(via\n\nthe PostQuitMessage<\/code> message<\/a>)\nso the next outer layer will see the WM_QUIT<\/code> message\nand do its cleanup as well. If you fail to propagate\nthe message, the next outer layer will not know that it\nneeds to quit, and the program will seem to “get stuck”\nin its shutdown code, forcing the user to\nterminate the process the hard way.\n<\/p>\n

\nIn a later series, we’ll see how this convention surrounding\nthe WM_QUIT<\/code> message is useful.\nBut for now, here’s\nthe basic idea of how your modal loops should re-post\nthe quit message to the next outer layer.\n<\/p>\n

\nBOOL WaitForSomething(void)\n{\n  MSG msg;\n  BOOL fResult = TRUE; \/\/ assume it worked\n  while (!SomethingFinished()) {\n    if (GetMessage(&msg, NULL, 0, 0)) {\n      TranslateMessage(&msg);\n      DispatchMessage(&msg);\n    } else {\n      \/\/ We received a WM_QUIT message; bail out!\n      CancelSomething();\n      \/\/ Re-post the message that we retrieved\n      PostQuitMessage(msg.wParam);\n      fResult = FALSE; \/\/ quit before something finished\n      break;\n    }\n  }\n  return fResult;\n}\n<\/pre>\n
\nSuppose your program starts some operation and then calls\nWaitForSomething()<\/code>.\nWhile waiting for something to finish, some other part of your\nprogram decides that it’s time to exit.\n(Perhaps the user clicked on a “Quit” button.)\nThat other part of the program will call\nPostQuitMessage(wParam)<\/code>\nto indicate that the message loop should terminate.\n<\/p>\n
\nThe posted quit message will first be retrieved by the\nGetMessage<\/code> in the WaitForSomething<\/code> function.\nThe GetMessage<\/code> function returns FALSE<\/code> if\nthe retrieved message is a WM_QUIT<\/code> message.\nIn that case, the “else” branch of the conditional is taken, which\ncancels the “Something” operation in progress, then posts\nthe quit message back into the message queue for the next\nouter message loop to handle.\n<\/p>\n
\nWhen WaitForSomething<\/code> returns, control presumably will fall\nback out into the program’s main message pump.  The main message\npump will then retrieve the WM_QUIT<\/code> message and do its\nexit processing before finally exiting the program.\n<\/p>\n
\nAnd if there were additional layers of modality between\nWaitForSomething<\/code> and the program’s main message pump,\neach of those layers would retrieve the WM_QUIT<\/code> message,\ndo their cleanup, and then re-post the WM_QUIT<\/code> message\n(again, via PostQuitMessage<\/code>) before exiting the loop.\n<\/p>\n
\nIn this manner, the WM_QUIT<\/code> message gets handed from modal\nloop to modal loop, until it reaches the outermost loop, which\nterminates the program.\n<\/p>\n
\n“But wait,” I hear you say.  “Why do I have to do all this\nfancy WM_QUIT<\/code> footwork?  I could just have a private little\nglobal variable named something like g_fQuitting<\/code>.  When\nI want the program to quit, I just set this variable, and all\nof my modal loops check this variable and exit prematurely if it\nis set.  Something like this:\n<\/p>\n
\nBOOL MyWaitForSomething(void) \/\/ code in italics is wrong\n{\n  MSG msg;\n  while (!SomethingFinished()) {\n    if (g_fQuitting) {\n    CancelSomething();\n      return FALSE;\n    }\n    if (GetMessage(&msg, NULL, 0, 0)) {\n      TranslateMessage(&msg);\n      DispatchMessage(&msg);\n    }\n  }\n  return TRUE;\n}<\/i>\n<\/pre>\n
\nAnd so I can solve the problem of the nested quit without needing\nto do all this PostQuitMessage<\/code> rigamarole.”\n<\/p>\n
\nAnd you’d be right, if you controlled every single modal loop in\nyour program.\n<\/p>\n
\nBut you don’t.\n<\/p>\n
\nFor example, when you call\n\nthe DialogBox<\/code> function<\/a>,\nthe dialog box code\nruns its own private modal loop to do the dialog box UI until\nyou get around to calling\n\nthe EndDialog<\/code> function<\/a>.  And whenever the user\nclicks on any of your menus, Windows runs its own private\nmodal loop to do the menu UI.  Indeed, even the resizing of\nyour application’s window is handled by a Windows modal loop.\n<\/p>\n
\nWindows, of course, has no knowledge of your little\ng_fQuitting<\/code> variable, so it has no idea that you want\nto quit.  It is the WM_QUIT<\/code> message that serves this\npurpose of co-ordinating the intention to quit among separate\nparts of the system.\n<\/p>\n
\nNotice that this convention regarding the WM_QUIT<\/code>\nmessage cuts both ways.  You can use this convention to cause\nmodal loops to exit (we’ll see more of this later), but it also\nobliges you to respect this convention so that\nother<\/strong> components (including the window manager itself)\ncan get your modal loops to exit.<\/p>\n","protected":false},"excerpt":{"rendered":"
After our two quick introductions to modality, we’re now going to dig in a little deeper. The trick with modality is that when you call a modal function, the responsibility of message dispatch is handled by that function rather than by your main program. Consequently, if you have customized your main program’s message pump, those […]<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25,143],"class_list":["post-36393","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code","tag-modality"],"acf":[],"blog_post_summary":"
After our two quick introductions to modality, we’re now going to dig in a little deeper. The trick with modality is that when you call a modal function, the responsibility of message dispatch is handled by that function rather than by your main program. Consequently, if you have customized your main program’s message pump, those […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/36393","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=36393"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/36393\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=36393"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=36393"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=36393"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}