DwmSetIconicLivePreviewBitmap 函式 (dwmapi.h)

設定靜態圖示位圖，以顯示即時預覽 (也稱為視窗或索引標籤的 預覽 預覽) 。任務欄可以使用這個點陣圖來顯示視窗或索引標籤的完整大小預覽。

語法

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

參數

[in] hwnd

視窗的句柄。 此視窗必須屬於呼叫進程。

[in] hbmp

點陣圖的句柄，表示 hwnd 所指定的視窗。

[in, optional] pptClient

索引標籤視窗的 用戶端區域 位移 (客戶端視窗框架內的內容區域，) 主視窗的框架。 此位移可讓索引標籤視窗的內容在即時預覽中正確繪製，而不會繪製其框架。

[in] 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
程式庫	Dwmapi.lib
Dll	Dwmapi.dll;Uxtheme.dll