dwmSetIconicThumbnail 函数 (dwmapi.h)

设置窗口或选项卡上要用作缩略图表示形式的静态图标位图。 任务栏可以将此位图用作窗口或选项卡的缩略图切换目标。

语法

HRESULT DwmSetIconicThumbnail(
  [in] HWND    hwnd,
  [in] HBITMAP hbmp,
  [in] DWORD   dwSITFlags
);

参数

[in] hwnd

窗口或选项卡的句柄。此窗口必须属于调用进程。

[in] hbmp

位图的句柄，用于表示 hwnd 指定的窗口。

[in] dwSITFlags

缩略图的显示选项。 以下值之一：

0 (0x00000000)

提供的缩略图周围不显示任何框架。

DWM_SIT_DISPLAYFRAME (0x00000001)

在提供的缩略图周围显示一个框架。

返回值

如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

备注

应用程序通常在收到其窗口的WM_DWMSENDICONICTHUMBNAIL消息后调用 DwmSetIconicThumbnail 函数。 缩略图不应超过该消息中指定的最大 x 坐标和 y 坐标。 缩略图还必须具有 32 位颜色深度。

应用程序调用 DwmInvalidateIconicBitmaps 向桌面窗口管理器 (DWM) 指示图标缩略图和实时预览位图已过期，应刷新。 然后，DWM 会在需要时从窗口中请求新版本。 但是，如果 DWM 位图缓存已满，DWM 不会请求更新的版本。

DWM 使用位图的副本，但由于内存限制，应用程序可以随时释放此副本。 如果释放副本，则不会通知窗口，但当再次需要其缩略图时，窗口可能会收到后续 WM_DWMSENDICONICTHUMBNAIL 请求。 调用方保留原始位图的所有权，并负责在不再需要时释放它使用的资源。

示例

在调用 DwmSetIconicThumbnail 之前，应用程序必须首先调用 DwmSetWindowAttribute 函数来设置 DWMWA_FORCE_ICONIC_REPRESENTATION 和 DWMWA_HAS_ICONIC_BITMAP 属性，如以下示例所示。

            // Set DWM window attributes to provide the iconic bitmap, and 
            // to always render the thumbnail using the iconic bitmap.
            BOOL fForceIconic = TRUE;
            BOOL fHasIconicBitmap = TRUE;

            DwmSetWindowAttribute(
                hwnd,
                DWMWA_FORCE_ICONIC_REPRESENTATION,
                &fForceIconic,
                sizeof(fForceIconic));

            DwmSetWindowAttribute(
                hwnd,
                DWMWA_HAS_ICONIC_BITMAP,
                &fHasIconicBitmap,
                sizeof(fHasIconicBitmap));

接下来，应用程序调用 DwmSetIconicThumbnail 函数以响应 WM_DWMSENDICONICTHUMBNAIL 消息，如以下示例所示。

        case WM_DWMSENDICONICTHUMBNAIL:
        {    
            // This window is being asked to provide its iconic bitmap. This indicates
            // a thumbnail is being drawn.
            hbm = CreateDIB(HIWORD(lParam), LOWORD(lParam)); 
            if (hbm)
            {
                hr = DwmSetIconicThumbnail(hwnd, hbm, 0);
                DeleteObject(hbm);
            }
        }
        break;

有关完整的示例代码，请参阅 自定义图标缩略图和实时预览位图 示例。

要求

最低受支持的客户端	Windows 7 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 R2 [仅限桌面应用]
目标平台	Windows
标头	dwmapi.h
Library	Dwmapi.lib
DLL	Dwmapi.dll;Uxtheme.dll