DwmSetIconicThumbnail-Funktion (dwmapi.h)

Artikel
08/23/2023

Legt eine statische, ikonische Bitmap für ein Fenster oder eine Registerkarte fest, die als Miniaturansicht verwendet werden soll. Die Taskleiste kann diese Bitmap als Miniaturansichtswechselziel für das Fenster oder die Registerkarte verwenden.

Syntax

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

Parameter

[in] hwnd

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

[in] hbmp

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

[in] dwSITFlags

Die Anzeigeoptionen für die Miniaturansicht. Einer der folgenden Werte:

0 (0x00000000)

Um die bereitgestellte Miniaturansicht wird kein Frame angezeigt.

DWM_SIT_DISPLAYFRAME (0x00000001)

Zeigt einen Rahmen um die bereitgestellte Miniaturansicht an.

Rückgabewert

Wenn diese Funktion erfolgreich ist, gibt sie S_OK zurück. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Eine Anwendung ruft in der Regel die DwmSetIconicThumbnail-Funktion auf, nachdem sie eine WM_DWMSENDICONICTHUMBNAIL Nachricht für ihr Fenster empfangen hat. Die Miniaturansicht sollte die maximale x- und y-Koordinate, die in dieser Nachricht angegeben sind, nicht überschreiten. Die Miniaturansicht muss auch eine Farbtiefe von 32 Bit aufweisen.

Die Anwendung ruft DwmInvalidateIconicBitmaps auf, um dem Desktopfenster-Manager (DWM) mitzuteilen, dass die ikonischen Miniaturansichten und Livevorschau-Bitmaps veraltet sind und aktualisiert werden sollten. Der DWM fordert dann neue Versionen aus dem Fenster an, wenn sie benötigt werden. Wenn der DWM-Bitmapcache jedoch voll ist, fordert DWM keine aktualisierten Versionen an.

Der DWM verwendet eine Kopie der Bitmap, aber die Anwendung kann diese Kopie aufgrund von Speichereinschränkungen jederzeit freigeben. Wenn die Kopie freigegeben wird, wird das Fenster nicht benachrichtigt, aber es erhält möglicherweise eine nachfolgende WM_DWMSENDICONICTHUMBNAIL Anforderung, wenn die Miniaturansicht erneut benötigt wird. 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.

Beispiele

Vor dem Aufruf von DwmSetIconicThumbnail muss die Anwendung zuerst die DwmSetWindowAttribute-Funktion aufrufen, um die Attribute DWMWA_FORCE_ICONIC_REPRESENTATION und DWMWA_HAS_ICONIC_BITMAP festzulegen, wie im folgenden Beispiel 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));

Als Nächstes ruft die Anwendung die DwmSetIconicThumbnail-Funktion als Antwort auf eine WM_DWMSENDICONICTHUMBNAIL-Nachricht auf, wie im folgenden Beispiel gezeigt.

        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;

Den vollständigen Beispielcode finden Sie im Beispiel Anpassen einer ikonischen Miniaturansicht und einer Livevorschau-Bitmap .

Anforderungen


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