DwmSetIconicLivePreviewBitmap, fonction (dwmapi.h)

Article
02/29/2024

Définit une bitmap statique et emblématique pour afficher un aperçu en direct (également appelé aperçu Aperçu) d’une fenêtre ou d’un onglet. La barre des tâches peut utiliser cette bitmap pour afficher un aperçu complet d’une fenêtre ou d’un onglet.

Syntaxe

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

Paramètres

hwnd

Handle de la fenêtre. Cette fenêtre doit appartenir au processus appelant.

hbmp

Handle de la bitmap pour représenter la fenêtre spécifiée par hwnd .

[in, optional] pptClient

Décalage de la région cliente d’une fenêtre d’onglet (la zone de contenu à l’intérieur du cadre de la fenêtre cliente) par rapport au cadre de la fenêtre hôte. Ce décalage permet de dessiner correctement le contenu de la fenêtre d’onglet dans un aperçu dynamique lorsqu’elle est dessinée sans son cadre.

dwSITFlags

Options d’affichage de l’aperçu en direct. Ce paramètre peut être 0 ou la valeur suivante.

DWM_SIT_DISPLAYFRAME (0x00000001)

0x00000001. Affiche un cadre autour de la bitmap fournie.

Valeur retournée

Retourne S_OK si la fonction réussit, ou une valeur d’erreur dans le cas contraire. Notez que, étant donné que cette bitmap n’est pas mise en cache, si la fenêtre n’est pas en cours d’aperçu lorsqu’une application appelle cette fonction, la fonction retourne un code de réussite, mais la bitmap est ignorée et non utilisée.

Remarques

Un aperçu dynamique (également appelé aperçu Aperçu) d’une fenêtre s’affiche lorsqu’un utilisateur déplace le pointeur de la souris sur la miniature de la fenêtre dans la barre des tâches ou donne le focus à la miniature dans la fenêtre ALT+TAB. Cette vue est une vue complète de la fenêtre et peut être une instantané ou une représentation emblématique.

Une fenêtre appelle généralement la fonction DwmSetIconicLivePreviewBitmap en réponse à un message WM_DWMSENDICONICLIVEPREVIEWBITMAP . La bitmap retournée ne doit pas être plus grande que la zone cliente de la fenêtre ou du cadre et doit avoir une profondeur de couleur de 32 bits.

Le Gestionnaire de fenêtres de bureau (DWM) utilise une copie de la bitmap, mais l’appelant conserve la propriété de la bitmap d’origine et est chargé de libérer les ressources qu’il utilise lorsqu’elle n’est plus nécessaire. Le DWM ne conserve pas sa copie de la bitmap lorsque le DWM cesse d’afficher la représentation d’aperçu en direct.

Exemples

Pour définir une bitmap statique et emblématique à utiliser en tant qu’aperçu en direct pour la fenêtre de l’application, une application appelle la fonction DwmSetIconicLivePreviewBitmap . Pour définir cette bitmap, l’application doit appeler DwmSetWindowAttribute pour définir les attributs de fenêtre pour le rendu non client sur DWMWA_FORCE_ICONIC_REPRESENTATION et DWMWA_HAS_ICONIC_BITMAP, comme indiqué dans le code suivant.

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

Ensuite, l’application appelle DwmSetIconicLivePreviewBitmap pour répondre au message WM_DWMSENDICONICLIVEPREVIEWBITMAP , comme indiqué dans le code suivant.

        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;

Pour obtenir l’exemple complet, consultez l’exemple Personnaliser une miniature iconique et un aperçu dynamique bitmap .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	dwmapi.h
Bibliothèque	Dwmapi.lib
DLL	Dwmapi.dll ; Uxtheme.dll

Partager via