Función DwmSetIconicLivePreviewBitmap (dwmapi.h)

Establece un mapa de bits estático e emblemático para mostrar una vista previa en directo (también conocida como Vistazo vista previa) de una ventana o pestaña. La barra de tareas puede usar este mapa de bits para mostrar una vista previa de tamaño completo de una ventana o pestaña.

Sintaxis

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

Parámetros

[in] hwnd

Un identificador de la ventana. Esta ventana debe pertenecer al proceso de llamada.

[in] hbmp

Identificador del mapa de bits para representar la ventana que hwnd especifica.

[in, optional] pptClient

Desplazamiento de la región de cliente de una ventana de pestaña (el área de contenido dentro del marco de la ventana de cliente) desde el marco de la ventana host. Este desplazamiento permite que el contenido de la ventana de tabulación se dibuje correctamente en una vista previa activa cuando se dibuja sin su marco.

[in] dwSITFlags

Las opciones de visualización de la versión preliminar en directo. Este parámetro puede ser 0 o el valor siguiente.

DWM_SIT_DISPLAYFRAME (0x00000001)

0x00000001. Muestra un marco alrededor del mapa de bits proporcionado.

Valor devuelto

Devuelve S_OK si la función se ejecuta correctamente o un valor de error de lo contrario. Tenga en cuenta que, dado que este mapa de bits no está almacenado en caché, si la ventana no se está previsualizando cuando una aplicación llama a esta función, la función devuelve un código correcto, pero el mapa de bits se descarta y no se usa.

Comentarios

Aparece una vista previa dinámica (también conocida como vista previa Vistazo) de una ventana cuando un usuario mueve el puntero del mouse sobre la miniatura de la ventana en la barra de tareas o proporciona el foco en miniatura en la ventana ALT+TAB. Esta vista es una vista de tamaño completo de la ventana y puede ser una instantánea o una representación emblemática.

Normalmente, una ventana llama a la función DwmSetIconicLivePreviewBitmap en respuesta a un mensaje de WM_DWMSENDICONICLIVEPREVIEWBITMAP . El mapa de bits devuelto no debe ser mayor que el área cliente de la ventana o marco y debe tener profundidad de color de 32 bits.

El Administrador de ventanas de escritorio (DWM) usa una copia del mapa de bits, pero el autor de la llamada conserva la propiedad del mapa de bits original y es responsable de liberar los recursos que usa cuando ya no es necesario. El DWM no mantiene su copia del mapa de bits cuando DWM deja de mostrar la representación en vista previa activa.

Ejemplos

Para establecer un mapa de bits estático e emblemático que se usará como vista previa en directo para la ventana de la aplicación, una aplicación llama a la función DwmSetIconicLivePreviewBitmap . Para establecer este mapa de bits, la aplicación debe llamar a DwmSetWindowAttribute para establecer atributos de ventana para la representación que no es de cliente en DWMWA_FORCE_ICONIC_REPRESENTATION y DWMWA_HAS_ICONIC_BITMAP, como se muestra en el código siguiente.

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

A continuación, la aplicación llama a DwmSetIconicLivePreviewBitmap para responder al mensaje WM_DWMSENDICONICLIVEPREVIEWBITMAP , como se muestra en el código siguiente.

        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 obtener el ejemplo completo, consulta el ejemplo Personalizar una miniatura icónica y un mapa de bits de vista previa dinámica .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	dwmapi.h
Library	Dwmapi.lib
Archivo DLL	Dwmapi.dll; Uxtheme.dll