Função DwmSetIconicLivePreviewBitmap (dwmapi.h)

Define um bitmap estático e icônico para exibir uma visualização ao vivo (também conhecida como uma visualização Pré-visualizar) de uma janela ou guia. A barra de tarefas pode usar esse bitmap para mostrar uma visualização em tamanho completo de uma janela ou guia.

Sintaxe

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

Parâmetros

[in] hwnd

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

[in] hbmp

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

[in, optional] pptClient

O deslocamento da região do cliente de uma janela de guia (a área de conteúdo dentro do quadro da janela do cliente) do quadro da janela do host. Esse deslocamento permite que o conteúdo da janela de guia seja desenhado corretamente em uma visualização ao vivo quando ele é desenhado sem seu quadro.

[in] dwSITFlags

As opções de exibição para a visualização ao vivo. Esse parâmetro pode ser 0 ou o valor a seguir.

DWM_SIT_DISPLAYFRAME (0x00000001)

0x00000001. Exibe um quadro ao redor do bitmap fornecido.

Retornar valor

Retorna S_OK se a função for bem-sucedida ou um valor de erro, caso contrário. Observe que, como esse bitmap não é armazenado em cache, se a janela não estiver sendo visualizada quando um aplicativo chama essa função, a função retorna um código de êxito, mas o bitmap é descartado e não é usado.

Comentários

Uma visualização ao vivo (também conhecida como visualização Pré-visualizar) de uma janela é exibida quando um usuário move o ponteiro do mouse sobre a miniatura da janela na barra de tarefas ou dá o foco em miniatura na janela ALT+TAB. Essa exibição é uma exibição de tamanho completo da janela e pode ser um instantâneo ou uma representação icônica.

Uma janela normalmente chama a função DwmSetIconicLivePreviewBitmap em resposta a uma mensagem WM_DWMSENDICONICLIVEPREVIEWBITMAP . O bitmap retornado não deve ser maior que a área do cliente da janela ou quadro e deve ter profundidade de cor de 32 bits.

O DWM (Gerenciador de Janelas da Área de Trabalho) usa uma cópia do bitmap, mas 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. O DWM não mantém sua cópia do bitmap quando o DWM para de exibir a representação de visualização ao vivo.

Exemplos

Para definir um bitmap estático e icônico a ser usado como uma visualização ao vivo para a janela do aplicativo, um aplicativo chama a função DwmSetIconicLivePreviewBitmap . Para definir esse bitmap, o aplicativo deve chamar DwmSetWindowAttribute para definir atributos de janela para renderização não cliente como DWMWA_FORCE_ICONIC_REPRESENTATION e DWMWA_HAS_ICONIC_BITMAP, conforme mostrado no código 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 DwmSetIconicLivePreviewBitmap para responder à mensagem WM_DWMSENDICONICLIVEPREVIEWBITMAP , conforme mostrado no código a seguir.

        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;

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	dwmapi.h
Biblioteca	Dwmapi.lib
DLL	Dwmapi.dll; Uxtheme.dll