DwmSetIconicLivePreviewBitmap-Funktion (dwmapi.h)

Artikel
02/26/2024

Legt eine statische, ikonische Bitmap fest, um eine Livevorschau (auch als Peek Vorschau bezeichnet) eines Fensters oder einer Registerkarte anzuzeigen. Die Taskleiste kann diese Bitmap verwenden, um eine vollständige Vorschau eines Fensters oder einer Registerkarte anzuzeigen.

Syntax

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

Parameter

hwnd

Ein Handle für das Fenster. Dieses Fenster muss zum aufrufenden Prozess gehören.

hbmp

Ein Handle für die Bitmap, um das Fenster darzustellen, das hwnd angibt.

[in, optional] pptClient

Der Offset der Clientregion eines Registerkartenfensters (der Inhaltsbereich innerhalb des Clientfensterrahmens) aus dem Frame des Hostfensters. Mit diesem Offset kann der Inhalt des Registerkartenfensters in einer Livevorschau ordnungsgemäß gezeichnet werden, wenn es ohne seinen Rahmen gezeichnet wird.

dwSITFlags

Die Anzeigeoptionen für die Livevorschau. Dieser Parameter kann 0 oder der folgende Wert sein.

DWM_SIT_DISPLAYFRAME (0x00000001)

0x00000001. Zeigt einen Frame um die bereitgestellte Bitmap an.

Rückgabewert

Gibt S_OK zurück, wenn die Funktion erfolgreich ist, oder andernfalls einen Fehlerwert. Beachten Sie, dass die Funktion einen Erfolgscode zurückgibt, aber die Bitmap wird verworfen und nicht verwendet, da diese Bitmap nicht zwischengespeichert wird, wenn das Fenster nicht in der Vorschau angezeigt wird, wenn eine Anwendung diese Funktion aufruft.

Hinweise

Eine Livevorschau (auch als Peek Vorschau bezeichnet) eines Fensters wird angezeigt, wenn ein Benutzer den Mauszeiger auf die Miniaturansicht des Fensters in der Taskleiste bewegt oder die Miniaturansicht im ALT+TAB-Fenster fokussiert. Diese Ansicht ist eine vollständige Ansicht des Fensters und kann eine Momentaufnahme oder eine ikonische Darstellung sein.

Ein Fenster ruft normalerweise die DwmSetIconicLivePreviewBitmap-Funktion als Reaktion auf eine WM_DWMSENDICONICLIVEPREVIEWBITMAP-Nachricht auf. Die zurückgegebene Bitmap darf nicht größer als der Clientbereich des Fensters oder Rahmens sein und muss eine Farbtiefe von 32 Bit aufweisen.

Der Desktopfenster-Manager (DWM) verwendet eine Kopie der Bitmap, aber der Aufrufer behält den Besitz der ursprünglichen Bitmap und ist für die Freigabe der ressourcen verantwortlich, die er verwendet, wenn sie nicht mehr benötigt wird. Der DWM behält seine Kopie der Bitmap nicht bei, wenn die DWM die Livevorschaudarstellung nicht mehr anzeigt.

Beispiele

Um eine statische, ikonische Bitmap festzulegen, die als Livevorschau für das Anwendungsfenster verwendet werden soll, ruft eine Anwendung die DwmSetIconicLivePreviewBitmap-Funktion auf. Um diese Bitmap festzulegen, muss die Anwendung DwmSetWindowAttribute aufrufen, um Fensterattribute für das Nichtclientrendering auf DWMWA_FORCE_ICONIC_REPRESENTATION und DWMWA_HAS_ICONIC_BITMAP festzulegen, wie im folgenden Code gezeigt.

            // 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));

Anschließend ruft die Anwendung DwmSetIconicLivePreviewBitmap auf, um auf die WM_DWMSENDICONICLIVEPREVIEWBITMAP Nachricht zu reagieren, wie im folgenden Code gezeigt.

        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;

Das vollständige Beispiel finden Sie im Beispiel Anpassen einer ikonischen Miniaturansicht und einer Livevorschau-Bitmap .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	dwmapi.h
Bibliothek	Dwmapi.lib
DLL	Dwmapi.dll; Uxtheme.dll

Freigeben über