DwmUpdateThumbnailProperties function (dwmapi.h)

Article
08/14/2024

Updates the properties for a Desktop Window Manager (DWM) thumbnail.

Syntax

HRESULT DwmUpdateThumbnailProperties(
  [in] HTHUMBNAIL                     hThumbnailId,
  [in] const DWM_THUMBNAIL_PROPERTIES *ptnProperties
);

Parameters

[in] hThumbnailId

The handle to the DWM thumbnail to be updated. Null or invalid thumbnails, as well as thumbnails owned by other processes will result in a return value of E_INVALIDARG.

[in] ptnProperties

A pointer to a DWM_THUMBNAIL_PROPERTIES structure that contains the new thumbnail properties.

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Thumbnail relationships created by the DwmRegisterThumbnail function will not be rendered to the destination window until this function is called. Subsequent calls will update the thumbnail according to the provided properties.

Examples

The following example demonstrates how to register and display the desktop thumbnail.


HRESULT UpdateDesktop(HWND hwnd)
{
	HRESULT hr = S_OK;

	// Register the thumbnail
	SIZE size = {100,100};
	HTHUMBNAIL thumbnail = NULL;

	hr = DwmRegisterThumbnail(hwnd, FindWindow(_T("Progman"), NULL), &size, &thumbnail);
	if (SUCCEEDED(hr))
	{
		// The destination rectangle size
		RECT dest = {0,50,100,150};

		// Set the thumbnail properties for use
		DWM_THUMBNAIL_PROPERTIES dskThumbProps;
		dskThumbProps.dwFlags = DWM_TNP_RECTDESTINATION | DWM_TNP_VISIBLE | DWM_TNP_SOURCECLIENTAREAONLY;

		// Use the window frame and client area
		dskThumbProps.fSourceClientAreaOnly = FALSE;
		dskThumbProps.fVisible = TRUE;
		dskThumbProps.opacity = (255 * 70)/100;
		dskThumbProps.rcDestination = dest;

		// Display the thumbnail
		hr = DwmUpdateThumbnailProperties(thumbnail,&dskThumbProps);
		if (SUCCEEDED(hr))
		{
			// ...
		}
	}
	return hr;	
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	dwmapi.h
Library	Dwmapi.lib
DLL	Dwmapi.dll

Share via