RegisterForTooltipDismissNotification function (winuser.h)
Registers or unregisters windows to receive notification to dismiss their tooltip windows.
Syntax
BOOL RegisterForTooltipDismissNotification(
HWND hWnd,
TOOLTIP_DISMISS_FLAGS tdFlags
);
Parameters
hWnd
Type: HWND
The handle of the window to receive the WM_TOOLTIPDISMISS message.
tdFlags
Type: TOOLTIP_DISMISS_FLAGS
A value of the enumeration that specifies whether the function registers or unregisters the window. TDF_REGISTER to register; TDF_UNREGISTER to unregister.
Return value
TRUE if the window was successfully registered or unregistered; otherwise, FALSE. (See Remarks.)
Remarks
This function makes tooltips more accessible by letting apps and frameworks that support tooltips register and unregister to be notified by a WM_TOOLTIPDISMISS message when the system requires all showing tooltips to be dismissed.
Apps should register for this notification each time they show a tooltip and hide their tooltips in response to a WM_TOOLTIPDISMISS message. When a tooltip is hidden for some other reason, like a mouse action, the app should unregister.
System-defined triggers for tooltip dismissal include a solitary Ctrl key up or Ctrl+Shift+F10. (The set of triggers may change over time.)
The function takes either the HWND of a tooltip window or the HWND of an app window that has child tooltips.
- If a tooltip HWND itself is registered, the tooltip window is expected to register upon showing and to dismiss upon receiving a WM_TOOLTIPDISMISS message.
- If an app HWND registers on behalf of its tooltips, the app's window is expected to register upon showing tooltips and dismiss all of its tooltips upon receiving a WM_TOOLTIPDISMISS message.
Tooltip or app windows are expected to call the function to register each time tooltips are shown. Registered windows are automatically unregistered upon posting WM_TOOLTIPDISMISS.
The TDF_UNREGISTER flag is used to explicitly unregister a window when a tooltip window is dismissed by application or framework prerogative (such as moving the cursor out of the "safe zone"). If an app or framework calls RegisterForTooltipDismissNotification
with TDF_UNREGISTER after the window has been automatically unregistered, the function returns FALSE. There is no impact on future registrations.
Return values
The HWND passed into the function must be owned by the calling process; otherwise, the function returns FALSE.
When called with TDF_REGISTER and a window belonging to the calling process, the function returns TRUE if the window was successfully registered or FALSE if the window was already registered. The window is treated as registered either way.
When called with TDF_UNREGISTER and a windows belonging to the calling process, the function returns TRUE if the window is successfully unregistered, or FALSE if the windows was not currently registered. The window is treated as unregistered either way.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 11 Build 22621 |
Target Platform | Windows |
Header | winuser.h |
Library | user32.lib |
See also
Examples
// WndProc: Window procedure for a window that is the parent of one or more
// tooltip windows.
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
switch (message)
{
case WM_TOOLTIPDISMISS:
// System is asking us to dismiss tooltip window due to system hotkey.
if (hwndVisibleTooltip)
{
// Hide the tooltip window. Not necessary to unregister as window is
// automatically unregistered upon notification.
ShowWindow(hwndVisibleTooltip, SW_HIDE);
hwndVisibleTooltip = nullptr;
}
break;
case WM_NOTIFY:
{
LPNMHDR toolInfo = (LPNMHDR) lParam;
switch (toolInfo->code)
{
case TTN_SHOW:
// Notification that a tooltip is about to show. Register this
// window to receive dismiss notification when the system wants
// to dismiss tooltips (such as in response to a system hotkey).
RegisterForTooltipDismissNotification(hWnd, TDF_REGISTER);
// Remember the visible tooltip window, so we know which one to
// hide when we receive WM_TOOLTIPTISMISS.
hwndVisibleTooltip = toolInfo->hwndFrom;
break;
case TTN_POP:
// Notification that a tooltip is about to hide
if (hwndVisibleTooltip)
{
// With the tooltip hiding, we will no longer need the system
// dismiss notification, so we can unregister from it.
RegisterForTooltipDismissNotification(hWnd, TDF_UNREGISTER);
hwndVisibleTooltip = nullptr;
}
break;
default:
return DefWindowProc(hWnd, message, wParam, lParam);
}
}
break;
case WM_DESTROY:
PostQuitMessage(0);
break;
default:
return DefWindowProc(hWnd, message, wParam, lParam);
}
return 0;
}