B# .NET Blog

DwmQueryThumbnailSourceSize

Want to know the size of the target window associated with a given thumbnail (in order to decide on scaling of the thumbnail in the call to DwmUpdateThumbnailProperties)? Use this function:

HRESULT DwmQueryThumbnailSourceSize(      
    HTHUMBNAIL hThumbnail,
    PSIZE pSize
);

Or in C# speak:

[DllImport("dwmapi.dll")]
static extern int DwmQueryThumbnailSourceSize(IntPtr thumb, out PSIZE size);

The PSIZE object is a struct containing the width (x) and height (y) of the window associated with the thumbnail (thumb) and serves as the function's output value:

[StructLayout(LayoutKind.Sequential)]
internal struct PSIZE
{
   public int x;
   public int y;
}

DwmUpdateThumbnailProperties

The last and maybe the most important function is this one. It's used to configure the thumbnail properties. By doing so, the DWM knows what kind of thumbnail you want to receive (opaque, format, source window region, etc).

HRESULT DwmUpdateThumbnailProperties(      
    HTHUMBNAIL hThumbnailId,
    const DWM_THUMBNAIL_PROPERTIES *ptnProperties
);

Its translation to C# looks like this:

[DllImport("dwmapi.dll")]
static extern int DwmUpdateThumbnailProperties(IntPtr hThumb, ref DWM_THUMBNAIL_PROPERTIES props);

where DWM_THUMBNAIL_PROPERTIES is defined as a struct:

[StructLayout(LayoutKind.Sequential)]
internal struct DWM_THUMBNAIL_PROPERTIES
{
   public int dwFlags;
   public Rect rcDestination;
   public Rect rcSource;
   public byte opacity;
   public bool fVisible;
   public bool fSourceClientAreaOnly;
}

[StructLayout(LayoutKind.Sequential)]
internal struct Rect
{
   internal Rect(int left, int top, int right, int bottom)
   {
      Left = left;
      Top = top;
      Right = right;
      Bottom = bottom;
   }

   public int Left;
   public int Top;
   public int Right;
   public int Bottom;
}

The Rect struct is used to pass rectangle coordinates (left top, right bottom). You could use the Rectangle class of the .NET Framework too because it has the same layout, but this would make things a bit less clear, since the Rectangle class uses Left, Width, Top, Height values.

A simple sample

Time to build a simple demo application. Start by performing the following steps:

1. Create a new C# Windows Forms project.
2. Modify Form1 to have the following layout:
   
   
   
• Title label
• Combobox lstWindows with DropDownList behavior (anchored to Top and Right)
• Refresh button btnRefresh (anchored to Top and Right)
• PictureBox image anchored to Top, Left, Right and Bottom; used to auto-calculate the available space (this is not going to be the drawing region used by the DWM since the DWM always works through the handle to the window itself and not an individual control)
• TrackBar control opacity for the opacity slider at the bottom, ranging from 0 to 255 with 255 set as the default value (anchored to Left and Bottom).
3. Add the static interop methods mentioned in the previous paragraph to the class.
4. Add the interop structs to the project, in a separate code file or at the bottom of the form1.cs file.

Getting all the visible windows

The first thing we need to add to the project is a method that's able to find out about all the visible windows in the user's session and to obtain the required handles to those windows. We use the following function to do this:

private List<Window> windows;

private void GetWindows()
{
   windows = new List<Window>();

   EnumWindows(Callback, 0);

   lstWindows.Items.Clear();
   foreach (Window w in windows)
      lstWindows.Items.Add(w);
}

private bool Callback(IntPtr hwnd, int lParam)
{
   if (this.Handle != hwnd && (GetWindowLongA(hwnd, GWL_STYLE) & TARGETWINDOW) == TARGETWINDOW)
   {
      StringBuilder sb = new StringBuilder(200);
      GetWindowText(hwnd, sb, sb.Capacity);
      Window t = new Window();
      t.Handle = hwnd;
      t.Title = sb.ToString();
      windows.Add(t);
   }

   return true; //continue enumeration
}

The GetWindows method is responsible to populate the lstWindows combobox. To do this, it relies on EnumWindows, a user32 function that uses a callback mechanism to list windows (as an alternative to iterator-based functions like GetWindow which can be error-prone):

[DllImport("user32.dll")]
static extern int EnumWindows(EnumWindowsCallback lpEnumFunc, int lParam);

with the callback defined through a delegate (based on the EnumWindowsProc callback in the Windows SDK):

delegate bool EnumWindowsCallback(IntPtr hwnd, int lParam);

Our Callback method matches the delegate's signature and can be passed to EnumWindows. The lParam parameter isn't used (it serves as a parameter passing mechanism to the callback).

In the Callback method we obtain the handle to the window (passed as the hwnd parameter) and query the window title text using GetWindowText:

[DllImport("user32.dll")]
public static extern void GetWindowText(IntPtr hWnd, StringBuilder lpString, int nMaxCount);

Notice the use of System.Text.StringBuilder when coping with strings through interop. Another function used is GetWindowLongA to get additional information about the window passed to the callback function:

[DllImport("user32.dll")]
static extern ulong GetWindowLongA(IntPtr hWnd, int nIndex);

Using the GWL_STYLE constant we ask for style properties which are matched against another custom constant "TARGETWINDOW" that combines the visibility (WS_VISIBLE) and border (WS_BORDER) properties of the window:

static readonly int GWL_STYLE = -16;

static readonly ulong WS_VISIBLE = 0x10000000L;
static readonly ulong WS_BORDER = 0x00800000L;
static readonly ulong TARGETWINDOW = WS_BORDER | WS_VISIBLE;

Finally there is the Window helper class to keep the handle and the friendly name (i.e. the window title):

internal class Window
{
   public string Title;
   public IntPtr Handle;

   public override string ToString()
   {
      return Title;
   }
}

Loading and refreshing the window list

We'll display the window list upon loading the form:

and refresh the list when the Refresh button is clicked:

In order to obtain thumbnails we need to register our interest to receive a thumbnail as explained earlier. We keep the thumbnail in a private variable:

private IntPtr thumb;

To set the thumbnail we use the SelectedIndexChanged event of the combobox:

private void lstWindows_SelectedIndexChanged(object sender, EventArgs e)
{
   Window w = (Window)lstWindows.SelectedItem;
   if (thumb != IntPtr.Zero)
      DwmUnregisterThumbnail(thumb);

   int i = DwmRegisterThumbnail(this.Handle, w.Handle, out thumb);
   if (i == 0)
      UpdateThumb();
}

In case a thumbnail was already selected, we unregister our further interest in it. This will stop the DWM to render the thumbnail to the current window. Then, we register to receive the thumbnail of the selected window (obtained by means of the SelectedItem property of the combobox) in the current window (this.Handle). This causes a thumbnail pointer to be returned by the output parameter, which sets the thumb private variable.