{"id":103316,"date":"2020-01-10T07:00:00","date_gmt":"2020-01-10T15:00:00","guid":{"rendered":"http:\/\/devblogs.microsoft.com\/oldnewthing\/?p=103316"},"modified":"2020-01-09T18:15:26","modified_gmt":"2020-01-10T02:15:26","slug":"20200110-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20200110-00\/?p=103316","title":{"rendered":"Over-documenting TTM_RELAYEVENT and why it results in a one-second periodic timer running as long as the tooltip is visible"},"content":{"rendered":"

If you create a Windows classic Win32 tooltip control<\/a>, you get to specify whether you want the control to subclass the window with which is associated, or whether you promise to forward mouse messages with the TTM_<\/code>RELAY\u00adEVENT<\/code> message<\/a>. The tooltip control uses these mouse messages to help decide when the tooltip should be displayed and hidden.<\/p>\n

If you agree to forward the messages yourself, then you may find that the tooltip control runs a one-second periodic timer for as long as the tooltip is visible. What’s that for?<\/p>\n

The timer is there so the tooltip can detect when the mouse has left the associated window. When that happens, the tooltip hides itself because the mouse is no longer on the tooltip target.<\/p>\n

Why does it need a timer to do this?<\/p>\n

Rewind to 1994. The tooltip control is being developed, and the TTM_<\/code>RELAY\u00adEVENT<\/code> message gives the tooltip control insight into what the mouse is doing in the associated window. It uses this information to detect that the mouse has dwelled inside the tooltip target for the required amount of time, which causes the tooltip to appear. It also uses this information to detect that the mouse has moved to another part of the associated window that is not part of the tooltip target, at which point it can remove the tooltip.<\/p>\n

But there’s another case that isn’t covered by this: The tooltip needs to know when the mouse has left the tooltip target due to the mouse leaving the associated window entirely.<\/p>\n

Since mouse messages are delivered to the window under the mouse cursor,\u00b9 moving the mouse out of the associated window entirely means that the associated window has nothing to forward to the control via the TTM_<\/code>RELAY\u00adEVENT<\/code> message The only way for the tooltip to know that the mouse has left the window entirely is for it to run a timer and poll the mouse position.<\/p>\n

That’s how things were in Windows 95.<\/p>\n

The documentation for the TTM_<\/code>RELAY\u00adEVENT<\/code> message says<\/p>\n

\n

A tooltip control processes only the following messages passed to it by the TTM_<\/code>RELAY\u00adEVENT<\/b> message:<\/p>\n

    \n
  • WM_<\/code>LBUTTON\u00adDOWN<\/li>\n
  • WM_<\/code>LBUTTON\u00adUP<\/li>\n
  • WM_<\/code>MBUTTON\u00adDOWN<\/li>\n
  • WM_<\/code>MBUTTON\u00adUP<\/li>\n
  • WM_<\/code>MOUSE\u00adMOVE<\/li>\n
  • WM_<\/code>RBUTTON\u00adDOWN<\/li>\n
  • WM_<\/code>RBUTTON\u00adUP<\/li>\n<\/ul>\n

    All other messages are ignored.<\/p>\n<\/blockquote>\n

    Move forward to 1998. The Track\u00adMouse\u00adEvent<\/code> function was added. Among other things, this allows a window to be notified when the mouse leaves the window outright. Great, the tooltip control can take advantage of this so that it doesn’t need to poll the mouse to find out whether it left the window. It can just wait for the WM_<\/code>MOUSE\u00adLEAVE<\/code> message.<\/p>\n

    Except that it can’t.<\/p>\n

    Because the TTM_<\/code>RELAY\u00adEVENT<\/code> message already had documentation that said “All other messages are ignored.” Programs were written based on the fact that only the messages given in the documentation need to be forwarded to the tooltip control. If they got any other message, they “optimized” their code by not bothering to forward it to the tooltip control.<\/p>\n

    This meant that the tooltip control would never get the WM_<\/code>MOUSE\u00adLEAVE<\/code> message, since the documentation told people that the tooltip control ignored the message.<\/p>\n

    So despite the availability of an efficient and battery-friendly way of detecting whether the mouse has left a window, the tooltip control cannot use it because the documentation revealed too much information, and people came to rely on that extra information.<\/p>\n

    If the documentation had merely said, “Forward all messages between WM_<\/code>MOUSE\u00adFIRST<\/code> and WM_<\/code>MOUSE\u00adLAST<\/code> to the tooltip control,” without enumerating which mouse messages the tooltip control actually cares about, then it would have been possible to use the efficient version, because everybody would be forwarding all mouse messages, which includes the new WM_<\/code>MOUSE\u00adLEAVE<\/code> message.<\/p>\n

    So things are bad because we wrote too much documentation. The documentation described the implementation rather than the contract.<\/p>\n

    All is not lost, however.<\/p>\n

    If you set the TTF_<\/code>SUBCLASS<\/code> flag when you create a tooltip target, then you are telling the tooltip control to subclass the window in order to grab the mouse messages. In this case, you don’t need to (and shouldn’t) use the TTM_<\/code>RELAY\u00adEVENT<\/code> message. And if the tooltip control is subclassing the window, it can see all<\/i> the messages, and that includes the WM_<\/code>MOUSE\u00adLEAVE<\/code> message.<\/p>\n

    So use the TTF_<\/code>SUBCLASS<\/code> flag when you create your tooltip targets. Your tooltip will respond more promptly to the user moving out of the window, and you won’t burn up the user’s battery.<\/p>\n

    \u00b9 Assuming that mouse capture is not in effect. Tooltips do not capture the mouse, because that would prevent the user from using the mouse to do normal mouse things.<\/p>\n","protected":false},"excerpt":{"rendered":"

    Too much information leads to trouble.<\/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-103316","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"

    Too much information leads to trouble.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/103316","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=103316"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/103316\/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=103316"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=103316"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=103316"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}