{"id":4343,"date":"2013-05-16T07:00:00","date_gmt":"2013-05-16T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2013\/05\/16\/untangling-the-confusingly-named-wm_updateuistate-and-wm_changeuistate-messages\/"},"modified":"2013-05-16T07:00:00","modified_gmt":"2013-05-16T07:00:00","slug":"untangling-the-confusingly-named-wm_updateuistate-and-wm_changeuistate-messages","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20130516-00\/?p=4343","title":{"rendered":"Untangling the confusingly-named WM_UPDATEUISTATE and WM_CHANGEUISTATE messages"},"content":{"rendered":"

I always get confused by the WM_UPDATE­UI­STATE<\/code> and WM_CHANGE­UI­STATE<\/code> messages, and I have to go figure them out each time I need to mess with them. So this time, I’m going to write it down so I don’t forget. Because the act of writing it down helps me to remember.<\/p>\n

It’s like in school, where the teacher says, “This is a closed-book, closed-notes exam, but you are allowed to bring one piece of standard 8½″×11″ paper with you, on which you can write anything you like. No funny business.” You work really hard to create the ultimate sheet of paper to bring to the exam, and then it turns out that during the exam, you barely refer to it at all. Because the act of deciding what to put on the cheat sheet made you remember the material. <\/p>\n

Part of the problem with the messages WM_UPDATE­UI­STATE<\/code> and WM_CHANGE­UI­STATE<\/code> is their confusing names, because to most people update<\/i> and change<\/i> are basically the same concept. The difference is the direction the message travels. Before we look at that, let’s look at the mysterious WPARAM<\/code>. <\/p>\n

The WPARAM<\/code> specifies what action you want to perform (initialize, set, or clear) and the target of the action (focus, accelerators, or both). <\/p>\n\n\n\n\n\n
Action<\/th>\nMeaning<\/th>\n<\/tr>\n
UIS_SET<\/code><\/td>\nSet the flag (hide the indicator).<\/td>\n<\/tr>\n
UIS_CLEAR<\/code><\/td>\nClear the flag (show the indicator).<\/td>\n<\/tr>\n
UIS_INITIALIZE<\/code><\/td>\nSet or clear the flag based on whether the last input event was mouse (set) or keyboard (clear).<\/td>\n<\/tr>\n<\/table>\n

Setting a flag hides the corresponding indicator. For example, if you have a UIS_SET<\/code> for UISF_HIDE­FOCUS<\/code>, that means that you want to hide focus indicators. <\/p>\n

Clearing a flag shows the corresponding indicator. For example, if you have a UIS_CLEAR<\/code> for UISF_HIDE­FOCUS<\/code>, that means that you want to show focus indicators. <\/p>\n

Yes, it’s a bit of a double-negative situation. <\/p>\n

Each window has its own internal state that remembers which indicators have been hidden for that window. You can query this state by sending the window a WM_QUERY­UI­STATE<\/code> message. <\/p>\n

The WM_UPDATE­UI­STATE<\/code> message travels down the tree: When a window receives the WM_UPDATE­UI­STATE<\/code> message, it updates its state according to the WPARAM<\/code> and then forwards the message to its children. Therefore, if you want to change the state for an entire window tree, you can send the WM_UPDATE­UI­STATE<\/code> message to the top-level window, and the message will be delivered to that window and all its children. <\/p>\n

It’s called update<\/i> because it says, “Okay, listen up everybody, this is what we’re going to do.” <\/p>\n

The WM_CHANGE­UI­STATE<\/code> message is more like a change request<\/i>. It travels up the tree: When a window receives the message, it sees if the state being requested matches the window’s current state. If so, then processing stops since there is nothing to change. Otherwise, the window forwards the message to its parent. The idea here is to push the change request up the tree until it finds the top-level window. <\/p>\n

If a top-level window receives a WM_CHANGE­UI­STATE<\/code> message for a state change that actually changes something, it turns around and sends itself a WM_UPDATE­UI­STATE<\/code> message, which as we saw before, tells the entire window tree to set its indicator state to the value specified. <\/p>\n

Okay, let’s draw a picture. Suppose we have a top-level window with two children, and suppose that everybody starts out with all indicators hidden. <\/p>\n\n\n
\n\n\n\n\n\n
 <\/td>\n <\/td>\n <\/td>\n <\/td>\n <\/td>\n <\/td>\n<\/tr>\n
 <\/td>\n A<\/font>
hideFocus=1
hideAccel=1<\/td>\n		 <\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n <\/td>\n <\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n <\/td>\n<\/tr>\n
B<\/font>
hideFocus=1
hideAccel=1<\/td>\n		 <\/td>\n C<\/font>
hideFocus=1
hideAccel=1<\/td>\n<\/tr>\n<\/table>\n

Window B decides that it wants to show accelerators, say because the user tapped the Alt<\/kbd> key. It sends itself a WM_CHANGE­UI­STATE<\/code> message with a wParam<\/code> of MAKEWPARAM(UIS_CLEAR, UISF_HIDE­ACCEL)<\/code>. <\/p>\n

The WM_CHANGE­UI­STATE<\/code> message handler for Window B sees that the UISF_HIDE­ACCEL<\/code> flag is set, so the clear<\/i> action is meaningful. It forwards the request to its parent, Window A. <\/p>\n

The WM_CHANGE­UI­STATE<\/code> message handler for Window A also sees that the UISF_HIDE­ACCEL<\/code> flag is set, so the clear<\/i> action is meaningful. Since it has no parent, Window A converts the WM_CHANGE­UI­STATE<\/code> message to a WM_UPDATE­UI­STATE<\/code> message and sends it to itself. <\/p>\n

The WM_UPDATE­UI­STATE<\/code> message handler for Window A sees that it is being told to clear the UISF_HIDE­ACCEL<\/code> flag, so it clears the flag and then forwards the mesage to both its children. <\/p>\n

Each of the child windows B and C receive the WM_UPDATE­UI­STATE<\/code> message and see that they are also being told to clear the UISF_HIDE­ACCEL<\/code> flag, so they do so. Those windows have no children of their own, so message processing stops. By this mechanism, Window B has managed to convince all the other windows in the hierarchy to clear the UISF_HIDE­ACCEL<\/code> flag. <\/p>\n\n\n
\n\n\n\n\n\n
 <\/td>\n <\/td>\n <\/td>\n <\/td>\n <\/td>\n <\/td>\n<\/tr>\n
 <\/td>\n A<\/font>
hideFocus=1
hideAccel=0<\/td>\n		 <\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n <\/td>\n <\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n <\/td>\n<\/tr>\n
B<\/font>
hideFocus=1
hideAccel=0<\/td>\n		 <\/td>\n C<\/font>
hideFocus=1
hideAccel=0<\/td>\n<\/tr>\n<\/table>\n

Now, suppose that Window C also decides to clear the accelerator indicator. It does the same thing as Window B and sends itself a WM_CHANGE­UI­STATE<\/code> message with a wParam<\/code> of MAKEWPARAM(UIS_CLEAR, UISF_HIDE­ACCEL)<\/code>. This time, the WM_CHANGE­UI­STATE<\/code> message handler for Window C sees that the UISF_HIDE­ACCEL<\/code> flag is already clear, so the clear<\/i> action is redundant. Message processing stops. <\/p>\n

These two examples show the flow of the UI state change messages. When somebody wants to suggest a change to the UI state, they send themselves a WM_CHANGE­UI­STATE<\/code> message with a description of what they want to change. The above algorithm then kicks in to decide whether the change is meaningful, and if so, it notifies all the other windows in the hierarchy about the new state. <\/p>\n

Next time, we’ll look at how this whole indicator state thing gets off the ground. <\/p>\n<\/tr>\n<\/table>\n<\/tr>\n<\/table>\n","protected":false},"excerpt":{"rendered":"

I always get confused by the WM_UPDATE­UI­STATE and WM_CHANGE­UI­STATE messages, and I have to go figure them out each time I need to mess with them. So this time, I’m going to write it down so I don’t forget. Because the act of writing it down helps me to remember. It’s like in school, where […]<\/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],"class_list":["post-4343","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"

I always get confused by the WM_UPDATE­UI­STATE and WM_CHANGE­UI­STATE messages, and I have to go figure them out each time I need to mess with them. So this time, I’m going to write it down so I don’t forget. Because the act of writing it down helps me to remember. It’s like in school, where […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/4343","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=4343"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/4343\/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=4343"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=4343"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=4343"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}