DwmSetIconicLivePreviewBitmap 函数 (dwmapi.h)

  • 项目

设置静态图标位图以显示实时预览 (也称为窗口或选项卡的速览预览) 。任务栏可以使用此位图显示窗口或选项卡的全尺寸预览。

语法

HRESULT DwmSetIconicLivePreviewBitmap(
                 HWND    hwnd,
                 HBITMAP hbmp,
  [in, optional] POINT   *pptClient,
                 DWORD   dwSITFlags
);

参数

hwnd

窗口的句柄。 此窗口必须属于调用进程。

hbmp

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

[in, optional] pptClient

选项卡窗口的 客户端区域 (客户端窗口框架内的内容区域的偏移量) 主机窗口的框架。 当在没有框架的情况下绘制选项卡窗口时，此偏移可使选项卡窗口的内容在实时预览中正确绘制。

dwSITFlags

实时预览的显示选项。 此参数可以是 0 或以下值。

DWM_SIT_DISPLAYFRAME (0x00000001)

0x00000001。 在提供的位图周围显示一个框架。

返回值

如果函数成功，则返回 S_OK ，否则返回错误值。 请注意，由于此位图未缓存，因此如果在应用程序调用此函数时未预览窗口，则函数将返回成功代码，但位图将被丢弃且未使用。

注解

当用户将鼠标指针移到任务栏的窗口缩略图上或在 ALT+TAB 窗口中提供缩略图焦点时，将显示窗口的实时预览 (也称为速览预览) 。 此视图是窗口的全尺寸视图，可以是快照或图标表示形式。

窗口通常调用 DwmSetIconicLivePreviewBitmap 函数来响应 WM_DWMSENDICONICLIVEPREVIEWBITMAP 消息。 返回的位图不能大于窗口或框架的工作区，并且必须具有 32 位颜色深度。

桌面窗口管理器 (DWM) 使用位图的副本，但调用方保留原始位图的所有权，并负责在不再需要时释放它使用的资源。 当 DWM 停止显示实时预览表示形式时，DWM 不会保留其位图副本。

示例

若要设置静态的图标位图以用作应用程序窗口的实时预览，应用程序会调用 DwmSetIconicLivePreviewBitmap 函数。 若要设置此位图，应用程序必须调用 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));

然后，应用程序调用 DwmSetIconicLivePreviewBitmap 来响应 WM_DWMSENDICONICLIVEPREVIEWBITMAP 消息，如以下代码所示。

        case WM_DWMSENDICONICLIVEPREVIEWBITMAP:
        {
            // This window is being asked to provide a bitmap to show in Peek preview.
            // This indicates the thumbnail in the taskbar is being previewed.
            RECT rectWindow = {0, 0, 0, 0};
            if (GetClientRect(hwnd, &rectWindow))
            {
                nWidth = rectWindow.right - rectWindow.left;
                nHeight = rectWindow.bottom - rectWindow.top;
            }

            hbm = CreateDIB(nWidth, nHeight);
            if (hbm)
            {
                hr = DwmSetIconicLivePreviewBitmap(hwnd, hbm, NULL, DWM_SIT_DISPLAYFRAME);
                DeleteObject(hbm);
            }
        }
        break;

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

要求

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