Função DwmSetIconicThumbnail (dwmapi.h)

Define um bitmap estático e icônico em uma janela ou guia a ser usado como uma representação em miniatura. A barra de tarefas pode usar esse bitmap como um destino de comutador de miniatura para a janela ou guia.

Sintaxe

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

Parâmetros

[in] hwnd

Um identificador para a janela ou guia. Essa janela deve pertencer ao processo de chamada.

[in] hbmp

Um identificador para o bitmap para representar a janela especificada por hwnd .

[in] dwSITFlags

As opções de exibição para a miniatura. Um dos seguintes valores:

0 (0x00000000)

Nenhum quadro é exibido ao redor da miniatura fornecida.

DWM_SIT_DISPLAYFRAME (0x00000001)

Exibe um quadro ao redor da miniatura fornecida.

Valor retornado

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Um aplicativo normalmente chama a função DwmSetIconicThumbnail depois de receber uma mensagem de WM_DWMSENDICONICTHUMBNAIL para sua janela. A miniatura não deve exceder a coordenada x máxima e a coordenada y especificadas nessa mensagem. A miniatura também deve ter uma profundidade de cor de 32 bits.

O aplicativo chama DwmInvalidateIconicBitmaps para indicar ao DWM (Gerenciador de Janelas da Área de Trabalho) que as miniaturas icônicas e os bitmaps de visualização ao vivo estão desatualizados e devem ser atualizados. Em seguida, o DWM solicita novas versões da janela quando elas são necessárias. No entanto, se o cache de bitmap do DWM estiver cheio, o DWM não solicitará versões atualizadas.

O DWM usa uma cópia do bitmap, mas o aplicativo pode liberar essa cópia a qualquer momento devido a restrições de memória. Se a cópia for liberada, a janela não será notificada, mas poderá receber uma solicitação de WM_DWMSENDICONICTHUMBNAIL subsequente quando sua miniatura for necessária novamente. O chamador retém a propriedade do bitmap original e é responsável por liberar os recursos que ele usa quando não é mais necessário.

Exemplos

Antes de chamar DwmSetIconicThumbnail, o aplicativo deve primeiro chamar a função DwmSetWindowAttribute para definir os atributos DWMWA_FORCE_ICONIC_REPRESENTATION e DWMWA_HAS_ICONIC_BITMAP , conforme mostrado no exemplo a seguir.

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

Em seguida, o aplicativo chama a função DwmSetIconicThumbnail em resposta a uma mensagem WM_DWMSENDICONICTHUMBNAIL , conforme mostrado no exemplo a seguir.

        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;

Para obter o código de exemplo completo, consulte o exemplo Personalizar uma miniatura icônica e um bitmap de visualização ao vivo .

Requisitos