Funzione DwmSetIconicThumbnail (dwmapi.h)

Articolo
03/14/2023

Imposta una bitmap statica e iconica su una finestra o una scheda da usare come rappresentazione di anteprima. La barra delle applicazioni può usare questa bitmap come destinazione dell'opzione di anteprima per la finestra o la scheda.

Sintassi

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

Parametri

[in] hwnd

Handle nella finestra o nella scheda. Questa finestra deve appartenere al processo chiamante.

[in] hbmp

Handle della bitmap per rappresentare la finestra specificata da hwnd .

[in] dwSITFlags

Opzioni di visualizzazione per l'anteprima. Uno dei valori seguenti:

0 (0x00000000)

Nessun frame viene visualizzato intorno all'anteprima fornita.

DWM_SIT_DISPLAYFRAME (0x00000001)

Visualizza una cornice intorno all'anteprima fornita.

Valore restituito

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Un'applicazione chiama in genere la funzione DwmSetIconicThumbnail dopo aver ricevuto un messaggio di WM_DWMSENDICONICTHUMBNAIL per la relativa finestra. L'anteprima non deve superare la coordinata x massima e la coordinata y specificata in tale messaggio. L'anteprima deve avere anche una profondità di colore a 32 bit.

L'applicazione chiama DwmInvalidateIconicBitmaps per indicare a Desktop Window Manager (DWM) che le bitmap di anteprima e anteprima live iconiche sono non aggiornate e devono essere aggiornate. Il DWM richiede quindi nuove versioni dalla finestra quando sono necessarie. Tuttavia, se la cache bitmap DWM è completa, DWM non richiede versioni aggiornate.

DWM usa una copia della bitmap, ma l'applicazione può rilasciare questa copia in qualsiasi momento a causa dei vincoli di memoria. Se la copia viene rilasciata, la finestra non viene notificata, ma potrebbe ricevere una richiesta di WM_DWMSENDICONICTHUMBNAIL successiva quando è necessaria di nuovo l'anteprima. Il chiamante mantiene la proprietà della bitmap originale ed è responsabile della liberazione delle risorse usate quando non è più necessario.

Esempio

Prima di chiamare DwmSetIconicThumbnail, l'applicazione deve prima chiamare la funzione DwmSetWindowAttribute per impostare gli attributi DWMWA_FORCE_ICONIC_REPRESENTATION e DWMWA_HAS_ICONIC_BITMAP , come illustrato nell'esempio seguente.

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

Successivamente, l'applicazione chiama la funzione DwmSetIconicThumbnail in risposta a un messaggio di WM_DWMSENDICONICTHUMBNAIL , come illustrato nell'esempio seguente.

        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;

Per il codice di esempio completo, vedere Personalizzare un'anteprima iconica e un esempio bitmap di anteprima live .

Requisiti


Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	dwmapi.h
Libreria	Dwmapi.lib
DLL	Dwmapi.dll; Uxtheme.dll

Share via